Onboarding: modelcontextprotocol/servers

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 2w ago
• 5 active contributors
• Distributed ownership (top contributor 46%)
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

This is the official reference implementation monorepo for Model Context Protocol (MCP) servers — a standard that lets LLMs securely interact with external tools and data sources via a defined protocol. It contains 7 active reference servers (Everything, Fetch, Filesystem, Git, Memory, Sequential Thinking, Time) built with the TypeScript and Python MCP SDKs, designed to demonstrate correct protocol usage rather than serve as production deployments. npm workspaces monorepo: each server lives under src/<name>/ as its own package (e.g. src/everything/, src/filesystem/), with independent package.json, Dockerfile, and README. The 'everything' server is the most fully structured, with subdirectories for prompts/, resources/, server/, and tests/, serving as the primary reference for how other servers should be organized.

Who it's for

Developers building their own MCP-compatible servers who need concrete, canonical examples of how to implement MCP features (tools, prompts, resources, subscriptions, logging). Also useful for LLM application developers evaluating MCP capabilities before integrating it into their own stack.

Maturity & risk

The repo has CI pipelines for TypeScript, Python, and release workflows under .github/workflows/, and the 'everything' server has a solid test suite covering prompts, resources, tools, registrations, and server behavior under src/everything/tests/. The project is under active LF Projects governance (v0.6.2), indicating structured maintenance. Verdict: actively developed reference implementations, not production-ready deployments by their own explicit warning.

The repo itself warns explicitly in the README that these servers are NOT production-ready and lack hardened security. The TypeScript workspace monorepo uses npm workspaces with cross-package wildcard dependencies (e.g. '@modelcontextprotocol/server-everything': '*'), which can cause version drift. The MCP SDK itself is under rapid evolution, meaning breaking protocol changes in the upstream SDKs could affect all servers simultaneously.

Active areas of work

The repo is actively maintaining the 'everything' reference server as a showcase of all MCP features, as evidenced by its extensive docs/ directory (architecture.md, extension.md, features.md, how-it-works.md, startup.md, structure.md). Several servers (AWS KB Retrieval, Brave Search) have recently been archived and moved to a separate servers-archived repo, indicating a consolidation of scope.

Get running

git clone https://github.com/modelcontextprotocol/servers.git cd servers npm install npm run build

To run the 'everything' reference server specifically:

cd src/everything npm run build

Daily commands: npm run build --workspaces # builds all servers npm run watch --workspaces # watches all in parallel

For a specific server:

cd src/everything && npm run build

Or via Docker: docker build -f src/everything/Dockerfile .

Map of the codebase

• src/everything/index.ts — Main entry point for the reference 'everything' server that wires together all MCP features (tools, resources, prompts, transports) and is the canonical example for the entire SDK.
• src/everything/server/index.ts — Core server instantiation and handler registration — defines how MCP capabilities are composed and attached to the server instance.
• src/everything/tools/index.ts — Aggregates and registers all tool handlers, making it the central registry that contributors must update whenever adding a new tool.
• src/filesystem/index.ts — Production-quality filesystem MCP server that demonstrates path validation, sandboxing, and structured content — the most feature-complete reference server.
• src/fetch/src/mcp_server_fetch/server.py — Python-based fetch MCP server showing how to implement MCP in Python with UV, serving as the canonical cross-language reference implementation.
• src/filesystem/path-validation.ts — Security-critical module that enforces allowed-directory sandboxing — every contributor must understand this before touching filesystem operations.
• src/everything/transports/streamableHttp.ts — Implements the Streamable HTTP transport, the newest and most complex transport layer, essential for understanding MCP's HTTP-based communication model.

How to make changes

Add a new Tool to the everything server

1. Create a new file following the pattern of existing tools — export a function that accepts the McpServer instance and calls server.tool() with a Zod schema and async handler (src/everything/tools/your-new-tool.ts)
2. Import your new tool registration function and call it inside the registerTools() function, passing the server instance (src/everything/tools/index.ts)
3. Add a corresponding test file that invokes the tool via a test client and asserts on the CallToolResult shape (src/everything/__tests__/tools.test.ts)

Add a new Resource to the everything server

1. Create a new file exporting a registration function that calls server.resource() or server.resourceTemplate() with URI pattern and ReadResourceCallback (src/everything/resources/your-new-resource.ts)
2. Import and call your resource registration function inside the registerResources() aggregator (src/everything/resources/index.ts)
3. Add test coverage asserting the resource URI resolves and returns correct content type and data (src/everything/__tests__/resources.test.ts)

Add a new filesystem tool to the filesystem server

