mcp-sandbox: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A public MCP (Model Context Protocol) server of test fixtures for QA and evals. Each tool returns deliberately distinctive output so a caller can prove a response originated from this server, not from the model's own training/context. Live at https://mcp.heptafox.com/mcp on AWS Lightsail (Ubuntu) behind nginx + Let's Encrypt.

Commands

uv sync                 # install deps into .venv
uv run server.py        # run server: guide at :8000/ , MCP at :8000/mcp
uv add <pkg>            # add a dependency

There is no test framework — the tools are constant returns. To smoke-test a tool in-memory (no network), use the FastMCP Client against the mcp object:

uv run python -c "
import asyncio; from fastmcp import Client; from server import mcp
async def m():
    async with Client(mcp) as c:
        print((await c.call_tool('identity', {})).content[0].text)
asyncio.run(m())"

Architecture

Single-process design: one uvicorn serves both the static guide and the MCP endpoint, from server.py:

• @mcp.tool functions are the MCP tools, ordered as a learning progression: identity (no auth, no params) → echo (params) → auth_check (Bearer token, fixed dev token in DEV_TOKEN).
• @mcp.custom_route(...) serves the static files in web/ (guide page, logo, robots.txt, sitemap.xml).
• mcp.run(transport="http", ...) = FastMCP streamable HTTP transport.

Routes (same port): GET / → guide page, POST /mcp → MCP endpoint.

New tools go in the same server.py as additional @mcp.tool functions — no new files needed.

Gotchas

• Endpoint is /mcp, no trailing slash. FastMCP 3.x 307-redirects /mcp/ → /mcp, and mcp-remote (the Claude Desktop bridge) drops the POST body across that redirect → 404. Always configure clients with /mcp.
• Bind 127.0.0.1 only. nginx terminates TLS and proxies in; the app port is never exposed publicly. deploy/nginx.conf proxies both location /mcp (matches /mcp and the redirect) and location / (the guide), with buffering off and long read timeouts on /mcp for streaming responses.
• Reading the Authorization header needs get_http_headers(include_all=True). FastMCP strips authorization from the default header set — plain get_http_headers() will never see it (see auth_check).
• web/index.html fills in the live URL via JS (location.origin), so the Claude config snippets show the real deployed URL with no hardcoding.