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

> Learn when to use stdio transport vs HTTP transport for the Context7 MCP server. Choose stdio for local setups and HTTP for remote deployments, containers, or OAuth needs.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: best-practices
- Published: 2026-02-19

---

**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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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:

```bash

# 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`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts) lines 84-85).

### Running with HTTP Transport

Deploy this mode for remote services or containerized environments:

```bash

# 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`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)).

### HTTP Client Example

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

```bash
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:

```typescript
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`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)).

## Key Source Files and Implementation Details

| File | Purpose |
|------|---------|
| [`packages/mcp/src/index.ts`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/packages/mcp/README.md) | Documents CLI flags, environment variables (`HTTPS_PROXY`), and usage examples for both transport modes (lines 72-81). |
| [`README.md`](https://github.com/upstash/context7/blob/main/README.md) (project root) | Notes that OAuth is unavailable with stdio transport (line 169). |
| [`server.json`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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.