Designing MCP for AI

Why exposing every API endpoint is usually wrong — naming, granularity, and descriptions the model can follow.

OpenAPI-to-MCP generators feel productive for an afternoon. Then the model picks updateIssueCustomField47 and you spend a week writing descriptions. Design the interface for a language model, not for a typed SDK client.

Why a 1:1 wrap fails

Too many tools: the model’s catalog is a haystack.
CRUD names do not match user intent (“make a ticket for the outage”).
Optional query parameters explode the schema. The model fills the wrong ones.
Error bodies from the API are written for engineers, not for a next tool call.

A better grain

One tool per job. Combine reads that always travel together. Hide fields the assistant should not set. Use enums in descriptions (“status is open or done”) when the schema cannot say it.

Write descriptions like runbooks

Bad: “Gets issues.” Good: “List open bugs on the default board, newest first. Use this when the user asks what is broken. Do not use this to create issues.” Negative instructions matter.

Version the surface

Renaming a tool is a breaking change for saved chats and host caches. Add list_open_issues_v2 if you must, and deprecate in the old description. Keep a changelog in the repo the humans read.

Check it

Print your tool list. If you cannot explain each name in one spoken sentence, merge or delete. Then take that list into the capstone.