MCP Automations

MCP Automations

A production-grade Model Context Protocol server in Python — four LLM-callable tools, two transports, deployed two different ways.

# 30-second proof the server is up:

curl -X POST https://mcp-automations.fly.dev/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","method":"initialize","id":1, "params":{"protocolVersion":"2024-11-05", "capabilities":{}, "clientInfo":{"name":"curl","version":"1"}}}'

What this is

Most "AI engineer" portfolio projects are *applications* (a RAG chatbot, an agent that does research). This project is the layer underneath — the typed tools an LLM can call and the transport plumbing that exposes them. MCP is the emerging standard for LLM tool use (~97M monthly SDK downloads as of early 2026); building one — not just consuming one — is the rare skill.

For a deeper look at the design decisions — why two transports, how cost telemetry works, the exception hierarchy, what I'd do differently — see WRITEUP.md.

Tools

Plus one MCP resource (automations://catalog) and one MCP prompt (daily_brief) — using all three MCP primitives, not just tools.

Every tool returns a typed Pydantic model with per-call token usage and dollar cost attached. Cheap tasks route to Haiku 4.5 ($1/M in, $5/M out), writing-heavy tasks to Sonnet 4.6 ($3/M in, $15/M out).

Connect Claude Desktop to this server

Add one of these to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%/Claude/claude_desktop_config.json (Windows), then restart Claude Desktop.

Option A — local stdio (no network, runs the server as a subprocess):

{

"mcpServers": { "mcp-automations": { "command": "python", "args": ["-m", "mcp_server.server"], "cwd": "/absolute/path/to/mcp-automations", "env": { "ANTHROPIC_API_KEY": "sk-ant-...", "TAVILY_API_KEY": "tvly-..." } } } }

Option B — remote HTTP (talks to the live Fly server, no local setup):

{

"mcpServers": { "mcp-automations": { "url": "https://mcp-automations.fly.dev/mcp", "transport": "http" } } }

Then ask Claude something like *"summarize https://www.paulgraham.com/greatwork.html in 3 bullets"* — it'll call summarize_url automatically.

Run locally

pip install -r requirements.txt

Stdio (for Claude Desktop):

python -m mcp_server.server

HTTP server (defaults to 0.0.0.0:8765):

MCP_TRANSPORT=http python -m mcp_server.server

Streamlit playground:

streamlit run playground/app.py

Requires Python 3.13. Needs ANTHROPIC_API_KEY and TAVILY_API_KEY in .env (see .env.example).

Architecture

┌────────────────┐     stdio      ┌──────────────────────┐

│ Claude Desktop ├───────────────►│ │ └────────────────┘ │ │ │ mcp_server/ │ ┌────────────────┐ HTTP/JSON │ server.py │ │ Remote client ├───────────────►│ (FastMCP) │ └────────────────┘ (Fly.io) │ │ │ 4 tools │ ┌────────────────┐ direct call │ 1 resource │ │ Streamlit UI ├───────────────►│ 1 prompt │ └────────────────┘ └──────────┬───────────┘ │ ┌──────────┴───────────┐ │ Anthropic + Tavily │ │ (lazy clients) │ └──────────────────────┘

The same Python callables back all three entry points. The transport is just a wrapper.

What's in this repo

mcp-automations/

├── mcp_server/ │ ├── server.py # FastMCP server: 4 tools + 1 resource + 1 prompt │ ├── models.py # Pydantic I/O schemas (incl. per-call Cost telemetry) │ └── exceptions.py # MCPToolError + UpstreamAPIError / EmptyLLMResponseError / ExtractionError ├── playground/ │ └── app.py # Streamlit UI with per-session call + spend caps ├── tests/ # offline unit tests (httpx/anthropic/tavily all mocked) ├── Dockerfile # python:3.13-slim, MCP_TRANSPORT=http for Fly ├── fly.toml # shared-cpu-1x, 256mb, auto-stop when idle └── .github/workflows/ # ruff + strict mypy + pytest on every push

Production touches worth noting

• Cost telemetry on every tool response (models.Cost) — token counts and USD attached so a client doesn't have to re-derive it.
• Cost-aware model routing — cheap tasks → Haiku, writing tasks → Sonnet.
• Domain-specific exception hierarchy — UpstreamAPIError, EmptyLLMResponseError, ExtractionError each route differently in logs and the Streamlit UI.
• Two transports, one codebase — MCP_TRANSPORT=stdio|http env switch; HTTP host/port from env so the same image runs on Fly.
• Per-session abuse caps in the playground — 20 calls / $0.50 max per session; backed by a $2/mo hard cap on the Anthropic console.
• Strict mypy + ruff + pytest in CI on every push (.github/workflows/ci.yml).

Why MCP

MCP is transport-agnostic, so one server serves both a local Claude Desktop user (stdio subprocess) and a hosted multi-tenant deployment (HTTPS). It also exposes three primitives that most demos skip:

• Tools — functions the model decides to call (4 of them here)
• Resources — read-only data the client can fetch by URI (automations://catalog returns the tool list as JSON)
• Prompts — server-side templates the user explicitly invokes (daily_brief chains daily_digest + repurpose_content)

Using all three is a signal of reading the spec, not just a quickstart.

Status

✅ Code on GitHub, CI green ✅ Public playground on Streamlit Cloud ✅ Public MCP HTTP server on Fly.io ✅ Cost protection (per-session caps + monthly Anthropic cap) ✅ Real test coverage (23 offline unit tests) ✅ Listed on the Official MCP Registry as io.github.wzltmp/mcp-automations ✅ Long-form writeup of design decisions ✅ Consumed by another agent, not just demoed — langgraph-research-agent's read_node calls this server's summarize_url tool over HTTP (with local fallback if the call fails) 🚧 Demo gif + screenshots (planned) 🚧 n8n self-host via docker-compose (planned)

License

MIT.