What you will be able to do
- Choose between stdio and streamable HTTP based on where the server runs and who uses it
- Keep a stdio server's stdout clean of anything except protocol messages
- Explain how an HTTP MCP server authorizes individual users with OAuth bearer tokens
- Register a server in Claude Code at the right scope, and attach one to a Messages API request
1.stdio: a local subprocess talking over pipes
An MCP server reaches its client over one of two transports: stdio or streamable HTTP. Which one you pick decides where the server runs, who can reach it, and how it authenticates. With stdio, the client launches the server as a child process and exchanges newline-delimited JSON-RPC messages over the server's stdin and stdout. Because the client owns the process, it also ends it. On macOS and Linux, Claude Code sends SIGINT, then SIGTERM after 100 ms, then SIGKILL after another 400 ms.
stdio fits a server that only one person uses on their own machine and that needs no network access, such as a search tool over a private repository on a developer's laptop. A stdio server does not run OAuth. Its credentials come from the environment, which is why claude mcp add takes --env KEY=value.
# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverOn stdio, stdout is reserved for protocol messages. A bare print() in Python writes to stdout, so the client tries to parse the debug line as JSON-RPC, fails, and drops the connection. The fix is to send diagnostics to stderr or to a log file. Servers may write any UTF-8 logging to stderr, and the client must not assume stderr output means an error. The other fixes you might try don't work. A longer timeout leaves the same bad bytes on the pipe. A hand-made JSON-RPC envelope still doesn't answer any request the client sent. Resources are context for the model, not a side channel for diagnostics.
Checkpoint 1 of 7· Fill the gap
This command registers a local stdio server in Claude Code and gives it the API key it needs. stdio servers don't run OAuth. Which flag passes the credential?
# Real example: Add Airtable server
claude mcp add ? AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverA stdio server gets its credentials from the environment, not from an OAuth flow. So claude mcp add uses --env KEY=value to put the API key into the environment of the subprocess it launches.
Checkpoint 2 of 7· Exam question
After adding print() debugging lines to a Python MCP server that runs over stdio, Claude Code reports JSON parse errors and the server disconnects. The tools worked before the change. What is the right fix?
Correct answer: D — Send diagnostics to stderr or a log file so standard output carries nothing except the protocol's own JSON-RPC messages
- A. Incorrect: the failure is malformed data on the channel, not slowness, so a longer timeout just delays the same parse error.
- B. Incorrect: forging protocol envelopes for log text injects fake messages with unmatched ids and still pollutes the stream the client parses.
- C. Incorrect: a resource is a server feature fetched on request; it does nothing about stray text already written to standard output.
- D. Correct: with stdio, standard output is the protocol channel, so logs must go to stderr or a file to keep every line on stdout valid JSON-RPC.
2.Streamable HTTP: one endpoint, many clients
With streamable HTTP, the server is a network service. Each client message is an HTTP POST to a single MCP endpoint. The client's Accept header lists both application/json and text/event-stream, because a request can be answered with one JSON object or with an SSE stream. Notifications and responses that the server accepts get 202 Accepted with no body. HTTP is the right choice when many people need the same server, or when the platform team wants one central deployment it can update without touching anyone's laptop.
Being reachable over the network brings duties that a stdio pipe never has. Servers must validate the Origin header on every connection and reject a bad one with 403 Forbidden, which defends against DNS rebinding. A server meant only for local use should bind to 127.0.0.1, not 0.0.0.0. And every connection should be authenticated.
| Concern | stdio | Streamable HTTP |
|---|---|---|
| Where the server runs | Child process launched by the client | Remote or shared host behind an MCP endpoint |
| Message framing | Newline-delimited JSON-RPC on stdin/stdout | One JSON-RPC message per HTTP POST; reply as JSON or SSE |
| Credentials | Read from the environment | OAuth 2.1 bearer token in the Authorization header |
| Best fit | One user, one machine, no network | Many users, central deployment, per-user access |
Checkpoint 3 of 7· Check yourself
A platform team wants one MCP server for 40 engineers. They want to update it in one place, and each engineer should reach only what their own account allows. Which setup fits?
Many users and a central deployment call for streamable HTTP, and HTTP-based transports authenticate each connection with OAuth bearer tokens. That gives every engineer access scoped to their own account. stdio runs as a child process on one user's machine, and a shared key without per-connection auth gives up per-user access.
“Implementations using an HTTP-based transport SHOULD conform to this specification.”Source: modelcontextprotocol.io
Checkpoint 4 of 7· Exam question
A developer builds an MCP server that lets Claude Code search files in a private repository on their own laptop. Only that developer will use it, and no network access is required. Which transport fits best?
Correct answer: A — Configure stdio so Claude Code starts the server as a child process on the laptop, with messages sent over stdin and stdout pipes
- A. Correct: stdio is the transport for a single-user server on the same machine as the client. Claude Code spawns the process and exchanges messages over its standard streams, so no port, endpoint or authorization layer is needed.
- B. Incorrect: streamable HTTP with a public endpoint and OAuth is built for remote, multi-client servers. Here it adds a load balancer, internet exposure and an authorization server for a repository search tool that needs no network access.
- C. Incorrect: a shared internal host is meant for servers used by several people. Only one developer needs this server, and moving it off the laptop adds token management and puts the private repository's files on another machine.
- D. Incorrect: a standalone SSE transport has been superseded by streamable HTTP, and a cloud relay forces traffic out to the network and back just to reach a process that Claude Code could start directly on the laptop.
3.Authorizing HTTP servers with OAuth
Authorization in MCP is OAuth 2.1, and it applies to HTTP-based transports. An MCP server acts as an OAuth protected resource and must publish Protected Resource Metadata (RFC 9728). Clients use that metadata to find the authorization server. When a request arrives without a valid token, the server answers 401 Unauthorized with a WWW-Authenticate: Bearer header. That header points to the metadata document, and it can also name the scope the client needs, such as files:read.
After the user signs in, the client sends the token on every request as Authorization: Bearer <access-token>, never in the URL query string. Token requests include a resource parameter set to the server's canonical URI, such as https://mcp.example.com, so each token is bound to the server it was issued for. If a token lacks a permission, the server returns 403 with error="insufficient_scope" and the scope it requires. The client then re-authorizes with the union of its old and new scopes, so it doesn't lose what it was already granted.
Consider a ticketing server shared by 200 engineers, where access must be tied to each individual. Hosting it centrally over streamable HTTP and validating each engineer's OAuth bearer token on every request meets both requirements. The other designs each miss one. A single static API key shared by everyone cannot tell one engineer from another. A VPN restriction with source-address logging limits the network but authenticates nobody. A stdio server that each engineer runs locally gives the platform team no central deployment to update.
Checkpoint 5 of 7· Check yourself
A client has just finished the OAuth sign-in for an HTTP MCP server at https://mcp.example.com/mcp and is about to send its first request. How should it present the access token?
The client sends the bearer token in the Authorization header on every request. Tokens must never appear in the URI query string, where they end up in logs and proxies.
“Access tokens MUST NOT be included in the URI query string”Source: modelcontextprotocol.io
Checkpoint 6 of 7· Exam question
An internal ticketing MCP server must be reachable by 200 engineers from their own machines. The platform team wants one central deployment they can update, and access must be tied to each individual user. Which design fits?
Correct answer: B — Host it as a remote streamable HTTP server, with an OAuth bearer token validated on each request to identify the caller
- A. Incorrect: personal tokens would identify users, but a stdio server runs as a separate local copy on each machine. The platform team would have to get 200 engineers to update, so there is no single deployment to maintain.
- B. Correct: one remote streamable HTTP deployment is the single place the platform team updates, and validating an OAuth bearer token on each request lets the server identify and authorize each user separately.
- C. Incorrect: the deployment is central, but VPN membership and a logged source address do not establish which person is calling. Addresses can be shared or reassigned, so access is not tied to the individual user.
- D. Incorrect: the deployment is central, but one static key shared by the engineers is the same credential for the whole group. The server cannot tell callers apart, so access is not tied to individual users.
Sources3
4.Connecting a server to Claude Code and the Messages API
In Claude Code, claude mcp add registers a server, and the --scope flag decides where the entry is stored and who gets it. local is the default and stays private to you in the current project. user follows you into every project. project writes to .mcp.json in the repository root, so the whole team gets the server through version control. A teammate has to approve a project-scoped server before it runs; until then it shows as pending approval.
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}The type field is easy to drop, and dropping it breaks the entry. Claude Code reads an entry with no type as a stdio server, so a url entry without "type": "http" fails. Another common mistake is a token pasted with a trailing newline. Claude Code warns about the hidden whitespace in claude mcp list and /mcp, but it does not trim it. For remote servers, a static token goes in --header "Authorization: Bearer your-token". Claude Code stores OAuth sign-ins per endpoint.
Applications built directly on the Messages API can use the MCP connector instead of running an MCP client of their own. The request lists each server in mcp_servers with type: "url", its url, a name and an optional authorization_token. It then enables each server's tools with an mcp_toolset entry in tools that references the server by mcp_server_name. For an OAuth-protected server, the application obtains the access token itself and passes it in authorization_token.
Checkpoint 7 of 7· Check yourself
After a teammate approves a new project-scoped entry in .mcp.json, it still fails to connect. The entry is "docs": { "url": "https://docs.example.com/mcp" } and has no other fields. What is wrong?
Claude Code does not infer HTTP from a url. An entry with no type is treated as a stdio server, so a url-only entry fails until you add "type": "http", "sse" or "ws". Approval was already given, so a pending status is not the cause.
“Claude Code reads an entry with no type as a stdio server, so a url entry without a type fails.”Source: code.claude.com
Practise it for real
Register a remote MCP server in Claude Code, inspect it, and remove it.
1.Run
claude mcp add --transport http notion https://mcp.notion.com/mcp.Why: A remote server is added by URL with an explicit http transport. The entry gets the default local scope.
You should see: Claude Code confirms that the server named notion was added.
2.Run
claude mcp list, thenclaude mcp get notion.Why: These commands show every configured server with its status, and the details for one server, including warnings such as hidden whitespace.
You should see: notion appears with its URL and a connection or authentication status.
3.Start
claudeand type/mcp.Why: The /mcp panel shows server status inside a session and is where you complete the OAuth sign-in for a remote server.
You should see: notion is listed, and you are offered a sign-in if the server requires one.
4.Run
claude mcp remove notion.Why: This cleans up the test entry.
You should see: notion no longer appears in
claude mcp list.
Stuck? Get a nudge
If you add the server again with --scope project, look at the .mcp.json file that appears in the repository root.
Sources
(5)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“The client launches the MCP server as a subprocess.”
↩︎ stdio: a local subprocess talking over pipes“SHOULD NOT assume stderr output indicates error conditions”
↩︎ stdio: a local subprocess talking over pipes“Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks”
↩︎ Streamable HTTP: one endpoint, many clients“When running locally, servers SHOULD bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0)”
↩︎ Streamable HTTP: one endpoint, many clients“The server MAY write UTF-8 strings to its standard error (stderr) for any logging purposes”
↩︎ Exam trap 1“The server MUST NOT write anything to its stdout that is not a valid MCP message.”
↩︎ Prediction - 2.https://code.claude.com/docs/en/mcpOfficial docs
“Claude Code sends SIGINT, then SIGTERM if the process is still running 100 milliseconds later”
↩︎ stdio: a local subprocess talking over pipes“Project | Current project only | Yes, via version control | .mcp.json in project root”
↩︎ Connecting a server to Claude Code and the Messages API“Claude Code stores OAuth sign-ins per endpoint”
↩︎ Connecting a server to Claude Code and the Messages API“Claude Code reads an entry with no type as a stdio server, so a url entry without a type fails.”
↩︎ Exam trap 3“Claude Code reads an entry with no type as a stdio server, so a url entry without a type fails.”
↩︎ Checkpoint - 3.
“Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.”
↩︎ stdio: a local subprocess talking over pipes“MCP servers MUST implement OAuth 2.0 Protected Resource Metadata (RFC9728).”
↩︎ Authorizing HTTP servers with OAuth“Access tokens MUST NOT be included in the URI query string”
↩︎ Authorizing HTTP servers with OAuth“MUST identify the MCP server that the client intends to use the token with.”
↩︎ Authorizing HTTP servers with OAuth“Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.”
↩︎ Exam trap 2“Implementations using an HTTP-based transport SHOULD conform to this specification.”
↩︎ Checkpoint - 4.
“each message is an HTTP POST to a single MCP endpoint”
↩︎ Streamable HTTP: one endpoint, many clients - 5.
“You can connect to multiple MCP servers by including multiple server definitions in mcp_servers and a corresponding MCPToolset for each in the tools array”
↩︎ Connecting a server to Claude Code and the Messages API