agent-06-mcp-server

A remote Model Context Protocol (MCP) server on Cloudflare Workers, plus a small agent where Llama 3.3 acts as the MCP client and picks tools itself. JSON-RPC 2.0 over Streamable HTTP (stateless), on the free tier. Project 6 of a 10-part agentic AI portfolio.

Live demo: https://agent-06-mcp-server.braylo777.workers.dev · MCP endpoint: https://agent-06-mcp-server.braylo777.workers.dev/mcp

What it is

• An MCP server any MCP client can connect to. It exposes 4 tools (calculator, word_stats, search_notes, utc_time) and 1 resource (notes://all).

• /api/agent: give it a task in plain English. Llama 3.3 reads the server's tools/list, chooses a tool and its arguments, the call runs through the same JSON-RPC handler, and the model answers from the result.

Related MCP server: remote-mcp-server-authless

Architecture

flowchart LR
  C[Any MCP client<br/>Claude, Cursor, Inspector] -->|POST /mcp JSON-RPC 2.0| W[Cloudflare Worker]
  U[Demo UI] -->|POST /api/agent| W
  W --> RL{Rate limit<br/>5 req/min/IP}
  RL --> H[MCP handler<br/>initialize · ping · tools/* · resources/*]
  RL --> A[Agent loop]
  A -->|tools/list as function schemas| L[Llama 3.3 70B<br/>Workers AI]
  L -->|tool call| A
  A -->|tools/call| H
  H --> T[calculator · word_stats<br/>search_notes · utc_time]
  A -->|result + one-line answer| U

How it works

• src/mcp.js: the MCP server. It validates the JSON-RPC envelope, echoes request ids, answers notifications with 202 and no body, supports batches, and uses the spec's error codes (-32600, -32601, -32602). A tool failure returns isError: true instead of crashing.

• src/calc.js: a safe arithmetic parser (no eval, which Workers forbid).

• src/agent.js: LLM-as-MCP-client. It turns tools/list into function-calling schemas and reads the model's tool call, either native tool_calls or a JSON-text fallback.

• Guardrails: 5 requests/min per IP, 500-character cap on agent tasks.

Eval results

Run live against the deployed server (node evals/run.mjs). Raw per-case output is in evals/results.json. Run on Oct 27, 2026.

2 of the 10 agent cases did not run: the account's shared Workers AI daily free allocation ran out mid-eval. They are excluded from the rates, not counted as passes. Sample sizes are small (12 protocol cases, 8 agent cases), so treat these as smoke-level numbers.

Tests

17 offline unit tests (node:test, model mocked): every JSON-RPC method, error codes, id echo, notifications, batches over HTTP, 405 on GET, calculator precedence and bad input, word_stats, search_notes hit and miss, resources, tool-schema mapping, parsing native and JSON-text tool calls, and the agent routing a model's call through MCP.

npm test

Run it

npm install
npm test             # offline unit tests (Node 20+)
npx wrangler dev     # local
npx wrangler deploy  # free tier, no paid API keys
node evals/run.mjs   # live eval, throttled to the rate limit; writes evals/results.json

Connect a client: npx @modelcontextprotocol/inspector, then choose transport "Streamable HTTP" and URL <your-worker>/mcp.

Stack

Cloudflare Workers · Workers AI (Llama 3.3 70B, function calling) · MCP 2025-06-18 · vanilla JS · node:test

License

MIT