HTTP, SSE, and stdio Transports in add-mcp Explained

A transport defines how an MCP client (your AI coding agent) communicates with an MCP server. add-mcp supports all three transport types defined by the MCP specification and writes the correct config format for each one into the target agent’s configuration file.

Transport overview

Transport	Flag	Description	When to use
HTTP	`--transport http`	Streamable HTTP — the current MCP standard	Default for any `http://` or `https://` URL
SSE	`--transport sse`	Server-Sent Events — an older MCP transport	Older remote servers that don’t support streamable HTTP
stdio	(automatic)	Local process communicating via stdin/stdout	npm packages and shell commands

HTTP (streamable HTTP)

Streamable HTTP is the default transport for remote servers. When your source starts with http:// or https://, add-mcp automatically configures the server entry with "type": "http" (or the equivalent field for the target agent). You do not need to pass any flag:

# HTTP transport is inferred automatically
npx add-mcp https://mcp.context7.com/mcp

# Explicit flag — identical result
npx add-mcp https://mcp.context7.com/mcp --transport http

Most modern agents — including Cursor, Claude Code, Codex, Gemini CLI, VS Code, and OpenCode — support streamable HTTP.

SSE (Server-Sent Events)

SSE is an older MCP transport that some servers still use. It is deprecated by the MCP specification but remains widely supported across agents. Pass --transport sse (or --type sse) to use it:

# Install a remote server using SSE transport
npx add-mcp https://mcp.example.com/sse --transport sse

The --transport and --type options are aliases — they behave identically. Use whichever feels more natural in your workflow.

stdio

stdio is used for local MCP servers: npm packages and shell commands that run as child processes. add-mcp detects these automatically based on the source format — no flag is needed:

# npm package — stdio is inferred
npx add-mcp @modelcontextprotocol/server-postgres

# Shell command — stdio is inferred
npx add-mcp "node /path/to/server.js --port 3000"

# Full npx invocation — stdio is inferred
npx add-mcp "npx -y @org/mcp-server --flag value"

When the source is a package or command, add-mcp generates a config entry with command, args, and optionally env fields — the standard stdio shape expected by all agents.

How add-mcp infers source type

add-mcp inspects the raw input string to decide which source type (and therefore which transport) applies:

Remote (HTTP/SSE)
npm package (stdio)
Command (stdio)

Any input starting with http:// or https:// is treated as a remote server. The transport defaults to http; pass --transport sse to override.

npx add-mcp https://mcp.neon.tech/mcp
# → type: "remote", transport: http

Inputs that look like npm package names — scoped (@scope/pkg) or plain (package-name) — are treated as packages and run via npx -y.

npx add-mcp @modelcontextprotocol/server-filesystem
# → type: "package", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"]

Any input containing a space, starting with a known runner (npx, node, python), or looking like a filesystem path is treated as a raw command.

Space-separated commands (including runner-prefixed ones like node …) are split: the first token becomes command and the rest become args.
Path-like inputs (/absolute/path, ~/home/path, ./relative/path, Windows C:\…) are kept as a single atomic command value with an empty args list — spaces inside the path are never treated as argument separators. Use --args to pass arguments to a path-based binary.

npx add-mcp "node /path/to/server.js --port 3000"
# → type: "command", command: "node", args: ["/path/to/server.js", "--port", "3000"]

npx add-mcp "/Applications/My MCP Server/bin/server"
# → type: "command", command: "/Applications/My MCP Server/bin/server", args: []

Agent transport compatibility

All agents except Claude Desktop support all three transport types. Claude Desktop is stdio only — it can only run local MCP servers through its config file. If you attempt to install a remote server (HTTP or SSE) to Claude Desktop, add-mcp will show an error and direct you to use the in-app Settings → Connectors interface instead.

Claude Desktop does not support HTTP or SSE transports via its config file. To connect Claude Desktop to a remote MCP server, use the Connectors section in the application’s settings.

Adding headers and environment variables

For remote servers you can attach authentication headers with --header:

npx add-mcp https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"

For stdio servers you can pass environment variables with --env and extra arguments with --args:

npx add-mcp @modelcontextprotocol/server-postgres \
  --env "DATABASE_URL=postgres://localhost/mydb" \
  --env "API_KEY=secret"

Both flags are repeatable and can be combined in the same command.

Get Started

Commands

Concepts

Registries

Guides

HTTP, SSE, and stdio Transports in add-mcp Explained

Transport overview

HTTP (streamable HTTP)

SSE (Server-Sent Events)

stdio

How add-mcp infers source type

Agent transport compatibility

Adding headers and environment variables

Build docs developers (and LLMs) love

Get Started

Commands

Concepts

Registries

Guides

Documentation Index

​Transport overview

​HTTP (streamable HTTP)

​SSE (Server-Sent Events)

​stdio

​How add-mcp infers source type

​Agent transport compatibility

​Adding headers and environment variables

Build docs developers (and LLMs) love

Transport overview

HTTP (streamable HTTP)

SSE (Server-Sent Events)

stdio

How add-mcp infers source type

Agent transport compatibility

Adding headers and environment variables