# mcp-server-starter-kit

A **production-shaped** starter for building a [Model Context Protocol](https://modelcontextprotocol.io) server in TypeScript.

Most MCP tutorials stop at "hello world" over stdio. The hard parts — the ones that actually break servers in the wild — start right after: authentication, transport choice, request timeouts, SSRF guards, and a deploy that survives cold starts. This kit ships those, small enough to read in one sitting.

> The MCP protocol is the easy part. Everything *around* it is where servers die. This kit is that "everything around it," kept minimal and honest.

- **stdio + streamable HTTP**, switched by one env var.
- **Bearer auth that fails closed** — no token configured means every HTTP request is rejected, with a real `401` + `WWW-Authenticate`, constant-time comparison, and the token never logged.
- **Legible errors** — a typed `ToolError` becomes a proper MCP error result (`isError: true`), so an agent sees `[forbidden_host] ...` instead of a silent hang or an opaque `internal error`.
- **A real example tool** (`http_get_json`) with the guards every fetch tool needs and most omit: input validation, https-only, an SSRF host allowlist, and a hard timeout.
- **Stateless HTTP by design** — the shape that survives serverless cold starts (see [`DEPLOYMENT.md`](./DEPLOYMENT.md)).
- **Tests + typecheck** out of the box (a drop-in GitHub Actions CI is in [`DEPLOYMENT.md`](./DEPLOYMENT.md)).

---

## Quickstart (stdio, ~60 seconds)

```bash
git clone https://github.com/park11innyc-lgtm/mcp-server-starter-kit
cd mcp-server-starter-kit
npm install
cp .env.example .env
npm run dev          # starts on stdio; logs "ready on stdio" to stderr
```

Point Claude Desktop / Cursor at it — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "starter-kit": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-server-starter-kit/src/index.ts"]
    }
  }
}
```

Restart the client and you'll have two tools: `ping` and `http_get_json`.

## Run it remotely (streamable HTTP + auth)

```bash
# generate a token
node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"

# put it in .env  ->  MCP_BEARER_TOKENS=<that token>
npm run serve:http   # POST http://localhost:3000/mcp   (GET /healthz is open)
```

Every request to `/mcp` now needs `Authorization: Bearer <token>`. With **no** token set, the server refuses everything — that "fail closed" default is the point.

---

## The two example tools

| Tool | What it shows |
|------|---------------|
| `ping` | The minimum viable tool: zero input, structured JSON out. Use it as your liveness check. |
| `http_get_json` | The patterns a real outbound tool needs — zod input validation, an https-only rule, an **SSRF allowlist** (`ALLOWED_FETCH_HOSTS`), and an `AbortController` timeout — with every failure mapped to a typed error. |

Add your own in `src/tools.ts` and register it in `src/server.ts`. The `try/catch → toToolResult` wrapper there is what keeps your failures legible; keep using it.

## The parts tutorials skip (and where they live)

- **Auth that fails closed** → [`src/auth.ts`](./src/auth.ts). Bearer tokens are the correct *first* step; full delegated OAuth 2.1 is a deliberate non-goal of a starter — [`DEPLOYMENT.md`](./DEPLOYMENT.md) points at where to add it.
- **stdout is sacred on stdio** → [`src/index.ts`](./src/index.ts). One stray `console.log` corrupts the JSON-RPC stream. Log to **stderr** only.
- **Cold starts** → [`src/http.ts`](./src/http.ts) is stateless on purpose. [`DEPLOYMENT.md`](./DEPLOYMENT.md) explains why and when to add sessions.
- **SSRF** → an MCP tool that fetches URLs is an open proxy into your network unless you allowlist hosts. `http_get_json` does.

## Layout

```
src/
  index.ts    entry — picks stdio vs http
  server.ts   builds the McpServer, registers tools, wraps handlers
  tools.ts    the example tools (add yours here)
  auth.ts     bearer auth for the HTTP transport (fail closed)
  http.ts     stateless streamable-HTTP server
  errors.ts   ToolError + toToolResult
test/
  tools.test.ts
```

## Scripts

```bash
npm run dev         # stdio, hot
npm run serve:http  # http transport
npm run build       # tsc -> dist/
npm start           # run built server
npm test            # vitest
npm run typecheck   # tsc --noEmit
```

## License

MIT — do whatever you want with it. Attribution appreciated, not required.

---

<sub>Built as an honest reference, not a paywall. A production companion focused on **ops automation** (retry/dedup, cost caps, runbooks) is in the works — a link will land here when it ships.</sub>