What this is
Tool focus: Model Context Protocol
Design Model Context Protocol (MCP) servers and integrations for agentic AI: tool surface, scopes, secrets, transport choice and review patterns.
Model Context ProtocolMCP server design and integrationTool surface design
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.
The tool surface is the interface — designed for the model that calls it.
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, HTTP or SSE is chosen deliberately, with notes on what would justify changing it later.
How an engagement runs
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.
Common questions
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 integration, HTTP for shared internal services, SSE where the tool produces a stream the agent should react to. 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.