MCP reference servers: what they demonstrate and what they omit

modelcontextprotocol/servers is the reference collection for the Model Context Protocol: seven small servers kept by the MCP steering group, each written to demonstrate one part of the protocol rather than to do a job well. Read as a product it is teaching material with an unusually candid README, and the position taken here is that it should be read and run locally but never deployed: the repository states outright that the servers are not production-ready, and its security policy refuses vulnerability reports against it. What it does well is show exactly what a server has to implement, in working code, from the people who wrote the specification.

It sits between the specification on modelcontextprotocol.io and the ten official SDKs, and it does not compete with the MCP Registry, where published servers for actual use are listed. Nothing here replaces a search index, a browser tool or a ticketing integration. The collection replaced an earlier grab-bag of one-off examples, most of which now live in a separate archive repository and still turn up in old tutorials.

What it is

One npm workspace holding seven packages under src/, published on npm as @modelcontextprotocol/server-* and on PyPI as mcp-server-*. Four servers are TypeScript and three are Python, and each isolates a different protocol feature: access control, prompts and resources, a knowledge graph, a tool that rewrites its own output, web retrieval, repository operations, time zones.

• About 91,100 stars and 11,800 forks in early October 2026, with 4,194 commits on main.
• Seven reference servers in src/: everything, fetch, filesystem, git, memory, sequentialthinking and time.
• Thirteen retired servers, including GitHub, Slack, PostgreSQL, SQLite, Puppeteer and Brave Search, moved to servers-archived; the Brave one was replaced by a server Brave maintains itself.
• The README now sends anyone looking for a server to the MCP Registry and keeps the repository for the reference implementations only.
• Licence is Apache-2.0 for new contributions with earlier code still under MIT, as the LICENSE file explains.
• Server packages use calendar versions: 2026.8.31 for the TypeScript packages, 2026.8.18 for the Python ones.
• Packages are published from a gated CI workflow by OIDC trusted publishing with provenance attestations, and the release path contains no registry tokens.

The repository, server by server

The layout is deliberately flat: one directory per server under src/, a root package.json that wires them up as npm workspaces, and a handful of operational documents at the top level. Reading a single server directory from top to bottom is the fastest way to learn the protocol, because each one is small enough to finish in one sitting.

Beside src/, the root holds ADDITIONAL.md for community frameworks and clients, RELEASING.md for how packages reach the registries, SECURITY.md, CLAUDE.md, a .mcp.json used by the repository's own tooling, and a scripts directory. The everything server is the exception to the flatness: it carries a docs directory with architecture, feature and extension-point notes, and it behaves more like a protocol conformance fixture than like a template.

SDKs and language versions

The README lists ten official SDKs — C#, Go, Java, Kotlin, PHP, Python, Ruby, Rust, Swift and TypeScript — and states that the reference servers are built on them. In practice the TypeScript packages are current while the Python packages sit one major version behind, and the time server's README says so in a single line.

The time server documents the reason for the gap plainly: SDK 2.0 renamed the APIs it uses and the port is in progress. That is the honest cost of a reference collection — the examples track the specification closely, and the Python half tracks the SDK majors less closely. Anyone copying a Python server today is reading working code written against the 1.x API, which is fine for study and a trap for new work.

How a server actually runs

A client configured with a stdio server spawns it as a child process at startup and speaks newline-delimited JSON-RPC over stdin and stdout. Nothing listens on a port. During the initialize handshake both sides declare capabilities: the server announces which tools, resources and prompts it implements, the client announces whether it accepts roots, sampling and elicitation, and everything after that is a request, a response or a notification.

The three primitives are not interchangeable. A tool is something the model decides to call, a resource is something exposed at a URI for the application or the user, and a prompt is a template the user selects. The everything server implements all three plus sampling, elicitation, progress notifications, structured tool output and the newer task extension, which makes it the one directory worth reading when a protocol feature is unclear.

