# example-mcp-sse

migration-focused starter for building MCP servers on Streamable HTTP, replacing the deprecated SSE transport. uses TypeScript SDK v2 pre-alpha.

> part of a series: [stdio](https://github.com/yigitkonur/example-mcp-stdio) · [stateless](https://github.com/yigitkonur/example-mcp-stateless) · [stateful](https://github.com/yigitkonur/example-mcp-stateful) · **sse** (you are here)

## what it does

- runnable Streamable HTTP server with session management, event replay, and graceful shutdown
- scaffold CLI (`create-mcp-streamable-starter` / `create-mcp-sse-starter`) to generate new projects from a proven template
- calculator demo with tools, resources, prompts, and structured output to exercise all MCP primitives
- vendored SDK v2 alpha tarballs for reproducible installs without npm registry dependency
- smoke tests for both the root project and scaffolded output
- CI workflow that validates root build, lint, typecheck, and generated project end-to-end

## quick start

```bash
npm install
npm run dev
```

the server starts at `http://127.0.0.1:3000` with these endpoints:

| endpoint  | method         | purpose                              |
|-----------|----------------|--------------------------------------|
| `/mcp`    | POST           | JSON-RPC request/response            |
| `/mcp`    | GET            | notification stream (stateful SSE)   |
| `/mcp`    | DELETE         | session termination                  |
| `/health` | GET            | health check with active session list|
| `/`       | GET            | server metadata                      |

configure with environment variables or CLI flags:

```bash
PORT=4000 npm run dev
# or
npm run dev -- --port 4000
```

## scaffold cli

generate a new MCP Streamable HTTP project:

```bash
npm run create -- --name my-server --target ./my-server
cd my-server
npm install
npm run dev
```

the generated project includes the full server module structure, vendored SDK tarballs, and its own smoke test. see [docs/03-scaffold-cli.md](docs/03-scaffold-cli.md) for the complete reference.

## documentation

| doc | description |
|-----|-------------|
| [docs/README.md](docs/README.md) | documentation hub and reading order |
| [docs/01-getting-started.md](docs/01-getting-started.md) | prerequisites, install, run, verify |
| [docs/02-architecture.md](docs/02-architecture.md) | module layout, request lifecycle, design rationale |
| [docs/03-scaffold-cli.md](docs/03-scaffold-cli.md) | CLI reference, generated structure, extension workflow |
| [docs/04-sdk-v2-notes.md](docs/04-sdk-v2-notes.md) | v2 packages, migration checklist, vendoring strategy |
| [docs/05-validation.md](docs/05-validation.md) | root and generated project validation, release checklist |

## sdk v2 context

this project targets the MCP TypeScript SDK v2 pre-alpha (`2.0.0-alpha.0`). v2 splits the monolithic `@modelcontextprotocol/sdk` into `@modelcontextprotocol/server`, `@modelcontextprotocol/client`, and `@modelcontextprotocol/node`. the server-side `SSEServerTransport` is removed; `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node` is the replacement. v1.x remains the stable production recommendation from the upstream project. vendored tarballs in `vendor/` pin the exact alpha artifacts for reproducible builds.

## license

MIT