Skip to main content
Glama
MCP Demo

MCP Demo

by shadmaanAsif

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/mcp

Ports 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:4767

The 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 tools

Branch 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-basic-server

Stage 1: the smallest MCP server, with one tool, add.

2

explore-mcp-client

Side exploration: a minimal client written from scratch.

3

03-claude-md-constitution

Side exploration: CLAUDE.md and the constitution/ guidance files.

4

04-stage-2-second-tool-validation

Stage 2: a second tool, divide, and validation with a custom rule.

5

05-stage-3-real-data-source

Stage 3: get_weather, the first tool that calls a real API.

6

06-monorepo-server-client-split

Side exploration: server and client become separate packages.

7

07-web-nextjs-react

Side exploration: the web dashboard rebuilt in Next.js and React.

8

08-server-http-transport

Side exploration: a standalone Streamable HTTP entry point.

9

09-switch-to-pnpm

Side exploration: the repo moves from npm to pnpm.

10

10-stage-4-error-handling-realtime

Stage 4: timeouts and retries, progress updates, and stateful HTTP sessions.

11

11-stage-4-wrapup

Stage 4: the dashboard reconnects after a server restart.

12

12-stage-4-verify-docs

Stage 4: verified cancel and idle sweep, added the dashboard Cancel button.

13

13-stage-5-resources-prompts

Stage 5: resources, prompts and argument completion, a CLI demo, and a tool vs resource vs prompt guide.

14

14-stage-6-testing-ci

Stage 6: Vitest unit, in-memory and HTTP integration tests, a schema snapshot, and a GitHub Actions workflow.

15

15-stage-7-http-framework

Stage 7: the HTTP entry point moves from hand-written node:http to Hono, with the same behaviour.

16

16-stage-8-code-review

Stage 8: a code review server (get_diff, read_file, run_checks, a review_code prompt, a file resource), with a root argument, client roots and path and command safety checks.

17

17-stage-9-authentication

Stage 9: authentication. First commit: the roadmap regrouped into three phases with numbered steps, a planning format (constitution/planning.md) and the Stage 9 plan. Then the build: token issuer, protected-resource metadata, bearer middleware, clients send the token, tests and docs (181 tests).

18

18-run-checks-package-manager

Fix: run_checks uses the project's own package manager (npm, pnpm, yarn, bun), skips scripts that don't exist, and no longer lets pnpm install into the reviewed repo.

19

19-split-review-module

Refactor: review.ts (610 lines) split into a review/ folder with a nested helpers/. No behaviour change.

20

20-stage-10-authorization-hardening

Stage 10: scopes per tool and session owner, Origin check, rate and size limits, audit log, and a validated config that stops the server on a bad value.

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-server and explore-mcp-client predate 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 in docs/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 planned

Colours 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 built

Phase 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 planned

Phase 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 planned

Phase 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).

  1. 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: #1

  2. Stage 2 — Second tool + input validation (on main) Add a second, slightly less trivial tool, and lean harder on zod — 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: #4

  3. Stage 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: #5

  4. Stage 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 — an Mcp-Session-Id issued on initialize, a map of live sessions, one McpServer per 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, #12

  5. Stage 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

  6. 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

  7. Stage 7 — HTTP framework (Hono) (built and merged) Replace the hand-rolled node:http entry in http.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: #15

  8. Stage 8 — Code review server (built and merged) A real use case on top of the server: a review_code prompt (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: a root argument on each tool (the review_code prompt asks the model to pass it), or the client's declared roots; REVIEW_ROOT pins one repo and REVIEW_ALLOWED_ROOTS limits 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 set REVIEW_ALLOW_HTTP=1. run_checks is 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

17-stage-9-authentication

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

20-stage-10-authorization-hardening

What each caller may do, and a record of what they did.

10.1 scopes per tool · 10.2 Origin check · 10.3 rate and size limits · 10.4 audit log · 10.5 validated config and secrets

11. Persistence and scaling

NN-stage-11-persistence-scaling

Sessions outside the process, so restarts and several instances work.

11.1 session store interface · 11.2 Redis store · 11.3 resumable streams (Last-Event-ID) · 11.4 two instances behind a proxy

12. Observability

NN-stage-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

NN-stage-13-containerize-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 tool
addAdd 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

    B3.2/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only a single tool, there is no possibility of confusion or misselection between tools. The purpose (adding two numbers) is unambiguous.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness2/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      Not graded
      maintenance
      A 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A model-agnostic MCP server exposing example tools (add1, multiply2, greet) for learning purposes, working with any LLM through stdio transport.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables users to run a modular TypeScript MCP server that communicates over STDIO and exposes tools for summing numbers and greeting users.
      2
      ISC