Getting started

Nothing needs compiling. A server is a package on npm or PyPI, and the configuration below is the whole installation: the client runs the command, the command answers over stdout, and the model is handed a tool list.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Writing one is not much harder. The TypeScript SDK exposes a server object with registerTool, registerResource and registerPrompt, plus one transport. The snippet below is a complete server with a single tool, and it is the same shape as the filesystem and memory examples.

import { readFile } from "node:fs/promises";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "wordcount", version: "0.1.0" });

server.registerTool(
  "count_words",
  {
    title: "Count words",
    description: "Count the words in a UTF-8 text file",
    inputSchema: { path: z.string() },
  },
  async ({ path }) => {
    const words = (await readFile(path, "utf8")).split(/\s+/).filter(Boolean).length;
    return { content: [{ type: "text", text: String(words) }] };
  },
);

await server.connect(new StdioServerTransport());

Security posture

The collection is unusually explicit about what it is not. The README's warning block says the servers demonstrate features and SDK usage, that developers should evaluate their own security requirements, and that the servers are not production-ready. SECURITY.md then states that the repository is not eligible for vulnerability reporting at all, which is the clearest signal of the intended status: the SDKs are supported, the examples are not.

• Every server is a local child process holding the privileges of the user who started it, so a model's tool calls become file, network and repository operations inside that account.
• The filesystem server is the only one with an access-control story: a directory allowlist set from command-line arguments or replaced at runtime by the client through Roots, and a path check is not a process sandbox.
• The fetch server converts pages to markdown, respects robots.txt and exposes a configurable user-agent and proxy, which is as far as the collection goes on outbound network hygiene.
• Memory persists a knowledge graph to a local JSON file with no authentication, and git writes to whichever repository path it is given; neither is meant to face a network.
• Releases are manual workflow dispatch into a gated GitHub environment with a required reviewer, published to npm and PyPI with provenance attestations and without registry tokens.

Where it falls short

Seven servers is a small sample and none of them is a service. There is no authentication model to copy, because stdio is local by construction and the HTTP routes in the everything server are development transports; there is no rate limiting, no support statement, no deployment story beyond a docker run in a README. The archived servers are still linked from years of tutorials, so a reader following an old guide can land in a repository that was deliberately moved. And the Python half of the collection lags the SDK it is supposed to demonstrate.

The honest comparison is not which of these four wins, but what each teaches. A framework gets a server running faster and hides the parts that change between specification versions. The registry gives you code somebody else wrote, with whatever review that author did. The reference servers are the only option where the source was written by the people who wrote the specification, and that is exactly why they are worth reading and not worth shipping.

Verdict

Use it as documentation that executes. Recommended for anyone building an MCP server, for anyone auditing one, and for anyone who wants to see how tools, resources and sampling appear on the wire; not recommended as a base repository, as a source of production tools, or as a list of servers to add to a client.

1. Read src/ before writing a server: filesystem for access control, everything for the full protocol surface, memory for a non-trivial tool design.
2. Run the reference servers locally to learn the protocol or to test a client, and treat their tool lists as fixtures rather than as a product.
3. Pin package versions in any configuration you keep, instead of the -y flag the README examples use.
4. Do not deploy a reference server to a shared account: no authentication, no rate limits and no vulnerability intake.
5. Send protocol findings to the SDK repositories, and use the registry rather than this repository when the goal is a server to run.

The servers in this repository are intended as reference implementations to demonstrate MCP features and SDK usage. They are meant to serve as educational examples for developers building their own MCP servers, not as production-ready solutions.

Sources

1. MCP reference servers repository
2. Repository README and server list
3. Security policy
4. Release process and trusted publishing
5. Filesystem server README
6. Everything server feature list
7. MCP Registry
8. Archived reference servers
9. Model Context Protocol documentation
10. TypeScript MCP SDK
11. Python MCP SDK
12. FastMCP on PyPI