How to Configure Deepwiki-MCP Transport Modes: stdio, HTTP, and SSE

Use the --http, --sse, or --stdio flags when launching the CLI to switch between transport modes, or call startServer() programmatically with the type option set to 'http', 'sse', or 'stdio'.

The regenrek/deepwiki-mcp repository implements a Model Context Protocol (MCP) server that supports multiple transport mechanisms. When you configure deepwiki-mcp transport modes, you determine how the server communicates with clients—whether through standard streams, HTTP requests, or persistent Server-Sent Events connections. This guide explains the implementation details found in the source code and provides practical configuration examples for each mode.

Understanding Deepwiki-MCP Transport Modes

Deepwiki-MCP supports three distinct transport mechanisms, each implemented in src/server.ts using classes from the Model-Context-Protocol SDK:

• stdio: The server runs as a child process and communicates over standard input/output streams. This is the default mode when no flags are provided.
• HTTP: An h3-based HTTP server handles requests at a configurable endpoint (default /mcp). This mode exposes the MCP API as a REST-like service.
• SSE: The server upgrades connections to Server-Sent Events at /sse and maintains a separate /messages endpoint for bidirectional communication, enabling long-running streaming interactions.

CLI Configuration: Selecting Transport Modes

The CLI entry point in src/index.ts defines three boolean flags that control transport selection. The argument parsing logic at lines 16-25 establishes the following precedence:

args: {
  http: { type: 'boolean', description: 'Run with HTTP transport' },
  sse:  { type: 'boolean', description: 'Run with SSE transport' },
  stdio:{ type: 'boolean', description: 'Run with stdio transport (default)' },
  port: { type: 'string', description: 'Port for http/sse (default 3000)', default: '3000' },
  endpoint: { type: 'string', description: 'HTTP endpoint (default /mcp)', default: '/mcp' },
},
...
const mode = args.http ? 'http' : args.sse ? 'sse' : 'stdio'

Flag precedence: --http takes priority over --sse, which takes priority over --stdio. If no flags are provided, the server defaults to stdio mode.

Transport Mode Examples

stdio (Default)

Run the server in stdio mode for local development or CLI integration:

# Default invocation requires no flags

npx mcp-deepwiki

# Or explicitly specify stdio

npx mcp-deepwiki --stdio

The executable script bin/cli.mjs loads the compiled entry point and initiates the stdio transport when no other flags are present.

HTTP

Expose the MCP API as an HTTP service for containerized or networked deployments:

# Start HTTP server on default port 3000 and endpoint /mcp

npx mcp-deepwiki --http

# Custom configuration

npx mcp-deepwiki --http --port 8080 --endpoint /api/mcp

In src/server.ts, the HTTP transport instantiates RestServerTransport from the MCP SDK and starts an h3-based server. You can then POST requests to the configured endpoint:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "id":"req-1",
        "action":"deepwiki_fetch",
        "params":{"url":"https://deepwiki.com/user/repo","mode":"aggregate"}
      }'

SSE

Enable Server-Sent Events for persistent, streaming connections:

# Start SSE server on default port 3000

npx mcp-deepwiki --sse

The SSE implementation in src/server.ts creates an h3 application with two routes:

• /sse — Upgrades the connection to Server-Sent Events
• /messages — Handles incoming messages for the established session

This mode uses SSEServerTransport from the MCP SDK and maintains persistent connections suitable for real-time UI updates or long-running operations.

Programmatic Configuration

You can configure deepwiki-mcp transport modes programmatically without using the CLI. The src/server.ts file exports startServer, which accepts a type option:

import { createServer, startServer } from 'deepwiki-mcp/src/server'

// Create the bare MCP instance
const mcp = createServer({ name: 'my-app', version: '1.0.0' })

// Start with HTTP transport
await startServer(mcp, { type: 'http', port: 4000, endpoint: '/mcp' })

// Or use SSE
// await startServer(mcp, { type: 'sse', port: 4000 })

// Or use stdio
// await startServer(mcp, { type: 'stdio' })

The startServer function switches on options.type and instantiates the appropriate transport class (StdioServerTransport, RestServerTransport, or SSEServerTransport) from the Model-Context-Protocol SDK.

Summary

• stdio is the default transport mode, activated when no flags are provided or when using --stdio.
• HTTP transport requires the --http flag and exposes the API at a configurable endpoint (default /mcp) using an h3-based server.
• SSE transport requires the --sse flag and establishes persistent connections via /sse and /messages endpoints.
• Transport selection logic resides in src/index.ts, while the transport implementations live in src/server.ts.
• You can configure transports programmatically using the startServer function with the type option set to 'stdio', 'http', or 'sse'.

Frequently Asked Questions

What is the default transport mode for deepwiki-mcp?

The default transport mode is stdio (standard input/output). If you launch the server without providing the --http or --sse flags, it automatically runs in stdio mode, making it suitable for local CLI usage and integration with other terminal-based tools.

How do I change the port when using HTTP or SSE transport?

Use the --port flag followed by your desired port number when starting the server. For example, npx mcp-deepwiki --http --port 8080 starts the HTTP server on port 8080 instead of the default 3000. This flag works identically for both HTTP and SSE modes.

Can I use deepwiki-mcp programmatically without the CLI?

Yes, you can import the createServer and startServer functions from deepwiki-mcp/src/server directly into your Node.js application. The startServer function accepts a type option where you specify 'stdio', 'http', or 'sse', along with other configuration options like port and endpoint.

What is the difference between HTTP and SSE transport modes?

HTTP transport uses a standard request-response model where clients POST requests to a specific endpoint (default /mcp) and receive immediate responses, suitable for stateless API calls. SSE transport establishes a persistent Server-Sent Events connection at /sse for streaming data from server to client, while using a separate /messages endpoint for client-to-server communication, making it ideal for real-time, long-running interactions.

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