# How to Configure Context7 MCP Transport: stdio vs HTTP Setup Guide

> Configure Context7 MCP transport with stdio or HTTP. Learn to set up CLI or network communication efficiently using the --transport flag and specific options.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Configure Context7 MCP transport types by passing the `--transport` flag with either `stdio` (default) or `http`, along with transport-specific options like `--port` for HTTP mode.**

The Context7 MCP server from the `upstash/context7` repository supports two mutually exclusive transport protocols that determine how clients communicate with the server. Understanding how to configure these transport types is essential for both local development workflows and production deployments.

## Understanding Context7 MCP Transport Types

### stdio Transport (Default)

The **stdio** transport uses standard input/output streams for communication between the MCP client and server. When you run the Context7 MCP server without specifying a transport, it defaults to this mode.

This transport is ideal for local development environments where IDE plugins or CLI tools spawn the server process directly. The server remains alive for the duration of the session, reading requests from stdin and writing responses to stdout.

### HTTP Transport

The **HTTP** transport starts an Express server that exposes the MCP endpoint at `/mcp` (or `/mcp/oauth` for OAuth flows). Clients communicate via JSON-RPC over HTTP requests rather than process streams.

Use HTTP transport when you need a long-running, addressable service that multiple clients can share across a network. This mode is essential for Docker deployments, remote server setups, or scenarios where the client cannot spawn a child process.

## How Transport Configuration Works in Context7 MCP

The transport selection logic resides in [`packages/mcp/src/index.ts`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts), which uses the **commander** library to parse CLI arguments:

```typescript
// packages/mcp/src/index.ts
const program = new Command()
  .option("--transport <stdio|http>", "transport type", "stdio")
  .option("--port <number>", "port for HTTP transport", DEFAULT_PORT.toString())
  .option("--api-key <key>", "API key for authentication (or set CONTEXT7_API_KEY env var)")
  .parse(process.argv);

```

The parsed transport value determines which server implementation initializes:

```typescript
if (TRANSPORT_TYPE === "http") {
  // Initialize Express, CORS, and StreamableHTTPServerTransport
} else {
  // stdio mode – read API key from CLI/env and start StdioServerTransport
}

```

The entry point also enforces transport-specific validation rules. For example, the `--api-key` flag is prohibited in HTTP mode because authentication must occur via HTTP headers rather than CLI arguments.

## Configuring stdio Transport for Local Development

To run Context7 MCP with stdio transport (the default), install the package and start the server:

```bash

# Install globally or use npx

npm i -g @upstash/context7-mcp

# Start with stdio transport and API key

npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

```

The server outputs a confirmation message indicating it is "running on stdio" and awaits JSON-RPC messages via stdin.

For **VS Code** integration, configure the transport in your settings:

```json
{
  "mcp": {
    "servers": {
      "context7": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
      }
    }
  }
}

```

## Configuring HTTP Transport for Remote Deployment

To start Context7 MCP in HTTP mode, specify the transport and optionally the port:

```bash

# Start HTTP server on default port 3000

npx -y @upstash/context7-mcp --transport http

# Or specify a custom port

npx -y @upstash/context7-mcp --transport http --port 8080

```

The server initializes an Express application with CORS support and exposes the MCP endpoint at `http://localhost:PORT/mcp`.

For **Docker** deployments, create a Dockerfile:

```dockerfile
FROM node:18-alpine
WORKDIR /app
RUN npm i -g @upstash/context7-mcp
CMD ["context7-mcp", "--transport", "http", "--port", "3000"]

```

Build and run:

```bash
docker build -t context7-mcp .
docker run -p 3000:3000 context7-mcp

```

When configuring **Cursor** or other HTTP-compatible clients, provide the URL and authentication headers:

```json
{
  "mcpServers": {
    "context7": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

```

## Transport-Specific Authentication Differences

Authentication configuration varies significantly between transport modes:

**stdio transport** accepts the API key via:
- The `--api-key` CLI flag
- The `CONTEXT7_API_KEY` environment variable

**HTTP transport** requires authentication via HTTP headers:
- `Authorization: Bearer <token>`
- `Context7-API-Key: <key>`

The `extractApiKey` function in [`packages/mcp/src/index.ts`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts) (lines 1010-1018) handles header extraction for HTTP mode, while stdio mode validates credentials during initial transport setup.

## Summary

- **stdio transport** is the default mode for local development, using standard input/output streams and CLI-based authentication.
- **HTTP transport** starts an Express server for remote access, requiring the `--transport http` flag and header-based authentication.
- Configure transport selection via the `--transport` flag in [`packages/mcp/src/index.ts`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts), with `--port` available for HTTP customization.
- Use stdio for VS Code and local IDE integrations; use HTTP for Docker deployments, Cursor, and shared server scenarios.

## Frequently Asked Questions

### How do I switch from stdio to HTTP transport in Context7 MCP?

Pass the `--transport http` flag when starting the server. Unlike stdio mode, you cannot use the `--api-key` CLI argument in HTTP mode; instead, clients must send the API key via the `Authorization` or `Context7-API-Key` HTTP headers.

### Can I run Context7 MCP in HTTP mode without Docker?

Yes. Install the package globally or use npx, then start the server with `npx -y @upstash/context7-mcp --transport http --port 8080`. The server will listen on the specified port until terminated.

### Why does HTTP transport reject the --api-key flag?

The HTTP transport validates that no `--api-key` argument is provided because authentication in HTTP mode occurs per-request via headers. This security measure prevents accidental credential exposure in process lists while ensuring each client provides its own authentication context.

### Which transport should I use for VS Code integration?

Use **stdio transport** for VS Code. The editor spawns the MCP server as a child process and communicates over stdin/stdout. Configure it in your VS Code settings using `"type": "stdio"` with the npx command and API key arguments.