Demo-MCP

A minimal Model Context Protocol server in Python, served over streamable HTTP from a Docker container.

What it exposes

The HTTP client's ETag cache and github_repo_overview's 60-second TTL cache both live in process memory, so they reset whenever the container restarts.

Related MCP server: mcp-server-http-streamable

Setup

The server requires a shared bearer token. Generate one and put it in .env:

make token          # prints a random token
cp .env.example .env
# paste the token as MCP_AUTH_TOKEN in .env

The GitHub tools work without any further setup, limited to GitHub's unauthenticated rate limit (60 requests/hour). To raise that limit, add a personal access token as GH_API_TOKEN in .env — see Two tokens below.

docker compose reads .env automatically, so make up picks it up with no extra flags.

Run it

docker compose up --build

The endpoint is http://localhost:8000/mcp.

While iterating on the demo_mcp/ package, this reloads the container on save:

docker compose watch

Connect from another Claude Code session

claude mcp add --transport http demo-mcp http://localhost:8000/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Then in that session, /mcp lists the connection and the tools show up as mcp__demo-mcp__github_repo_overview, etc.

To remove it later:

claude mcp remove demo-mcp

Two tokens

There are two distinct auth layers, and conflating them is an easy misread:

MCP_AUTH_TOKEN is required; the server refuses to start without it (or without MCP_AUTH_DISABLED=1). GH_API_TOKEN is optional — its absence degrades to GitHub's 60 requests/hour unauthenticated limit rather than refusing to start, and a warning is logged once when the GitHub client is first used. The token is never echoed in tool output, error messages, or logs.

Adding a tool

Add a plain, undecorated function to the relevant module under demo_mcp/tools/ (e.g. demo_mcp/tools/demo.py), then bind it in that module's register() — the type hints become the input schema and the docstring becomes the tool description, so both matter to the calling model:

def word_count(text: str) -> int:
    """Count whitespace-separated words in the given text."""
    return len(text.split())


def register(mcp: MCPServer) -> None:
    ...
    mcp.tool()(word_count)

Async functions work too, and adding a ctx: Context parameter gives you await ctx.info(...) for logging back to the client and await ctx.report_progress(...) for long operations. The parameter is injected by the SDK and is not part of the tool's schema.

A new tool domain (a new file under demo_mcp/tools/) needs one more line: call its register() from register_all() in demo_mcp/tools/__init__.py.

Makefile

Wraps the commands above. Run make (or make help) to list targets.

Releasing

Commits follow Conventional Commits: feat: bumps the minor version, fix:/perf: bumps patch, and a ! or BREAKING CHANGE: footer bumps major (minor, while the project is still 0.x). Merging to main runs python-semantic-release automatically — it computes the next version from commit history, updates pyproject.toml and __version__ in demo_mcp/__init__.py, tags the commit, generates CHANGELOG.md, and publishes a GitHub Release. PRs are squash-merged, so the PR title is what gets parsed — it must itself be a valid Conventional Commit, and CI lints it.

Notes

• The server binds 0.0.0.0 inside the container so Docker can publish the port; only 8000 on the host is exposed.

• Auth is a single shared static bearer token (MCP_AUTH_TOKEN), not OAuth. There's no rotation and no per-client identity — everyone holding the token is demo-client. The issuer_url set in server.py is a placeholder; no authorization server actually runs. This is appropriate for a localhost demo only — keep the published port off any untrusted network, and note there's no TLS, so the token is exposed to anything on the network path.

• demo_mcp/server.py imports MCPServer with a fallback to FastMCP, the SDK's older name for the same class, so it builds against either release line.