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.
MCP servers designed for the caller you actually have.
MCP is the protocol that lets agents call your tools. Designing a good MCP server is mostly an API design problem with one extra constraint: the caller is a model, not a person.
The tool surface is the interface — designed for the model that calls it.
Tool surface design
Which tools to expose, how they should be named, what arguments they take, and what the failure mode looks like. The aim is a tool surface a model can use accurately on the first try, not a wrapper around every internal endpoint.
Scopes, secrets, and identity
Authentication and authorisation on the MCP server. Per-user scopes where it matters. Where the secret lives, who can rotate it, and how the agent host proves it is allowed to make the call. Mistakes here are the most common failure mode.
Transport choice
stdio for local agent integration, HTTP for shared services, SSE where streaming is needed. The wrong transport is a year-long mistake; we pick deliberately, with notes on what would change the answer later.
Resources, prompts, and notifications
When to model something as a tool, when as a resource, when as a prompt template, and when to push a notification back to the agent. These distinctions look subtle on paper and matter a lot in practice.
Review and observability
The MCP server is logged like any other API: per-tool call counts, latency, error rates, and per-caller traces. Reviewing what the agent actually called for in the last week is the highest-leverage feedback loop in agentic work.
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 choice, error model. A working skeleton server with the first one or two tools live.
Week 3
Real integration
The agent (Codex, Claude Code, internal) calls the server on real tasks. Logs are reviewed daily. Tool surface is adjusted in light of real call patterns.
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.
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.