MCP Server Development

Transports: stdio, Streamable HTTP, and Where the Server Runs

The specification defines two standard transports, and the choice gets made early because it decides where the server process lives. With stdio, the client launches the server as a child process and the two exchange newline delimited JSON-RPC messages over stdin and stdout; individual messages cannot contain embedded newlines, and anything written to stderr is treated as log output rather than protocol traffic. With Streamable HTTP, the server is a service at a single endpoint: the client POSTs JSON-RPC messages to it and receives either a JSON response or a Server-Sent Events stream, and it can open a GET stream on that same endpoint for messages the server initiates. An earlier transport that used two separate HTTP endpoints, one for POSTs and one for SSE, is deprecated but still spoken by older clients.

A stdio server runs on the workstation, as the user who started the client, inheriting that user's environment and credentials. There is no listener to attack and no session state to manage, because the operating system account is already the permission boundary. What you give up is central control: the version in use is whatever each machine happens to have, and the audit trail is a file on that machine unless the server ships it somewhere.

A remote server runs once, somewhere you operate, and every user reaches the same process. It has to do explicitly what stdio got from the operating system: terminate TLS, validate a credential on every request, keep sessions apart, and apply rate limits. A server that listens on HTTP locally is a special case worth naming, since it should still validate the Origin header and bind to 127.0.0.1 rather than 0.0.0.0, or a page open in the user's browser can reach it through DNS rebinding. The practical differences follow from that:

• Updates. A remote server is one deployment on one version, so a fix reaches every user at once and a rollback is a single action. A stdio server is installed per workstation and changes when each user's client or package updates.
• Visibility. A remote server logs where you can query it. A stdio deployment writes its audit records on each machine, so central logging is a separate piece you have to build and keep working.
• Data locality. A stdio server can read whatever the user's machine can read, including a local checkout or a mounted share. A remote server sees only what it can reach from its own network position, which rules it out for work that depends on files that never leave the laptop.
• Credential exposure. A remote server holds its credentials in one place, where they can be rotated on a schedule. Distributing a stdio server means distributing whatever it authenticates with to every machine that runs it.

How Authorization Works on a Remote MCP Server

On a remote server the current specification puts you in the OAuth 2.1 resource server role: the server validates tokens and never issues them. It advertises where tokens come from by serving protected resource metadata at /.well-known/oauth-protected-resource, per RFC 9728, and by returning a WWW-Authenticate header on a 401 that points at that document. From there the client reads the authorization server's own metadata (RFC 8414), registers itself, often through dynamic client registration (RFC 7591), and runs an authorization code flow with PKCE, passing a resource indicator (RFC 8707) so the token it receives is minted for your server specifically.

Validation on the server side starts with an audience check: a token issued for a different resource is rejected even though it is genuine and unexpired. The specification is also explicit that the caller's token must not be forwarded to the upstream API, which raises the question of what the server presents instead. Carry the caller's identity forward: after validating the token, the server exchanges it for an upstream credential scoped to that same user, through a token exchange (RFC 8693) at your identity provider or through a per-user grant captured when that user first connected. Upstream permissions and upstream logs then reflect the individual, which is what makes per-user scoping real rather than nominal. An application identity is the fallback for upstream systems that cannot represent individual users at all, and it shifts the burden onto the server, which now has to carry the caller's identity into its own authorization checks and its own audit records because the upstream system no longer will.

These failures present as connectivity problems and are not. A client reporting that it cannot connect is often receiving a 401 with no WWW-Authenticate header, or metadata served on a host or path that does not match the URL the user typed, so discovery never starts and there is nothing in the server's application log to see. Fetch the metadata URL derived from the server URL and read the 401 headers directly before looking anywhere else; if both are correct and the flow still fails, the next suspects are a redirect URI the authorization server does not have registered and a token whose audience does not match. Tokens also expire mid-run on long agent sessions, so an expired token has to produce a 401 the client can act on rather than a 500 it cannot.

Evaluating Tool Behavior Before Rollout

The tool name, its description and its JSON Schema are the entire interface the model sees. They are prompt text, not documentation: a parameter called id with no description gets guessed at, a set of allowed values written as free text gets invented values, and two tools whose descriptions cover overlapping ground get chosen between arbitrarily. Most corrections during an evaluation pass are wording and schema changes rather than code changes, which is the argument for running that pass before the tool surface is frozen into client configurations that are painful to update.

Error text is read by the model as well, so it is part of the interface too. A failure that returns invalid request produces a retry with the same bad argument; one that names the field, the constraint and the acceptable values usually produces a corrected call. Return execution failures as tool results marked as errors, where the model can see and respond to them, and reserve protocol level errors for calls that could not be attempted at all.

The failure modes cluster, and each has its own diagnostic:

• The wrong tool is called. Two descriptions overlap, or one is written for a human reader who already knows the system. Read the client's call trace rather than the server log, because the server never saw the call that was not made.
• The right tool is called with bad arguments. The schema is under-specified: dates without a format, identifiers without an example, fields marked optional that are only optional in certain combinations. Fix it in the schema, not in prose appended to the description.
• A routine task turns into a long chain of calls. This usually means a missing lookup: with no way to search by name, the model lists and filters records just to find the identifier it needs before the real work starts.
• The run stops partway. Often context exhaustion from tools returning whole records where an identifier and three fields would do. Pagination, field selection and truncation are server-side decisions, and the defaults matter more than the options because the model takes the default.
• Every call succeeds and the answer is still wrong. The data was real but scoped differently from what a person would have opened: a default filter, the wrong tenant, a cached view that is hours old.

What the Work Depends On From You

The server can only expose what your system already exposes programmatically. Where a workflow exists only in a user interface, with no API, no documented write path and no service account that can perform it, building that interface comes first and is a separate project with its own review. Screen automation is not a substitute: it breaks on layout changes and cannot be scoped or audited one operation at a time.

• A non-production environment with working credentials, holding data realistic enough to judge behavior against. A test tenant with three tidy records hides exactly the ambiguity that causes trouble in production.
• A domain expert available during design, not only at sign-off. Someone who does the work daily can say what a field actually means in practice, which operations exist but are never used, and which requests arrive ambiguous often enough that the server should ask rather than assume.
• The upstream rate limits and quotas, including any that apply per account rather than per key. An agent produces call patterns no human client generates, and a loop that looks harmless can consume a daily quota in minutes.
• A decision on what should happen when a request is ambiguous: ask the user, apply a documented default, or refuse. Left unspecified, it becomes whatever the model does, which varies by client and by model version.
• An owner for after handoff. Upstream APIs change, credentials expire, protocol versions move; the server needs someone who notices.