# MCP Ecosystem

Sourcey's MCP support is built on two standalone npm packages published under the [sourcey](https://github.com/sourcey) org. They're useful independently of sourcey for any project that works with MCP server specifications.


## mcp-schema {#mcp-schema}


TypeScript types and JSON Schema for the `mcp.json` snapshot format.

```bash
npm install mcp-schema
```

```typescript
import type { McpSpec, McpTool, McpResource } from "mcp-schema";
import { mcpSpecSchema } from "mcp-schema/schema";
```

Provides typed interfaces for the full MCP surface: tools (with `inputSchema`, `outputSchema`, annotations), resources, resource templates, prompts, server capabilities, and transport configuration. The JSON Schema can be used with any validator (Ajv, Zod, etc.).

Zero runtime dependencies.

- [GitHub](https://github.com/sourcey/mcp-schema)
- [npm](https://www.npmjs.com/package/mcp-schema)


## mcp-parser {#mcp-parser}


Snapshot, parse, validate, and document MCP server specifications.

```bash
npm install mcp-parser
```

```typescript
import { parse, validate, snapshot, generateMarkdown } from "mcp-parser";

const spec = await parse("./mcp.json");
const result = validate(spec);
const markdown = generateMarkdown(spec);
```


### API {#api}


| Function | Description |
| --- | --- |
| `parse(path)` | Parse an `mcp.json` file with `$ref` dereferencing |
| `parseString(json)` | Parse from a JSON string |
| `validate(spec)` | Check for errors and best-practice warnings |
| `snapshot(options)` | Connect to a running server and capture a snapshot |
| `generateMarkdown(spec)` | Generate a full markdown reference |
| `generateLlmsTxt(spec)` | Generate a compact llms.txt-style index |
| `generateLlmsFullTxt(spec)` | Generate a full-text context reference |


### CLI {#cli}


```bash
mcp-parser parse ./mcp.json
mcp-parser validate ./mcp.json
mcp-parser snapshot --stdio "node server.js" -o mcp.json
mcp-parser snapshot --sse http://localhost:3000/sse -o mcp.json
mcp-parser snapshot --http http://localhost:3000/mcp -o mcp.json
mcp-parser generate ./mcp.json -o mcp.md
mcp-parser generate ./mcp.json --format llms-txt -o llms.txt
```

Depends on `mcp-schema` for types.

- [GitHub](https://github.com/sourcey/mcp-parser)
- [npm](https://www.npmjs.com/package/mcp-parser)


## How they fit into sourcey {#how-they-fit-into-sourcey}


Sourcey depends on `mcp-parser` (which brings `mcp-schema` transitively). When you add an `mcp` tab to your config, sourcey uses `mcp-parser` to parse the `mcp.json` file and then normalizes it into the same internal format used for OpenAPI specs. The rendering pipeline, search, navigation, and theming work identically.

You don't need to install `mcp-parser` or `mcp-schema` separately to use MCP tabs in sourcey. They're included as dependencies.


## MCP protocol revisions {#mcp-protocol-revisions}


Three different things sit behind this question, and they answer it differently.

**The `mcp.json` format** (`mcp-schema`) is revision-independent. It records which
revision a snapshot came from, validating it as a `YYYY-MM-DD` shape rather than
against a list of known revisions, so a document produced against a revision
newer than the package still validates.

**The snapshot client** (`mcp-parser`) requests `2025-11-25` by default and, from
0.4.2, any other revision on request. A handshake revision is offered in `initialize`, and
later requests declare the revision the server negotiates. A stateless revision
(`2026-07-28` and later) is declared on every request in `_meta`, and the
snapshot reads `server/discover` instead of `initialize`, recording the
server's supported revisions as `mcpVersions`.

**The hosted Sourcey MCP server** at `mcp.sourcey.com/mcp` works with every MCP
client on Streamable HTTP. It serves every published revision on one endpoint:

| Revisions | How a client connects |
| --- | --- |
| `2026-07-28` | Stateless: the revision travels in `_meta` and in the `MCP-Protocol-Version`, `Mcp-Method`, and `Mcp-Name` headers; `server/discover` describes the server |
| `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` | `initialize` negotiates the revision; later requests declare it, or omit the header |

A revision outside that set is refused with `400` and the complete set of
revisions the server serves, so a client can retry with one it shares. Each
request carries one JSON-RPC message; batches are refused. The hosted manifest
at `mcp.sourcey.com/mcp.json` lists the same set as `mcpVersions`, and the set
is declared once in Sourcey's MCP contract. Every deploy's live check proves
each declared revision and rolls the release back on any failure, and
`mcp-parser` can snapshot the endpoint at any of them.


## MCP specification resources {#mcp-specification-resources}


- [MCP Specification](https://modelcontextprotocol.io/specification/2026-07-28) (current revision)
- [MCP Specification `2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25) (the newest handshake revision)
- [Specification repo](https://github.com/modelcontextprotocol/specification)
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) (`@modelcontextprotocol/sdk`)
- [Python SDK](https://github.com/modelcontextprotocol/python-sdk) (`mcp` on PyPI)