1. Add the new tool schema and handler inside the main server setup using server.tool(); use validatePath() from path-validation.ts before any fs operation to enforce sandboxing (src/filesystem/index.ts)
2. Add any shared filesystem helpers (read, stat, search patterns) here so they can be reused by multiple tools (src/filesystem/lib.ts)
3. Write path validation tests to confirm the new tool rejects paths outside allowed directories (src/filesystem/__tests__/path-validation.test.ts)

Add a new Prompt to the everything server

1. Create a prompt module exporting a registration function that calls server.prompt() with argument definitions and a GetPromptCallback returning messages (src/everything/prompts/your-new-prompt.ts)
2. Import and invoke your prompt registration function in the central prompts aggregator (src/everything/prompts/index.ts)
3. Add test coverage for the new prompt's GetPromptResult and any argument completions (src/everything/__tests__/prompts.test.ts)

Why these technologies

• TypeScript with Zod — Provides compile-time type safety for MCP message schemas and runtime validation of tool inputs, matching the JSON-Schema-driven MCP specification without manual validation code.
• Python + UV (fetch server) — Demonstrates MCP SDK cross-language parity; UV gives fast, reproducible Python environments without heavyweight virtualenv management.
• npm Workspaces — Each server is an independently publishable npm package; workspaces allow a single repo with shared tooling while keeping packages isolated.
• Vitest — Native ESM support and TypeScript-first test runner matches the ESM-only codebase without transpilation overhead; fast watch mode suits iterative SDK development.
• Multiple transports (stdio, SSE, Streamable HTTP) — Reference servers must demonstrate all officially supported MCP transports so SDK consumers can choose and implement the right one for their deployment model.

Trade-offs already made

• Monorepo with per-server packages

  • Why: Enables independent versioning and publishing of each reference server while sharing CI, linting, and root-level scripts.
  • Consequence: npm workspace hoisting can cause subtle dependency conflicts; each server's package.json must explicitly declare its own MCP SDK version.

• Everything server is intentionally unrealistic

  • Why: Exercises every MCP feature (sampling, elicitation, subscriptions, roots, structured output) in one server for SDK testing, not production use.
  • Consequence: The everything server cannot serve as a template for real servers — contributors must mentally filter out demo-only patterns.

• Path sandboxing enforced at validation layer not OS level

  • Why: Keeps the filesystem server portable across operating systems without requiring containers or OS-level jails.
  • Consequence: Security relies entirely on the correctness of path-validation.ts — symlink attacks or TOCTOU races are possible if the logic has bugs.

