MCP servers designed for the caller you actually have
MCP lets agents call your tools. Good MCP design is API design for a model caller.
What this covers
What I set up and check with your team.
Tool surface design
Expose the few tools the model can call accurately, with clear names, arguments and failure modes.
Scopes, secrets, and identity
Authentication, per-user scopes, secret storage and agent-host identity are designed before the server is useful.
Transport choice
stdio or Streamable HTTP is chosen deliberately, with notes on what would justify changing it later.
Resources, prompts, and notifications
Tools, resources, prompt templates and notifications are separated so the agent gets the right surface.
Review and observability
Per-tool calls, latency, errors and caller traces show what the agent actually used last week.
The tool surface the agent sees
Agents are early
About three in ten developers use AI agents at work. More than eight in ten worry about their accuracy and data security.
- Use agents daily14.1%
- Use agents weekly9%
- Use agents monthly or less7.8%
- Plan to17.4%
- Autocomplete only13.8%
- No plans37.9%
- Accuracy of what agents produce86.9%
- Security and privacy of data81.4%
Few manage the risk
Fewer than a quarter of UK businesses using or considering AI have practices to manage its cyber risk.
- 24%Manage AI security risk
- 76%No AI security practices reported
See the engagement shape
Review the sequence, review gates and handover before you book.
How the work runs
A bounded sequence turns the tool decision into an operating habit.
- Week 1
Tool inventory
Which internal tools exist, which the agent should reach, what the existing API surface already does, and what new shape the MCP server needs.
- Week 2
Design and skeleton
Tool naming, argument schema, scopes, transport and error model. First tools go live in a skeleton server.
- Week 3
Real integration
Codex, Claude Code or an internal agent calls the server on real tasks. Logs shape the tool surface.
- Week 4
Hardening and handover
Secrets in the right vault, observability live, runbook written, and a written review of the design decisions and what would trigger a revisit.
Questions teams ask before the work
Should we run our own MCP server, or use one?
Both, depending on the tool. Off-the-shelf servers exist for common things and there is no point reimplementing them. Custom servers are worth it when the tool is specifically yours: an internal API, a domain-specific search, a private dataset.
Which transport should we use?
stdio for local single-developer use; Streamable HTTP for anything shared or remote (it carries streamed results; the older HTTP+SSE transport is deprecated). The choice is decided early because changing it later is expensive.
How does this fit our identity layer?
The MCP server should look like any other API to the identity layer: it is a client of the same SSO, it respects the same scopes, and its calls show up in the same audit trail. The agent does not get a parallel identity universe.
Keep exploring
Book an MCP design call
Most useful where the team has internal tools they want an agent to reach. If the only goal is using off-the-shelf MCP servers in Claude Code, the Claude Code workshop is a better starting point.