Skip to content

README.md

Latest commit

 

History

History
164 lines (124 loc) · 5.1 KB

README.md

File metadata and controls

164 lines (124 loc) · 5.1 KB

MCP Server Template (TypeScript)

A minimal Model Context Protocol server template for Render. Fork it, add your own tools, and deploy.

What's included

  • A working MCP server using the official TypeScript SDK with Streamable HTTP transport
  • Bearer token authentication via MCP_API_TOKEN (auto-generated on deploy)
  • One example tool (hello) to show the pattern
  • A /health endpoint for Render's health checks
  • A render.yaml Blueprint for one-click deployment
  • An AGENTS.md so AI coding assistants can scaffold new tools for you

Note: This template deploys on the free plan by default. Free services spin down after 15 minutes of inactivity, causing cold starts of 30-60 seconds on the next request. MCP clients may time out during this delay. For reliable use, upgrade to a paid plan in the Render Dashboard — the Starter plan keeps your service running continuously.

Getting started locally

git clone https://github.com/render-examples/mcp-server-typescript.git
cd mcp-server-typescript
npm install
npm run build
npm start

The server starts on http://localhost:10000. The MCP endpoint is at /mcp.

Running tests

npm install
npm test

Authentication

The server authenticates requests using a bearer token. Render's Blueprint auto-generates a random MCP_API_TOKEN on first deploy.

To find your token after deploying, go to Render Dashboard > your service > Environment and copy the MCP_API_TOKEN value.

Clients must include the token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

When MCP_API_TOKEN is not set (e.g., during local development), authentication is disabled and all requests are allowed through.

Managing your token

After the initial deploy, the token is yours to manage:

  • Rotate it by updating MCP_API_TOKEN in the Render Dashboard under Environment. The service restarts automatically with the new value.
  • Generate a new token with any of these:
    • openssl rand -base64 32
    • node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
    • A password manager's generator (1Password, Bitwarden, etc.)
  • Don't commit tokens to source control. Use environment variables or .env files (which are in .gitignore).
  • For multi-user or production setups, consider upgrading to OAuth 2.1.

Connecting to your MCP server

After deploying to Render, your MCP endpoint is available at:

https://your-service-name.onrender.com/mcp

Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://your-service-name.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "streamable-http",
      "url": "https://your-service-name.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Codex

codex mcp add --transport streamable-http \
  --url https://your-service-name.onrender.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  my-mcp-server

Or add to .codex/config.toml:

[mcp_servers.my-mcp-server]
url = "https://your-service-name.onrender.com/mcp"
http_headers = { Authorization = "Bearer YOUR_TOKEN" }

Adding tools

Add tools inside the createServer() function in src/app.ts:

server.registerTool(
  "fetch-weather",
  {
    description: "Get the current weather for a city",
    inputSchema: {
      city: z.string(),
      units: z.string().default("celsius"),
    },
  },
  async ({ city, units }) => ({
    content: [{ type: "text", text: `Weather for ${city} in ${units}` }],
  }),
);

The description is what MCP clients show to LLMs. Always write a clear one.

This repo includes an AGENTS.md file. If you use an AI coding assistant (Cursor, Copilot, Codex, Windsurf, etc.), you can ask it to "add a new tool" and it will follow the conventions in AGENTS.md automatically.

Project structure

src/app.ts               App setup: tools, auth middleware, routes
src/server.ts            Entrypoint: imports app and starts listening
package.json             Dependencies and scripts
tsconfig.json            TypeScript compiler configuration
render.yaml              Render Blueprint for deployment
.env.example             Environment variable reference
tests/server.test.ts     Test suite (auth, health, tool calls)
vitest.config.ts         Vitest configuration
AGENTS.md                Instructions for AI coding assistants
CLAUDE.md                Pointer to AGENTS.md for Claude Code

Learn more