mcp-tools knowledge base

mcp-tools is a small MCP server on Cloudflare Workers. Three read-only tools (convert_units, time_in_zone, text_stats) answer from their input alone; the Worker serves them over Streamable HTTP at /mcp, limits each client's tool calls with a Durable Object and counts calls in KV.

How it works

• [[tool-design]]: what every tool has (name, description for the model, schemas, structured output) and how failures reach the model.
• [[http-transport]]: how a POST to /mcp becomes an MCP response, and what the Worker does around it.
• [[rate-limits]]: the per-client token bucket and the Durable Object that holds it.
• [[usage-counts]]: what /stats counts, where, and how far to trust it.

Why it is this way

• [[0001-stateless-streamable-http]]: a fresh server per request, no sessions.
• [[0002-tool-errors-are-results]]: failures come back as tool results the model can read.
• [[0003-usage-counts-in-kv]]: approximate counters in KV rather than a Durable Object.
• [[0004-per-client-rate-limit]]: an exact limit per client IP, refused calls answered as tool results.

How to

• [[adding-a-tool]]: from a new file in src/tools/ to a passing test.
• [[connecting-a-client]]: Claude Desktop, the MCP Inspector, or curl.