How to Configure Docker Deployment for Different Transport Modes in deepwiki-mcp

The deepwiki-mcp Docker image uses a multi-stage build with a flexible CLI entrypoint that selects between stdio, HTTP, or SSE transports at runtime via --http, --sse, or default flags.

The regenrek/deepwiki-mcp repository provides a Model Context Protocol (MCP) server that supports multiple transport configurations for different deployment scenarios. Understanding how to configure Docker deployment for different transport modes allows you to optimize the server for local development, remote HTTP clients, or real-time streaming connections using the same container image.

Understanding the Transport Architecture

The application implements three distinct transport modes in src/server.ts, each suited for different operational contexts:

• Standard I/O (stdio): Default mode for local MCP client integration
• HTTP (REST): Full-duplex HTTP transport for remote API clients
• Server-Sent Events (SSE): Event-streaming transport for real-time browser connections

The transport selection occurs at runtime through CLI argument parsing in src/index.ts, not during the Docker build process. This design ensures a single Docker image serves all transport configurations.

Dockerfile Configuration for Transport Flexibility

The multi-stage Dockerfile builds the application and configures the container entrypoint without hardcoding transport-specific settings:

FROM node:22-alpine AS release
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/bin ./bin
COPY --from=builder /app/package.json ./package.json
ENTRYPOINT ["node", "bin/cli.mjs"]

The ENTRYPOINT directive launches bin/cli.mjs, which delegates to the argument parser in src/index.ts. Because the container accepts command-line arguments passed to docker run, you configure the transport mode at container startup rather than image build time.

Configuring Transport Modes at Runtime

The CLI argument definitions in src/index.ts expose transport selection flags:

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', default: '3000' },
  endpoint: { type: 'string', default: '/mcp' },
},

The mode selection logic determines which transport implementation to initialize:

const mode = args.http ? 'http' : args.sse ? 'sse' : 'stdio';

Standard I/O (stdio) Transport

When no flags are provided (or --stdio is explicitly set), src/server.ts instantiates StdioServerTransport:

if (options.type === 'stdio') {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

This mode suits local development and CLI-based MCP clients that communicate over standard streams.

HTTP (REST) Transport

Passing --http triggers the REST transport implementation in src/server.ts:

if (options.type === 'http') {
  const transport = new RestServerTransport({ 
    port: options.port, 
    endpoint: options.endpoint 
  });
  await server.connect(transport);
  await transport.startServer();
}

This configuration exposes the MCP server as a REST API, making it accessible to remote HTTP clients and microservices.

Server-Sent Events (SSE) Transport

The --sse flag activates the SSE transport in src/server.ts, which creates an H3 application with dedicated routes:

const app = createApp();
const port = options.port || 3000;

app.use('/sse', async (req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  await server.connect(transport);
});

app.use('/messages', async (req, res) => {
  // Handle incoming messages via SSE transport
});

createServer(app).listen(port);

This mode enables real-time, unidirectional streaming to browser clients and event-driven architectures.

Docker Run Examples for Each Transport

Build the image once, then select your transport mode at runtime:

# Build the multi-stage image

docker build -t deepwiki-mcp .

Standard I/O (Default)

# Run with stdio transport for local MCP client integration

docker run -i --rm deepwiki-mcp

HTTP Transport

# Expose HTTP API on port 3000 with custom endpoint

docker run -d -p 3000:3000 \
  deepwiki-mcp --http --port 3000 --endpoint /mcp

SSE Transport

# Enable Server-Sent Events on port 3000

docker run -d -p 3000:3000 \
  deepwiki-mcp --sse --port 3000

Summary

• The deepwiki-mcp Docker image uses a transport-agnostic multi-stage build with ENTRYPOINT ["node", "bin/cli.mjs"].
• Transport selection occurs at runtime via CLI flags parsed in src/index.ts, not during the Docker build.
• Three transport modes are supported: stdio (default), HTTP (REST), and SSE (Server-Sent Events), each implemented in src/server.ts.
• The same Docker image serves all transport configurations; simply pass --http, --sse, or no flag when running the container.

Frequently Asked Questions

How do I switch between transport modes in a running deepwiki-mcp container?

You cannot switch transport modes dynamically in a running container. The transport is initialized once at startup based on the CLI flags provided to docker run. To change transports, stop the current container and start a new one with the desired flag (--http, --sse, or no flag for stdio).

What is the default transport mode when running the deepwiki-mcp Docker image?

The default transport mode is Standard I/O (stdio). If you run the container without specifying --http or --sse, the application parses the absence of flags in src/index.ts and defaults to stdio mode, instantiating StdioServerTransport in src/server.ts.

Can I customize the port and endpoint for HTTP and SSE transports in Docker?

Yes. Both --http and --sse modes respect the --port and --endpoint CLI arguments defined in src/index.ts. For example, docker run deepwiki-mcp --http --port 8080 --endpoint /api exposes the HTTP transport on port 8080 at the /api path. The SSE transport uses the same port parameter but ignores the endpoint parameter, instead using fixed /sse and /messages routes as implemented in src/server.ts.

Does the multi-stage Dockerfile affect transport configuration options?

No. The multi-stage Dockerfile only builds the application and sets the ENTRYPOINT to bin/cli.mjs. It does not bake in any transport-specific configuration. This design ensures the resulting image is transport-agnostic, allowing you to configure stdio, HTTP, or SSE modes at runtime via command-line arguments passed to docker run.

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