Transports

A transport Transport The mechanism that carries MCP messages between a client and a server. It defines how messages are framed and delivered, not what they mean, so the same tools work over either transport. is how MCP messages get between a client and your server. MCP defines two: stdio stdio transport The client launches your server as a subprocess and they exchange newline-delimited messages over its standard input and output. Nothing listens on a port. and Streamable HTTP Streamable HTTP transport Each message is an HTTP POST to a single endpoint on your server. The reply is either a JSON object or a stream scoped to that request, which is what carries progress updates. . Tools, resources, and prompts behave the same way on both, and the code you write for them doesn't change.

stdio: a program the client launches

In the stdio transport, the client launches the MCP server as a subprocess Subprocess A program started and owned by another program, communicating over its standard input and output streams. A stdio MCP server runs as one, launched by the client. . The server reads JSON-RPC messages from stdin stdin Standard input: the stream a process receives data on. A stdio MCP server reads incoming protocol messages from it. and writes JSON-RPC messages to stdout stdout Standard output: a process's normal output stream. In a stdio MCP server this channel carries protocol messages only, so writing anything else to it corrupts the conversation. . Messages are delimited by newlines and must not contain embedded newlines.

Nothing listens on a port. You configure it by telling the client what command to run:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "src/stdio-server.ts"]
    }
  }
}

This is the right choice when your server works with local things: files on this machine, a local database, installed CLI tools. It's also the fastest way to develop, which is why this course starts there.

Streamable HTTP: a service clients connect to

With Streamable HTTP, your server exposes one endpoint and accepts POST requests to it. Each message is its own POST. The reply is either a plain JSON object, or a stream scoped to that request when the tool reports progress along the way.

{
  "servers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

This is the right choice when many people need to reach one shared instance, or when the server needs to live somewhere other than each user's laptop.

Picking one

The choice isn't permanent. You can serve the same tools over either transport, and moving from stdio to HTTP later changes the file that serves your server, not the tools themselves.

Registering a stdio server with your assistant

A stdio server is only useful once a client is configured to launch it. Every assistant reads its own configuration, so set up the one you're using before moving on.

If you're using GitHub Copilot, create .vscode/mcp.json in your workspace:

{
  "servers": {
    "demo-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "src/stdio-server.ts"]
    }
  }
}

If you're using Claude Code, run this in the terminal instead:

claude mcp add demo-server --transport stdio -- npx tsx src/stdio-server.ts

Both name a command that starts your server as a subprocess, which is exactly what "stdio" means. You don't have a server for it to launch yet, that's the next lesson, so it won't connect successfully. Do it anyway: the config will be sitting there once src/stdio-server.ts exists.

The one rule about standard output

A server must not write anything to its stdout that is not a valid MCP message. That stream carries the protocol, and console.log writes to it:

async ({ title }) => {
  console.log("adding task:", title);  // goes into the protocol stream
  tasks.push(title);
  return { content: [{ type: "text", text: `Added: ${title}` }] };
}

Read the raw stdout of a server doing that and the log text sits alongside the response:

adding task: Buy milk
{"result":{"content":[{"type":"text","text":"Added: Buy milk"}],...},"jsonrpc":"2.0","id":1}

In practice the call may still succeed, because the SDK client and MCP Inspector skip any line that doesn't parse as a JSON-RPC message. That tolerance is their own behavior, not something the protocol promises, so don't build on it.

For logging, use stderr stderr Standard error: a second output stream, separate from stdout. A server may write logs here for any purpose, which is why console.error is safe when console.log is not. instead, which a server may write to for any purpose:

console.error("adding task:", title);  // safe