Make Your REST API Callable by Claude: A Practical MCP Primer

Most APIs in 2026 still ship the same artifacts they shipped in 2016: an OpenAPI spec, a SwaggerUI page, maybe a Postman collection if the team is feeling generous. Those are great for humans. They are not enough for the thing that is actually consuming your API more and more often — an LLM running inside an editor or chat client.

If you want Claude, Cursor, Continue, or any other agent to call your API rather than just describe it, you need a Model Context Protocol (MCP) endpoint. This post explains what MCP is, why it's different from OpenAPI, and how to ship one without rewriting your backend.

OpenAPI tells. MCP does.

An OpenAPI spec is a description: "here is POST /v1/customers, here are its fields, here are its responses." An agent reading OpenAPI knows about your API. It still has to translate that knowledge into an HTTP request, sign the auth, parse the response, and handle errors — every single time, in every project.

MCP is different. An MCP server exposes your API as callable tools. The agent doesn't see "an HTTP endpoint at this URL" — it sees create_customer(name, email, plan) as a function it can invoke. Authentication, base URL, content types, retry behavior, and response parsing all live on the server side. The agent just calls the tool.

In practice that means:

• The model spends fewer tokens reasoning about HTTP and more tokens reasoning about your domain.
• Auth secrets stay on the MCP server, not in the model's context window.
• You control which operations are exposed, and at what granularity.
• The same MCP server works in Claude Desktop, Cursor, Continue, Zed, and anything else that speaks the protocol.

What an MCP server actually exposes

An MCP server has three primitives:

Tools — functions the agent can call. Each tool has a name, a description, a JSON Schema for its arguments, and a handler that returns a result. This is where most of your API surface lives. A GET /orders/:id becomes get_order(order_id). A POST /orders becomes create_order(items, customer_id).

Resources — read-only documents the agent can pull into context on demand. Use these for things like "the current pricing table" or "the latest changelog." Resources are addressable by URI and are cheaper than tools because they don't require a round-trip decision from the model.

Prompts — pre-baked prompt templates with named arguments. Less commonly used, but handy when you want to ship a "summarize this customer's last 30 days" workflow rather than a raw tool.

For most teams, tools and resources are 95% of the work.

The four design decisions that matter

When you turn an existing REST API into an MCP server, four choices determine whether agents will actually use it well.

1. Pick tool granularity carefully. A common mistake is exposing one tool per HTTP endpoint. That gives the agent 200 tools and a paralysis problem. Instead, group related operations into intent-shaped tools. find_customers(query) is more useful than list_customers + search_customers + get_customer_by_email + get_customer_by_id. The model is good at picking between 20 tools. It is not good at picking between 200.

2. Write descriptions for the model, not the docs site. Tool and parameter descriptions are the primary signal the model uses to decide whether and how to call a tool. Replace marketing copy ("Powerful customer management") with operational copy ("Returns up to 25 customers matching the query. Use cursor from the previous response to paginate. Searches across name, email, and external_id."). Mention edge cases. Mention what the tool does not do.

3. Make errors readable. When a tool call fails, the model sees the error text and decides what to do next. A 400 with {"error": "invalid_request"} tells the agent nothing. A 400 with "customer_id 'cus_123' was not found — did you mean cus_124?" lets the agent self-correct on the next turn. Spend an afternoon on error messages. It pays back ten-fold in retry quality.

4. Decide what to not expose. Your destructive endpoints (DELETE /accounts, POST /transfers) probably don't belong in MCP at all, or belong behind a confirmation flow. The agent will try things. Assume any tool you expose will eventually be called by an agent doing something you didn't anticipate.

A minimal example

Here's the smallest interesting MCP server in Python — a single tool that proxies a real HTTP call:

from mcp.server.fastmcp import FastMCP
import httpx, os

mcp = FastMCP("orders-api")
BASE = "https://api.example.com"
TOKEN = os.environ["ORDERS_API_TOKEN"]

@mcp.tool()
def get_order(order_id: str) -> dict:
    """Fetch an order by ID.

    Args:
        order_id: The order's external ID, e.g. 'ord_abc123'.

    Returns the full order including line items, status, and shipping.
    """
    r = httpx.get(
        f"{BASE}/v1/orders/{order_id}",
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=10.0,
    )
    if r.status_code == 404:
        return {"error": f"order_id '{order_id}' not found"}
    r.raise_for_status()
    return r.json()

if __name__ == "__main__":
    mcp.run()

That's it. Point Claude Desktop or Cursor at it and the agent can now fetch orders. Add four or five more tools — search_orders, create_order, refund_order, list_recent_orders — and you have a usable surface.

The "I don't want to maintain a second server" problem

The catch with hand-rolled MCP servers is the same catch every API team already knows: now you have two things that have to stay in sync. Your OpenAPI spec changes, your handlers change, your auth changes — and your MCP server drifts.

This is the part of the problem APIKumo handles automatically. Every collection you publish on APIKumo gets an MCP endpoint generated from the same schema that powers your docs. When you bump the schema, the MCP endpoint updates. Auth, base URLs, and pre/post-processors flow through. There's nothing to deploy.

If you'd rather hand-roll it, the Python SDK and TypeScript SDK are both solid and the protocol itself is small enough to read in an afternoon.

What to ship this week

If you want to make your API agent-callable without a big project:

• Pick the 10–20 operations that cover 80% of the use cases. Skip the rest.
• Write tool descriptions like you're explaining the API to a new hire over Slack, not like you're writing brochure copy.
• Run a smoke test: open Claude Desktop, point it at your MCP server, and try ten realistic tasks. The first round will tell you which descriptions are too vague and which tools are too coarse.
• Iterate on descriptions before adding more tools. Description quality matters more than tool count.

OpenAPI told agents about your API. MCP lets them actually use it. The teams that ship an MCP endpoint in 2026 are going to feel like the teams that shipped a mobile app in 2010 — a meaningful step ahead of the ones that didn't.

---

APIKumo is an API workspace that builds, automates, and publishes typed docs with an MCP endpoint generated automatically from every published collection. Try it free while in preview →