How to Wrap Your Own API in an MCP Server

Wrapping your API in MCP is less a technical task than a design one. The wrapper code is quick; the work is deciding what you expose and how.

What to expose

The temptation is to mirror the API one to one. Do not.

Expose tasks, not endpoints. You may have three calls to fetch an order, its lines and its delivery status. The agent needs one tool: “get order with contents”. Three tools instead of one means three steps, three context hits and three chances to get it wrong.

Expose what is actually needed. If the agent handles four kinds of task, there should be roughly four tools, not thirty. The rest is context cost and extra ways to choose wrongly.

Do not expose dangerous operations at the start. Deletion, bulk updates, anything involving money. Those get added deliberately, one at a time, usually with human confirmation - see security.

A useful test before adding a tool: can you name the specific agent question it answers? If not, it is not needed.

Descriptions decide everything

This is the central point. The agent chooses a tool by its description, and that matters more than the code behind it.

A good description answers four questions:

• What it does - one sentence.
• When to use it - concretely, with a trigger: “when the order number is known”.
• When not to use it - the most skipped item and the most valuable. It prevents redundant calls.
• What comes back, including the “nothing found” case.

Bad: “Order handling.”

Good: “Returns an order and its line items by number. Use when the number is known. There is a separate tool for finding a customer’s orders. If the order is not found, returns an empty result rather than an error.”

The same applies to arguments: every parameter needs a description clear enough that the agent knows what to put there. A type parameter with no enumerated values guarantees mistakes.

And once more: one tool does one thing. A tool with a “mode” parameter taking five values is five tools the agent will confuse.

Authentication

Two scenarios, structurally different.

The server acts as one technical user. The token sits in an environment variable and is used for every call. Simple, and fine for internal work. That user’s permissions should be minimal.

There are several users. The token is supplied at session initialisation and the server acts on behalf of a specific person. More complex, but necessary wherever access separation matters.

A rule common to both: the secret must not enter the agent context. Do not build a tool that takes a token as a parameter: the agent will see it, and it will travel to the model provider along with everything else.

Limits

Mandatory, not optional. A tool response enters context whole, and without limits one call can consume the window.

What to limit:

• Records per response, with an explicit note that the result was truncated and a way to fetch the next page.
• Text field length. The agent does not need a three-screen product description.
• Call count. Protection both against a looping agent and against load on your system.
• Heavy operations. A yearly report is better returned as a summary than row by row.

A related recommendation: compute on your side. An agent handed a thousand rows to sum them will spend context and get it wrong. A tool that returns the computed figure is cheaper and more accurate.

Errors

Return text explaining what went wrong and what to do. “No customer found for that phone number” is more useful than a 404: the agent reads it and refines the query. An empty response with no explanation will most likely be read as “no data” and completed with invention.

How to write the server itself: an MCP server in Python. A worked example on a specific system: an MCP server for 1C. The overview is in the MCP guide.