Build an MCP Server from Your API

What you'll build

An MCP server that wraps your existing API so any MCP-compatible client — Claude Desktop, Cursor, your internal agent — can call it without custom glue per client.

If you haven't read MCP Explained yet, start there. This workflow is the hands-on follow-up.

Why MCP for your API

Before MCP, integrating your billing API into three AI surfaces meant three separate plugins. MCP standardizes the wire format:

• Tools — actions (create ticket, refund order, search customers).
• Resources — read-only context (account summary, open incidents).
• Prompts — reusable templates your server ships to the client.

The client still uses the model's native tool-calling API. MCP just defines where those tools come from.

Step 1 — Curate the surface

Don't mirror your OpenAPI spec 1:1. Ask: what would a helpful coworker need in chat?

Good first tools:

Defer until v2: bulk exports, admin deletes, anything irreversible.

Step 2 — Scaffold the server

TypeScript (most common for MCP servers):

npm init -y
npm install @modelcontextprotocol/sdk zod

Python:

pip install mcp httpx

Register each tool with a schema the SDK validates before your handler runs. Tight schemas = fewer bad API calls.

Step 3 — Tool handlers

Each handler should:

1. Validate input (SDK does this if schemas are correct).
2. Call your API with the user's credentials from env.
3. Return concise, structured text — not a 50 KB JSON dump unless asked.
4. On failure, return an actionable error string.

Example response shape:

Customer: Acme Corp (id: cust_8f2a)
Plan: Pro ($299/mo) · 12 seats · renews 2026-07-01
Open tickets: 2 (billing, SSO setup)
Last login: 2026-06-04

The model can quote this directly in chat.

Step 4 — Resources for read-heavy lookups

Tools are for actions and lookups the model chooses. Resources are for data the client can prefetch.

Expose stable URIs:

• customer://{id} — full account snapshot
• docs://runbooks/billing — internal markdown your team maintains

Resources shine when the same context gets attached to many conversations.

Step 5 — Auth

Pattern that works:

API_BASE_URL=https://api.yourco.com
API_KEY=sk_live_...

For OAuth SaaS (Linear, Slack, GitHub): complete OAuth once, store refresh token locally, refresh in the server on startup. Never pass tokens through the model's context.

Step 6 — Connect the client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "your-api": {
      "command": "node",
      "args": ["/path/to/server/dist/index.js"],
      "env": {
        "API_KEY": "..."
      }
    }
  }
}

Cursor — same shape in MCP settings. Restart after changes.

Smoke-test: ask the client to "look up customer X" and verify the tool call in logs.

Production guardrails

• Read-only v1 — ship reads first, add writes with dry_run or confirmation.
• Rate limits — wrap your API client with backoff; the model will retry aggressively.
• Audit log — append-only local log of tool name + args hash + timestamp.
• Allowlist — if the API is powerful, restrict which tools appear per environment.

What to build next

Once the base server works:

• Composite tools — prepare_support_context(customer_id) that fetches customer + tickets + recent orders in one call.
• MCP prompts — ship "Investigate billing dispute" as a server prompt with embedded tool hints.
• HTTP transport — host for the team when local stdio doesn't scale.

The platform compounds. Your API becomes a first-class citizen in every AI surface your team uses.