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

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, which uses the commander library to parse CLI arguments:

// 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:

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:

# 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:

{
  "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:

# 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:

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

Build and run:

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:

{
  "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 (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, 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.

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