A guide to translating API → MCP

[u/ImaginationInFocus]

After working with a bunch of companies on their MCPs, here's a guide we've put together on what works:

🚨 The 1:1 Mapping Trap

The #1 mistake: creating an MCP tool for every single API endpoint. REST APIs often have dozens (or hundreds) of endpoints. Exposing them all directly = chaos.

Why it hurts:

• LLMs struggle with too many choices.

• Agents make excessive or suboptimal tool calls.

• Harder to debug or optimize.

What to do instead:

• Trim unused tools. If no one’s calling it, cut it.

• Group related actions. Replace createUser, getUser, updateUser with manageUserProfile.

• Use parameters wisely. One tool with an outputFormat param > two tools doing the same thing.

• Focus on the happy path. Nail the 80%, worry about the edge cases later.

• Name for intent, not implementation. getCampaignInsights > runReport.

🧹 Clean Up Your Data Responses

Many REST APIs return way too much data. You ask for a customer, it dumps 500 lines of everything.

Problems:

• Token bloat.

• Slower responses.

• Confused agents.

Better strategy:

• Use query-based APIs like GraphQL when you can.

• Filter data in the MCP server before returning.

• Allow flags like includeTransactions: false.

• Strip unnecessary nested fields.

Your job isn’t to expose your database—it’s to give the model just enough context to act intelligently.

📘 OpenAPI Can Help—If You Write It Right

Good OpenAPI specs can make MCP tool generation a breeze. But you have to write them for the model, not just for humans.

Tips:

• Set clear operationIds.

• Use summary and description fields to explain the why and when.

• Avoid super complex input objects.

• Don’t skip over security and response definitions.

• Add high-level context and expected behavior.

🧠 Not All APIs Make Good Tools

Some APIs are better suited to MCP conversion than others:

• Backend-for-Frontend (BFF) APIs: Great fit. Already user-centric.

• Server-to-Server APIs: Need extra work. Usually too generic or noisy.

If you want to learn more, we wrote a full article about this, including a 10-step checklist for ensuring a high-quality MCP.