MCP Demo
This server exposes a single MCP tool for adding two numbers.
Call the
addtool with numeric inputsaandb.Receive the sum of those two numbers.
No other tools, resources, or prompts are present in the provided schema.
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., "@MCP Demo add 4 and 7"
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 Explorer
A hands-on project for learning MCP (Model Context Protocol) by building both halves of the protocol ourselves — a server, then a client — one small, understandable step at a time.
This README is also published as a browsable page: MCP Explorer. It mirrors everything here — keep both in sync as the plan changes.
What is MCP?
MCP (Model Context Protocol) is a standard way for an AI assistant to call out to external tools and data, instead of every app inventing its own custom integration. You write an MCP server that exposes a small set of capabilities — tools (functions the assistant can call), resources (read-only data) and prompts (reusable request templates) — and any MCP-compatible client (Cursor, Claude Desktop, Claude Code, etc.) can discover and use them the same way. Think of it like a USB port for AI assistants: one common plug, many different devices behind it.
The point of this repo isn't to rush to a "real" server. It's to build enough small, working versions that each new MCP concept has somewhere to attach itself in your head.
Related MCP server: Math Addition MCP Server
Quick start
pnpm install
pnpm build
pnpm start:http # the server, on http://localhost:4768/mcpPorts and addresses are set in a .env per package (packages/server, client, web; copy each .env.example; see Ports and settings).
Then, in another terminal, try a client:
pnpm client # scripted CLI client
pnpm web # web dashboard on http://localhost:4767The server can also run over stdio (pnpm start), which is how the Inspector and Cursor can launch it themselves. Every client and both transports, step by step: docs/connecting-clients.md.
What's in the repo
MCP-Explorer/
├── package.json, pnpm-workspace.yaml, tsconfig.base.json
├── docs/
│ ├── connecting-clients.md # how to connect Cursor, the Inspector, the CLI, the dashboard
│ ├── branches/ # one file per numbered branch: what changed and how to try it
│ └── plans/ # detailed plan for the next stage
├── constitution/ # longer project guidance, read on demand
└── packages/
├── server/ # @mcp-explorer/server — tools, resources, prompts; stdio and HTTP entry points
├── client/ # @mcp-explorer/client — a minimal client built from scratch
└── web/ # @mcp-explorer/web — Next.js dashboard that runs the server's toolsBranch history
Every branch gets a global sequence number, and every numbered branch has its own file in docs/branches/ explaining what happened, the details worth knowing, and how to connect and try it. Read them in order to follow how the project grew.
# | Branch | What it did |
1 | Stage 1: the smallest MCP server, with one tool, | |
2 | Side exploration: a minimal client written from scratch. | |
3 | Side exploration: | |
4 | Stage 2: a second tool, | |
5 | Stage 3: | |
6 | Side exploration: server and client become separate packages. | |
7 | Side exploration: the web dashboard rebuilt in Next.js and React. | |
8 | Side exploration: a standalone Streamable HTTP entry point. | |
9 | Side exploration: the repo moves from npm to pnpm. | |
10 | Stage 4: timeouts and retries, progress updates, and stateful HTTP sessions. | |
11 | Stage 4: the dashboard reconnects after a server restart. | |
12 | Stage 4: verified cancel and idle sweep, added the dashboard Cancel button. | |
13 | Stage 5: resources, prompts and argument completion, a CLI demo, and a tool vs resource vs prompt guide. | |
14 | Stage 6: Vitest unit, in-memory and HTTP integration tests, a schema snapshot, and a GitHub Actions workflow. | |
15 | Stage 7: the HTTP entry point moves from hand-written | |
16 | Stage 8: a code review server ( | |
17 | Stage 9: authentication. First commit: the roadmap regrouped into three phases with numbered steps, a planning format ( | |
18 | Fix: | |
19 | Refactor: | |
20 | Stage 10: scopes per tool and session owner, |
Branch numbering: every new branch — a numbered stage or a side exploration — gets the next global sequence number (
NN-description), so the branch list alone shows true creation order, not just which stages happen to be numbered.stage-1-basic-serverandexplore-mcp-clientpredate the convention (they are #1 and #2) and keep their original names. #3 turned out to be a side exploration rather than Stage 2, which is why the counter is global and does not reserve numbers for stages in advance. Adding a branch means adding its file indocs/branches/and a row to the table above.
Roadmap
Every stage (and every side exploration) gets its own git branch. The habit is: branch → build → understand it → merge into main → branch again for the next thing. Nothing moves to main until it's understood, not just working.
The plan is grouped into phases. A phase is a goal you can demonstrate; a stage is one branch; a step (9.1, 9.2 …) is one commit or one small PR. Every phase below has the same five parts: Goal, You can do this when it's done, Stages, Done when, Out of scope. The rules for writing one are in constitution/planning.md.
Overview: three phases in order.
flowchart LR
P1["Phase 1<br/>Build the server<br/>Stages 1-8 (done)"] --> P2["Phase 2<br/>Production-ready<br/>Stages 9-13 (in progress)"] --> P3["Phase 3<br/>Build the client<br/>Stages 14-18 (planned)"]
classDef built fill:#d1fae5,stroke:#059669,color:#064e3b
classDef current fill:#fef3c7,stroke:#d97706,color:#78350f
classDef planned fill:#e0e7ff,stroke:#6366f1,color:#312e81
class P1 built
class P2 current
class P3 plannedColours in every diagram below: green = built and merged, amber = built, PR open, blue = planned.
Phase 1: Build the server. Stages are single branches, so there are no numbered steps.
flowchart LR
S1["Stage 1<br/>Basic server<br/>add tool"] --> S2["Stage 2<br/>Second tool<br/>divide + validation"] --> S3["Stage 3<br/>Real data source<br/>get_weather"] --> S4["Stage 4<br/>Errors, progress,<br/>stateful sessions"] --> S5["Stage 5<br/>Resources, prompts,<br/>completions"] --> S6["Stage 6<br/>Tests + CI"] --> S7["Stage 7<br/>Hono HTTP<br/>framework"] --> S8["Stage 8<br/>Code review server<br/>get_diff, read_file,<br/>run_checks"]
classDef built fill:#d1fae5,stroke:#059669,color:#064e3b
class S1,S2,S3,S4,S5,S6,S7,S8 builtPhase 2: Make it production-ready. Every step is one commit or one small PR.
flowchart TB
subgraph S9["Stage 9 - Authentication (merged, #18)"]
direction LR
A1["9.1<br/>Token issuer"] --> A2["9.2<br/>Protected-resource<br/>metadata"] --> A3["9.3<br/>Bearer<br/>middleware"] --> A4["9.4<br/>Client sends<br/>the token"] --> A5["9.5<br/>Tests and docs"]
end
subgraph S10["Stage 10 - Authorization and hardening (built, PR #20 open)"]
direction LR
B1["10.1<br/>Scopes<br/>per tool"] --> B2["10.2<br/>Origin check"] --> B3["10.3<br/>Rate and<br/>size limits"] --> B4["10.4<br/>Audit log"] --> B5["10.5<br/>Validated config<br/>and secrets"]
end
subgraph S11["Stage 11 - Persistence and scaling (planned)"]
direction LR
C1["11.1<br/>Session store<br/>interface"] --> C2["11.2<br/>Redis store"] --> C3["11.3<br/>Resumable streams<br/>Last-Event-ID"] --> C4["11.4<br/>Two instances<br/>behind a proxy"]
end
subgraph S12["Stage 12 - Observability (planned)"]
direction LR
D1["12.1<br/>Structured logs<br/>with session id"] --> D2["12.2<br/>Health and<br/>readiness"] --> D3["12.3<br/>Metrics"] --> D4["12.4<br/>OpenTelemetry<br/>traces"] --> D5["12.5<br/>Graceful<br/>shutdown"]
end
subgraph S13["Stage 13 - Containerize and deploy (planned)"]
direction LR
E1["13.1<br/>Dockerfile"] --> E2["13.2<br/>Env config"] --> E3["13.3<br/>Gateway, TLS,<br/>no SSE buffering"] --> E4["13.4<br/>CD pipeline"] --> E5["13.5<br/>Tool versioning<br/>policy"]
end
S9 --> S10 --> S11 --> S12 --> S13
classDef built fill:#d1fae5,stroke:#059669,color:#064e3b
classDef current fill:#fef3c7,stroke:#d97706,color:#78350f
classDef planned fill:#e0e7ff,stroke:#6366f1,color:#312e81
class A1,A2,A3,A4,A5 built
class B1,B2,B3,B4,B5 current
class C1,C2,C3,C4,D1,D2,D3,D4,D5,E1,E2,E3,E4,E5 plannedPhase 3: Build the client. Its steps are written when Phase 2 ends, so only the stages are shown.
flowchart LR
F14["Stage 14<br/>Client library<br/>reconnect, 401 flow"] --> F15["Stage 15<br/>LLM agent loop<br/>calls tools"] --> F16["Stage 16<br/>Client features<br/>roots, sampling,<br/>elicitation"] --> F17["Stage 17<br/>Several servers<br/>at once"] --> F18["Stage 18<br/>Web UI on the<br/>library"]
classDef planned fill:#e0e7ff,stroke:#6366f1,color:#312e81
class F14,F15,F16,F17,F18 plannedPhase 1 — Build the server (done: Stages 1–8)
Goal: a working MCP server with tools, resources and prompts, tested, on both transports, doing one real job. You can do this when it's done: connect Cursor or the Inspector, call the tools, and run the code review prompt on your own repo. Done when: 145 tests pass in CI and Stages 1–8 are merged. Out of scope: anything about who is calling, or running it for other people (that is Phase 2).
Stage 1 — Basic server + one trivial tool (on
main) A server exists, and it can do exactly one thing (add). Goal: understand server / tool / transport as separate concepts. Details: #1Stage 2 — Second tool + input validation (on
main) Add a second, slightly less trivial tool, and lean harder onzod— rejecting bad input with clear errors rather than trusting the caller. Goal: see how multiple tools coexist, and what "validation" means beyond just typing. Details: #4Stage 3 — Connect to a real data source / API (on
main) Swap a toy tool for one that does real (async) work — calling a public API or reading real data. Goal: handle async operations and things that can be slow or unavailable. Details: #5Stage 4 — Error handling, a real-time use case & stateful HTTP (on
main) Harden the server against failures (bad responses, timeouts, partial data), add a tool that reports progress while it runs, and add stateful Streamable HTTP — anMcp-Session-Idissued oninitialize, a map of live sessions, oneMcpServerper session. Goal: go from "it works when everything goes right" to "it behaves sensibly when it doesn't," and see why sessions exist at all. Details: #10, #11, #12Stage 5 — Resources, prompts & completions (built and merged) Tools are one of three server primitives. Add resources (read-only data a client can attach, addressed by URI) and prompts (reusable templates the user picks), plus argument completion. Goal: know which primitive fits which job instead of making everything a tool. Details: #13
Stage 6 — Testing & CI (built and merged) Unit-test tools, integration-test the server through an in-memory transport and through real HTTP, add contract checks on tool schemas, and run it all in GitHub Actions on every PR. Goal: change a server safely before it has real users. Details: #14
Stage 7 — HTTP framework (Hono) (built and merged) Replace the hand-rolled
node:httpentry inhttp.ts(manual body parsing, routing, error handling) with Hono (via@hono/node-server, bridging to the SDK transport). The session map, idle sweep and transports stay as they are; only the HTTP layer changes. Goal: a typed router and middleware to build the later stages on, with the stage 6 tests proving nothing changed. Details: #15Stage 8 — Code review server (built and merged) A real use case on top of the server: a
review_codeprompt (the checklist the user picks), read-only tools that fetch what the model needs (get_diff,read_file), repo files as resources, and one extra tool,run_checks(lint / typecheck / tests), that streams progress and supports cancel. The client's model does the reviewing; the server only supplies context. The repo it reviews is the one the client names: arootargument on each tool (thereview_codeprompt asks the model to pass it), or the client's declared roots;REVIEW_ROOTpins one repo andREVIEW_ALLOWED_ROOTSlimits which folders are accepted. Goal: apply the three primitives to a job none of them fits alone. The review tools work over stdio only, started by the client on the user's own machine; over HTTP they return an error that says to use stdio, or to ask the server admin to setREVIEW_ALLOW_HTTP=1.run_checksis still pnpm-only. (MCP sampling, where the server asks the client's model, is a possible follow-up.) Details: #16
Phase 2 — Make it production-ready (in progress: Stages 9–13)
Goal: what separates a demo server from one a team can run: you know who is calling and what they may do, state survives restarts, you can see what it is doing, and you can ship it.
You can do this when it's done: start the whole stack with Docker Compose, get 401 without a token, call a tool with one, kill an instance and lose no session.
Done when: the five stages below are merged and the Compose stack passes an end-to-end check in CI.
Out of scope: a real identity provider (a small local issuer stands in), multi-region, billing.
Stage | Branch | What you learn | Steps |
9. Authentication · plan |
| The server is an OAuth 2.1 resource server: validate tokens, say how to get one. | 9.1 local token issuer · 9.2 protected-resource metadata · 9.3 bearer middleware · 9.4 client sends the token · 9.5 tests and docs |
10. Authorization and hardening · plan |
| What each caller may do, and a record of what they did. | 10.1 scopes per tool · 10.2 |
11. Persistence and scaling |
| Sessions outside the process, so restarts and several instances work. | 11.1 session store interface · 11.2 Redis store · 11.3 resumable streams ( |
12. Observability |
| See the server in production and stop it cleanly. | 12.1 structured logs with a session id · 12.2 health and readiness · 12.3 metrics · 12.4 OpenTelemetry traces · 12.5 graceful shutdown |
13. Containerize and deploy |
| Ship it, update it, roll it back. | 13.1 Dockerfile · 13.2 env config · 13.3 gateway with TLS and no SSE buffering · 13.4 CD pipeline · 13.5 tool versioning policy |
Side branches that may come up during Phase 2 (not stages): background checks (start, then fetch the result) for clients with short timeouts; npm package prep for the stdio server.
Phase 3 — Build the client (planned: Stages 14–18)
Goal: the project says "both halves"; the client is still a thin script. Build the second half properly. You can do this when it's done: open the web UI, connect to a server (with auth), and let a model use its tools in a conversation. Done when: the client covers what the server exposes, and the web UI runs on it. Out of scope: hosting the client for others.
Stages, in order, with steps to be written when Phase 2 ends: 14 a client library (reconnect, the 401 flow) · 15 an LLM agent loop that calls tools · 16 client features (roots, sampling, elicitation) · 17 several servers at once · 18 the web UI on top of the library.
Where we are: Phase 1 is done: Stages 1–8 are merged (Stage 8 on #16, 145 tests), along with side explorations #2, #3 and #6–#9. Phase 2 is in progress: Stage 9 is merged (#18), Stage 10 is built and its PR (#20) is open, and Stage 11 is next. Phases 2 and 3 are the plan, not a promise of exact detail.
Available Tools
1 tooladdAdd two numbersB
Adds two numbers together and returns their sum.
Inputs: a (required), b (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only a single tool, there is no possibility of confusion or misselection between tools. The purpose (adding two numbers) is unambiguous.
The lone tool 'add' uses a clear, simple verb, but with only one name there is no established convention to be consistent with. No violations exist, but the pattern is untestable.
A single trivial tool is far too thin for any meaningful server scope, even a demo. The surface offers no room for a real workflow.
For an arithmetic domain, only addition is covered; subtraction, multiplication, and division are missing. Agents relying on this surface will hit dead ends for any non-additive task.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- FlicenseBqualityNot gradedmaintenanceA minimal Model Context Protocol server that provides a simple tool for adding two integers. It serves as a demonstration of the official Python MCP SDK and is designed for local execution via stdio.1-
- FlicenseNot gradedqualityDmaintenanceA simple MCP server that provides a tool for adding two numbers, designed for testing MCP integration with Claude.-
- FlicenseNot gradedqualityDmaintenanceA model-agnostic MCP server exposing example tools (add1, multiply2, greet) for learning purposes, working with any LLM through stdio transport.-
- AlicenseAqualityDmaintenanceEnables users to run a modular TypeScript MCP server that communicates over STDIO and exposes tools for summing numbers and greeting users.2ISC