When to Use stdio Transport vs HTTP Transport for the Context7 MCP Server

Use stdio transport for local integrations where the client spawns the server process directly, and HTTP transport for remote deployments, containerized environments, or when you need OAuth authentication and multi-client support.

The Context7 MCP server from the upstash/context7 repository supports two transport modes that determine how clients communicate with the server. Choosing between stdio and HTTP transport depends on your deployment architecture, authentication requirements, and whether the server runs locally or remotely.

Understanding MCP Transport Modes

The Model Context Protocol (MCP) defines how tools and resources are exposed to AI clients. The transport layer determines the physical connection between the client and the Context7 server:

• stdio transport: Uses standard input/output pipes (stdin/stdout) for direct process-to-process communication
• HTTP transport: Uses standard HTTP(S) request-response cycles over TCP ports

According to the source code in packages/mcp/src/index.ts, the transport mode is selected via the --transport CLI flag, with stdio being the default when no flag is provided.

stdio vs HTTP Transport: Key Differences

Feature	stdio (default)	HTTP
Connection type	Direct pipe between processes; no network stack	HTTP(S) over TCP port
Typical use case	Local integrations (Cursor, Claude, VS Code extensions)	Remote deployments (Docker, Kubernetes, cloud VMs)
Port configuration	Not applicable; --port flag is rejected with error	Configurable via --port (default: 3000)
Authentication	API key only	API key or OAuth (via /mcp/oauth endpoint)
Multi-client support	One client per process	Concurrent connections from multiple clients
Network requirements	Works offline; no firewall configuration	Requires firewall/proxy configuration; respects HTTPS_PROXY

The port validation logic in packages/mcp/src/index.ts explicitly rejects the --port flag when using stdio transport: "The --port flag is not allowed when using --transport stdio." (lines 56-58). For HTTP transport, the default port is 3000 (lines 61-65).

Decision Guide: Choosing the Right Transport

Follow this decision tree to select the appropriate transport mode for your deployment:

1. Is the MCP server running on the same machine as the client?

   • Yes → Use stdio. It provides the lowest latency and requires no network configuration.
   • No → Proceed to question 2.

2. Do you need to expose the server to multiple clients or run it in a container?

   • Yes → Use HTTP. It supports concurrent connections and works with Docker, Kubernetes, and load balancers.
   • No → Proceed to question 3.

3. Do you require OAuth authentication (e.g., single sign-on)?

   • Yes → Use HTTP. The stdio transport does not support OAuth; only HTTP provides the /mcp/oauth endpoint with WWW-Authenticate headers (as implemented in packages/mcp/src/index.ts lines 30-34).
   • No → Use stdio for simplicity.

4. Does your environment require running behind a corporate proxy?

   • Yes → Use HTTP. The server respects HTTPS_PROXY and https_proxy environment variables (documented in packages/mcp/README.md lines 42-44).

When none of the above conditions apply, stay with the default stdio transport for optimal performance and minimal configuration.

Implementation Examples

Running with stdio Transport

Use this mode when integrating with local editors like Cursor or Claude Desktop:

# Pass API key via command line

bun run dist/index.js --transport stdio --api-key YOUR_API_KEY

# Or use environment variable

export CONTEXT7_API_KEY=YOUR_API_KEY
bun run dist/index.js --transport stdio

The server outputs "running on stdio" and communicates exclusively through stdin and stdout (see packages/mcp/src/index.ts lines 84-85).

Running with HTTP Transport

Deploy this mode for remote services or containerized environments:

# Use default port 3000

bun run dist/index.js --transport http

# Specify custom port

bun run dist/index.js --transport http --port 8080

The server initializes an Express HTTP listener and prints the accessible URL (lines 70-75 in packages/mcp/src/index.ts).

HTTP Client Example

When connecting to a remote HTTP transport, use standard HTTP requests:

curl -X POST https://mcp.context7.com/mcp \
  -H "Content-Type: application/json" \
  -H "Context7-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"resolve-library-id","params":{"query":"react","libraryName":"react"},"id":1}'

stdio Client Example

For local integrations, the client spawns the process and connects via the SDK:

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);

This corresponds to the else branch in the main() function where StdioServerTransport is instantiated (lines 79-84 in packages/mcp/src/index.ts).

Key Source Files and Implementation Details

File	Purpose
packages/mcp/src/index.ts	Contains CLI argument parsing, transport selection logic, and server initialization. Lines 56-58 validate port usage for stdio; lines 61-65 set the HTTP default port; lines 79-84 instantiate StdioServerTransport; lines 30-34 configure OAuth for HTTP.
packages/mcp/README.md	Documents CLI flags, environment variables (HTTPS_PROXY), and usage examples for both transport modes (lines 72-81).
README.md (project root)	Notes that OAuth is unavailable with stdio transport (line 169).
server.json	Example configuration showing type: "stdio" for local editor integrations.

These files provide the authoritative implementation details for transport behavior in the upstash/context7 repository.

Summary

• Choose stdio transport for local, single-client integrations where the MCP server runs on the same machine as the client (e.g., Cursor, Claude Desktop, VS Code extensions). It offers the lowest latency and requires no network configuration.

• Choose HTTP transport for remote deployments, containerized environments, or when you need to support multiple concurrent clients. It enables OAuth authentication, configurable ports, and proxy support.

• stdio limitations: No port configuration, no OAuth support, and one client per process.

• HTTP advantages: Supports OAuth endpoints (/mcp/oauth), respects HTTPS_PROXY environment variables, and allows load-balanced deployments.

Frequently Asked Questions

Can I use OAuth authentication with stdio transport?

No. The stdio transport only supports API key authentication passed via the --api-key flag or CONTEXT7_API_KEY environment variable. OAuth is only available with HTTP transport through the /mcp/oauth endpoint, which emits the required WWW-Authenticate headers for OAuth discovery as implemented in packages/mcp/src/index.ts.

Why does the server reject my --port flag when using stdio transport?

The stdio transport uses direct process pipes (stdin/stdout) rather than network sockets, so port configuration is meaningless. The CLI explicitly validates this in packages/mcp/src/index.ts (lines 56-58) and throws the error: "The --port flag is not allowed when using --transport stdio."

How do I run the Context7 MCP server behind a corporate proxy?

Use HTTP transport and set the HTTPS_PROXY or https_proxy environment variable. The HTTP server respects these proxy settings (documented in packages/mcp/README.md lines 42-44). stdio transport does not support proxy configurations because it operates without network stack involvement.

Can multiple clients connect to a single stdio transport instance?

No. Each stdio transport instance supports exactly one client connection because it operates through direct process pipes. If you need to serve multiple concurrent clients, deploy using HTTP transport, which supports concurrent connections and can be load-balanced across multiple server instances.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}