• No shared library between servers

  • Why: Each server is a self-contained reference that developers can copy independently; shared abstractions would obscure the minimal SDK surface needed.
  • Consequence: Some utility logic (e.g. path norm

Traps & gotchas

The root package.json uses 'type': 'module' making this a pure ESM project — CommonJS require() will not work anywhere. Wildcard workspace dependencies ('*') mean you must run 'npm install' from the root, not inside individual server directories, or cross-package resolution breaks. The .npmrc file likely contains registry or workspace hoisting config that affects installs. Python servers (fetch, git, time) have separate dependency management (likely pyproject.toml or requirements.txt) not managed by npm — check each server's directory independently.

Architecture

Concepts to learn

• Model Context Protocol (MCP) — The entire repo is an implementation of this protocol — understanding the spec (tools, prompts, resources, subscriptions) is mandatory before modifying any server.
• MCP Resource Subscriptions — src/everything/resources/subscriptions.ts implements the pattern where clients subscribe to resource changes and receive push notifications — a non-obvious stateful MCP feature.
• npm Workspaces (ESM Monorepo) — The repo uses npm workspaces with pure ESM ('type': 'module') meaning all inter-package imports and build order are workspace-managed — misunderstanding this breaks local development.
• MCP Prompt Completions — src/everything/prompts/completions.ts implements argument autocompletion for prompts — a protocol feature that many MCP server authors overlook but clients depend on.
• Stdio Transport (MCP) — MCP servers in this repo communicate over stdio by default (not HTTP), meaning the server is spawned as a child process — this affects how you test and debug locally.
• MCP Roots — src/everything/server/roots.ts implements the MCP roots feature, which tells clients which filesystem paths or URIs the server has access to — a security boundary concept specific to MCP.

Related repos

• modelcontextprotocol/typescript-sdk — The TypeScript MCP SDK that all TypeScript servers in this repo are built on — understanding it is prerequisite to modifying any server here.
• modelcontextprotocol/python-sdk — The Python MCP SDK used by the Fetch, Git, and Time servers in this repo.
• modelcontextprotocol/servers-archived — Contains servers that were removed from this repo (AWS KB Retrieval, Brave Search, etc.) — useful for reference implementations of more complex integrations.
• modelcontextprotocol/inspector — MCP debugging/inspection tool used to interactively test MCP servers built using this repo's patterns.
• anthropics/anthropic-cookbook — Companion examples showing how MCP servers from this repo are consumed by Claude-based LLM applications.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for all individual tool modules in src/everything/tools/

The test suite under src/everything/tests/ has tests for tools.test.ts (likely integration-level), but there are 16+ individual tool files (echo.ts, get-sum.ts, trigger-sampling-request.ts, trigger-elicitation-request.ts, gzip-file-as-resource.ts, simulate-research-query.ts, etc.) with no dedicated per-module unit tests. Adding isolated unit tests for each tool ensures edge cases (e.g. gzip errors, async sampling timeouts, elicitation cancellation) are caught without spinning up the full server, and improves contributor confidence when modifying individual tools.

• [ ] Audit src/everything/tests/tools.test.ts to identify which individual tools currently have no isolated coverage
• [ ] Add src/everything/tests/tools/echo.test.ts, get-sum.test.ts, get-annotated-message.test.ts, etc. — one file per tool module
• [ ] Write unit tests for src/everything/tools/gzip-file-as-resource.ts covering missing file, invalid input, and successful gzip output as a resource
• [ ] Write unit tests for src/everything/tools/trigger-elicitation-request.ts and trigger-elicitation-request-async.ts covering both sync and async paths, including cancellation/timeout scenarios
• [ ] Write unit tests for src/everything/tools/simulate-research-query.ts verifying the simulated delay and response shape
• [ ] Ensure all new test files follow the existing Jest/Vitest config in src/everything/package.json

Add unit tests for src/everything/resources/ modules (files.ts, session.ts, subscriptions.ts, templates.ts)

src/everything/tests/resources.test.ts likely covers high-level resource listing, but the four individual resource modules — files.ts (file-backed resources), session.ts (session-scoped state), subscriptions.ts (subscriber update logic), and templates.ts (URI template expansion) — have no dedicated tests visible in the file structure. subscriptions.ts is especially critical because src/everything/tools/toggle-subscriber-updates.ts depends on it, making subscription lifecycle bugs hard to catch without targeted tests.

• [ ] Review src/everything/resources/subscriptions.ts and map out all exported functions/classes that manage subscriber state
• [ ] Create src/everything/tests/resources/subscriptions.test.ts with tests for subscribe, unsubscribe, and update notification logic including edge cases (double-subscribe, unsubscribe when not subscribed)
• [ ] Create src/everything/tests/resources/session.test.ts verifying that session resources are correctly scoped and cleared
• [ ] Create src/everything/tests/resources/templates.test.ts with tests for URI template expansion covering valid templates, missing variables, and malformed input
• [ ] Create src/everything/tests/resources/files.test.ts using a temp directory fixture to test file read, missing file, and binary content scenarios
• [ ] Cross-reference with src/everything/tools/toggle-subscriber-updates.ts to ensure the subscription toggle path is exercised in tests

Add a dedicated architecture/extension documentation page for the tools plugin pattern implied by src/everything/docs/extension.md and src/everything/tools/index.ts

src/everything/docs/extension.md exists but the tools directory has grown to 16+ individual tool files all wired through src/everything/tools/index.ts, suggesting a registration/plugin pattern. However, there is no documentation showing how to add a new tool end-to-end (create the file, export the handler, register in index.ts, add tests). New contributors currently have to reverse-engineer this from existing tool files. A concrete 'Adding a New Tool' guide in docs/ would dramatically reduce onboarding friction and is a natural complement to the existing extension.md.

• [ ] Read src/everything/tools/index.ts to document the exact registration pattern (how tools are exported and

Good first issues

1. Add missing unit tests for src/everything/server/logging.ts and src/everything/server/roots.ts — these files exist but have no corresponding test files in tests/. 2. The src/everything/resources/templates.ts file has no dedicated test; add src/everything/tests/templates.test.ts covering template expansion edge cases. 3. Add a AGENTS.md equivalent to servers other than 'everything' (only src/everything/AGENTS.md exists) to document AI-assisted contribution guidelines for each server.

Top contributors

• @olaservo — 31 commits
• @cliffhall — 16 commits
• @nielskaspers — 8 commits
• @koic — 6 commits
• @dependabot[bot] — 6 commits

Recent commits

• 4503e2d — Merge pull request #3659 from ShionEria/fix/issue-3460-windows-npx-docs (cliffhall)
• 7e6b780 — Merge pull request #3693 from nipunnegi2/patch-2 (cliffhall)
• c3448d7 — Merge pull request #3694 from nipunnegi2/patch-3 (cliffhall)
• 74cdb4d — Merge pull request #3695 from nipunnegi2/patch-4 (cliffhall)
• 756db5b — Merge pull request #3733 from Zandereins/docs/add-claude-md (cliffhall)
• bb0a189 — Merge pull request #3877 from Chelebii/docs-3132-sequentialthinking-usage (cliffhall)
• 5d146b3 — Merge branch 'main' into docs-3132-sequentialthinking-usage (Chelebii)
• d5bfe34 — Merge pull request #3950 from olaservo/retire-third-party-server-list (cliffhall)
• 5914f61 — docs: retire third-party server list in favor of MCP Registry (olaservo)
• bae042b — docs: clarify sequentialthinking usage and add examples (Chelebii)

Security observations

• High · Server-Side Request Forgery (SSRF) via Fetch Server — src/fetch/src/mcp_server_fetch/server.py. The fetch server (src/fetch/src/mcp_server_fetch/server.py) likely accepts arbitrary URLs from clients and performs HTTP requests on their behalf. This enables SSRF attacks, allowing attackers to probe internal network services, access cloud metadata endpoints (e.g., http://169.254.169.254/), or interact with services not exposed externally. Fix: Implement an allowlist of permitted domains/IP ranges. Block requests to private IP ranges (RFC1918), loopback addresses, link-local addresses, and cloud metadata endpoints. Validate and sanitize all URLs before making requests. Consider adding configurable URL filtering policies.
• High · Potential Command Injection via Environment Variable Exposure — src/everything/tools/get-env.ts. The tool 'get-env.ts' (src/everything/tools/get-env.ts) suggests the server exposes environment variables to MCP clients. Environment variables may contain sensitive credentials, API keys, database URLs, or other secrets. Exposing these to any connecting client is a significant information disclosure risk. Fix: Remove or heavily restrict the get-env tool. If environment variable access is necessary for demonstration, restrict which variables can be accessed via an explicit allowlist. Never expose full process environment to untrusted clients.
• High · Arbitrary File Read via Filesystem Resource Exposure — src/everything/tools/gzip-file-as-resource.ts, src/everything/resources/files.ts. The gzip-file-as-resource tool (src/everything/tools/gzip-file-as-resource.ts) and file resources (src/everything/resources/files.ts) suggest the server reads files from the filesystem and returns them to clients. Without proper path traversal prevention and sandboxing, attackers could read arbitrary files from the host system including sensitive configuration files, SSH keys, or credentials. Fix: Implement strict path validation to ensure all file access is confined to a designated directory. Use realpath resolution and prefix checking to prevent path traversal (e.g., ../../etc/passwd). Run the server process with minimal filesystem permissions.
• High · Unrestricted Sampling Request Capability — src/everything/tools/trigger-sampling-request.ts, src/everything/tools/trigger-sampling-request-async.ts. The presence of trigger-sampling-request.ts and trigger-sampling-request-async.ts indicates the server can trigger LLM sampling requests. If not properly rate-limited or authenticated, malicious clients or prompt injection attacks could abuse this to exhaust LLM API quotas, exfiltrate data through LLM responses, or perform unintended model interactions. Fix: Implement rate limiting and authentication on sampling request endpoints. Validate and sanitize all inputs before including them in sampling requests to prevent prompt injection. Log all sampling requests for audit purposes.
• High · Elicitation Request Abuse — src/everything/tools/trigger-elicitation-request.ts, src/everything/tools/trigger-elicitation-request-async.ts. The elicitation request tools (trigger-elicitation-request.ts and trigger-elicitation-request-async.ts) can prompt users for information. This could be abused to perform social engineering attacks against users, tricking them into providing credentials or sensitive information through seemingly legitimate prompts. Fix: Restrict who can trigger elicitation requests. Implement clear user-facing indicators of the source of elicitation requests. Validate and sanitize elicitation content to prevent injection of misleading prompts.
• Medium · Missing Authentication on MCP Server Transports — src/everything/transports/sse.ts, src/everything/transports/streamableHttp.ts. The server exposes multiple transport mechanisms (SSE via src/everything/transports/sse.ts, Streamable HTTP via src/everything/transports/streamableHttp.ts, and stdio). HTTP-based transports (SSE, Streamable HTTP) typically lack built-in authentication, allowing any client that can reach the server to connect and invoke all tools, including potentially dangerous ones like file access and environment variable exposure. Fix: Implement authentication middleware for HTTP-based transports (e.g., API key validation, OAuth tokens). Consider binding HTTP transports to localhost only by default. Add origin validation to prevent cross-origin requests from unauthorized web pages.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.