example-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@example-mcp show me the open todos for user 3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-template
A starter for MCP servers that expose an HTTP API to AI assistants (Claude Code, Claude Desktop, Cursor, LangGraph agents) as a few safe, read-first tools. It works out of the box against a free public fake API (JSONPlaceholder), with:
a typed client, errors the model can act on, and stdout-safe logging;
tools built from field allowlists, with no-leak tests;
approval-gated write tools (off by default);
docs search (hybrid RAG with a secret gate);
a test agent with evals and a calibrated LLM judge;
an end-to-end stdio test and CI.
Why every piece exists: docs/PATTERNS.md. Connecting it to Claude Code: GETTING_STARTED.md.
Versions (2026-11): Python 3.12,
mcp>=1.30,<2(held below 2 becauselangchain-mcp-adaptersdoesn't support it yet), langchain 1.4, uv 0.12. The MCP spec and SDKs move fast; check them when you start.
Start a new server from this template
uv run python scripts/new_project.py weather-mcp # creates ../weather-mcp
cd ../weather-mcp && git init -b main && uv sync && uv run pytestIt copies everything except local state (.git, .venv, .env, data/, eval reports), renames the package
(example_mcp → weather_mcp), the command and server name (example-mcp → weather-mcp), and refreshes
uv.lock. On GitHub, "Use this template" works too; then rename by hand. The script and its test exist only
in the template.
Related MCP server: DevTools MCP Server
Quick start
uv sync
uv run pytest # unit tests + stdio end-to-end test, no network needed
uv run python scripts/probe.py users # live, read-only: prints the response SHAPE only
npx @modelcontextprotocol/inspector uv --directory "$PWD" run example-mcp # try the toolsThe server needs no .env for the example API. For the agent, evals and docs search:
cp .env.example .env, then set OPENAI_API_KEY (or another provider's key) and MODEL.
Layout
src/example_mcp/
settings.py env config, validation, load_env_file()
log.py stderr-only logging with redaction
errors.py typed errors -> ToolError messages (run_backend, run_write)
auth.py token sources (NoAuth, StaticToken)
client.py ApiClient.get/post/patch: the only place that does HTTP
formatting/ pure functions: raw API data -> short text, from field allowlists
tools/ one module per domain, register(mcp, client)
docs/ hybrid search (Chroma + BM25 + rank fusion)
server.py create_server() wiring, serve(), main() (--http flag)
agent/ test agent (LangChain create_agent over one MCP session)
evals/ questions.yaml, checks, LLM judge + calibration, runner
ingest/ builds the docs index from knowledge/ (secret gate, safe rebuild)
knowledge/ the docs the search indexes (here: the example API)
scripts/ probe.py, new_project.py
tests/ everything mocked; test_stdio_e2e.py starts the real server
docs/PATTERNS.md the rules and the reasons behind themAdd a tool in 5 steps
Read the real shape:
uv run python scripts/probe.py <path>.Formatter in
formatting/<domain>.py: pure function, allowlist of fields,display()for user text,format_listing()for capped lists with counts.Tool in
tools/<domain>.py:@mcp.tool(annotations=READ_ONLY, structured_output=False), a docstring that says when to use it and where its ids come from,run_backend(client.get(...), hint_tool=...).Register the module in
server.py(TOOL_MODULES) and mention it inINSTRUCTIONS.Test it in the
TOOL_CASEStable intests/test_server.py(request, output, no leaks), then add an eval case inevals/questions.yaml.
Replace the example API
Set
API_BASE_URL(andAPI_TOKENif it needs a bearer token) in.env. For login-based APIs, write a token source following the recipe in PATTERNS.md.Replace
tools/users.py,todos.py,posts.pyand their formatters, tests and fixtures.Replace
knowledge/with your docs and re-run the ingest; rewriteevals/questions.yamland the judge labels for your data; updateINSTRUCTIONSandagent/prompt.py.
Tools (example)
Tool | API | Notes |
|
| name, username, id, company; never email, phone or address |
|
| profile + post and todo counts; 404 hints |
|
| open/completed counts, up to 50 rows |
|
| local title/body match with a match count |
| local index | cited excerpts from |
|
| write: off by default, allowlist, approval; the API doesn't persist it |
Optional parts (delete what you don't need)
Part | Delete | Then |
Write tools |
| remove |
Docs search |
| remove |
Agent + evals |
| drop the |
HTTP transport | the | keep stdio only |
Docs search
uv run python -m ingest.ingest_docs # embeds knowledge/ into data/chroma; re-run when docs changeEvery file passes the secret gate before embedding; a flagged file is skipped whole and only its path and pattern names are printed. The collection is replaced only after all embeddings succeed.
EMBEDDING_MODELis aprovider:modelstring (defaultopenai:text-embedding-3-small) and must match between ingest and server. LangChain'sinit_embeddingshas no Anthropic provider: with Claude models, still use another provider's key for embeddings.RESULTS = 4indocs/search.py: re-measure it on your corpus (PATTERNS.md).
Test agent and evals
uv run python -m agent.chat "how many open todos does user 1 have?" # one question, prints tool calls
uv run python -m evals.calibrate_judge --runs 3 # judge must agree with every label
uv run python -m evals.run_evals --runs 3 # all cases x 3MODELandJUDGE_MODELareprovider:modelstrings forinit_chat_model(e.g.anthropic:claude-sonnet-5-5afteruv add langchain-anthropic). The default judge is an OpenAI model, so calibrate again when you change it.The runner exits 1 below 90% or when any case failed every run. Reports with every answer go to
evals/results/(gitignored). Read the answers before changing anything.Evals switch the write tools on for the server they start and reject every write proposal, so nothing changes.
LANGSMITH_TRACING=trueplusLANGSMITH_API_KEYtraces every run.
Roadmap (for servers built from this)
Hosting: Streamable HTTP behind HTTPS with OAuth 2.1 (see PATTERNS.md "Later: hosting"), Docker, Sentry, audit events, per-user rate limits.
CI: run a read-only contract check against a dev API after backend deploys (are the fields formatters rely on still there?), and rebuild the docs index when its sources change.
Upgrade to
mcp2.x oncelangchain-mcp-adapterssupports it.
License
MIT
Available Tools
5 toolsget_userARead-onlyIdempotent
Show one user's profile with their number of posts and open/completed todos.
Get user_id from list_users.
Inputs: user_id (required).
list_todosARead-onlyIdempotent
List todos with open/completed counts.
- user_id: only this user's todos (get it from list_users); omit for everyone.
- completed: true = only completed, false = only open; omit for both.
Prefer these filters over reading the whole list: rows are capped at 50, the counts are not.
Inputs: user_id, completed.
list_usersARead-onlyIdempotent
List users with their user id, username and company.
- name_contains: case-insensitive part of the full name or username; empty lists everyone.
Use the user id with get_user, list_todos or search_posts. Contact details (email, phone,
address) are never available through this server.
Inputs: name_contains.
search_docsARead-onlyIdempotent
Search the example API's documentation (the files in knowledge/).
Use it for how-it-works questions: which endpoints and filters exist, what fields a resource
has, how errors, pagination or writes behave. Include exact names when known (e.g. /todos,
userId). Returns a few excerpts, each starting with a citation [source — file]; cite them.
This is documentation, not live data: use the other tools for actual users, todos or posts.
Inputs: query (required).
search_postsARead-onlyIdempotent
Find posts whose title or body contains the query, with a match count.
- query: case-insensitive text; empty matches every post.
- user_id: only this user's posts (get it from list_users).
Returns title, post id and user id; rows are capped at 50, the match count is not.
Inputs: query, user_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct resource and action: list users, get a single user, list todos, search posts, and search documentation. search_docs is explicitly contrasted with the live-data tools, and there is no overlap between user, todo, and post operations.
All tool names use a consistent snake_case verb_noun pattern: list_users, get_user, list_todos, search_posts, search_docs. The verbs are appropriately varied but predictable, and there is no mixing of naming conventions.
Five tools are well-scoped for a small example API covering users, todos, posts, and documentation. Each tool earns its place with a distinct resource area, and there are no redundant or filler tools.
The read-only surface covers listing users, getting a user, listing todos, searching posts, and searching docs, but there is no get_post tool to retrieve a full post body—search_posts only returns title, post id, and user id. If write operations are part of the domain, they are also entirely absent, leaving notable gaps for post content retrieval.
Maintenance
Related MCP Connectors
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Turn any task into the right API calls: discover, evaluate, and integrate public APIs.
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes tools to create and list tasks by wrapping a REST API, enabling LLMs to manage a TODO list via natural language.-
- AlicenseNot gradedqualityDmaintenanceEnables LLM clients to fetch web pages as clean text, tail local logs, search the live web via DuckDuckGo, and run read-only SQL queries against SQLite or Postgres/Supabase.MIT
- FlicenseAqualityCmaintenanceEnables a locally-run LLM to search the web, fetch pages as markdown, make arbitrary HTTP requests, and optionally render pages with headless Chromium.3-
- AlicenseNot gradedqualityBmaintenanceExposes an OpenAI-compatible /v1/responses endpoint so a model can answer prompts by discovering and running a shared folder of sandboxed tools — shell commands, file editing, pull requests, persistent notes, time, sysinfo and Doxygen checks. Path-taking tools are bounded by a configurable file-system gate, and new tools added to the tools folder become available without code changes.MIT