MCP Transport Mechanisms

Kodik supports three transport mechanisms for communicating with MCP servers. The right choice depends on where the server runs and what protocol it speaks.

Transport	type value	Where the server runs	Best for
stdio	"stdio" (default when command is set)	Local process on your machine	Local tools, IDE extensions
SSE	"sse"	Remote HTTP server	Older hosted servers
Streamable HTTP	"http" or "streamableHttp"	Remote HTTP server	New hosted servers (recommended)

stdio transport

stdio launches a command on your machine as a child process. Kodik writes JSON-RPC messages to the process’s stdin and reads responses from its stdout. The process’s stderr is captured separately for error logging.

How it works

Kodik                         Server process
  |                                 |
  |--- JSON-RPC (stdin) ----------->|
  |                                 | (processes request)
  |<-- JSON-RPC (stdout) -----------|
  |                                 |

Characteristics

• Local only — the server binary must be installed on your machine
• Lowest latency — no network stack involved
• One-to-one — each Kodik instance gets its own server process
• Inherently secure — no network exposure

Config fields

{
  "servers": {
    "my-local-server": {
      // type: "stdio" is inferred when command is present
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": { "API_KEY": "..." },
      "cwd": "/optional/working/dir",
    },
  },
}

When to use stdio

• Tools that need direct access to your local file system or processes
• Servers installed via npm, pip, or uv
• Single-user scenarios
• Operations where latency matters

SSE transport

SSE (Server-Sent Events) connects to a remote HTTP server. Kodik opens a persistent GET connection on which the server pushes events, and sends requests to the server via HTTP POST on a separate endpoint. Kodik uses a reconnecting EventSource so transient network failures do not drop the stream.

How it works

Kodik                              Remote server
  |                                      |
  |--- HTTP GET /sse ------------------->| (establish stream)
  |<--- SSE event stream ----------------| (persistent)
  |                                      |
  |--- HTTP POST /message -------------->| (client request)
  |<--- SSE event with response ---------| (response)

Characteristics

• Remote — server runs anywhere on the network
• Multi-client — one server instance can serve many clients
• Auto-reconnect — Kodik reconnects automatically on network interruption
• Requires explicit type: "sse" — must be set to distinguish from streamable HTTP when a url field is present

Config fields

{
  "servers": {
    "my-sse-server": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": { "Authorization": "Bearer token" },
    },
  },
}

When to use SSE

• Servers that were built before streamable HTTP became standard
• Services that explicitly document an SSE endpoint

Streamable HTTP transport

Streamable HTTP is the modern MCP transport, introduced in the MCP spec as the successor to SSE. It uses a single HTTP endpoint that can stream responses. Use type: "http" (Kodik also accepts "streamableHttp" and normalizes both to the same internal implementation).

How it works

Kodik sends requests to the URL and receives streamed responses over the same connection. OAuth bearer tokens are attached automatically if authentication is configured.

Characteristics

• Remote — server runs anywhere on the network
• Modern — recommended for all new server implementations
• Simpler server-side implementation than SSE (one endpoint instead of two)
• OAuth-ready — integrates with Kodik’s OAuth 2.1 flow

Config fields

{
  "servers": {
    "my-http-server": {
      "type": "http", // "streamableHttp" also accepted
      "url": "https://example.com/mcp",
      "headers": { "X-Custom": "value" },
    },
  },
}

When to use streamable HTTP

• Any new server you are building or connecting to
• Services that document a single /mcp endpoint (rather than separate /sse and /message endpoints)
• Servers that require OAuth 2.1

Choosing a transport

Does the server run on your local machine?
  Yes → stdio

Does the server use two endpoints (/sse and /message)?
  Yes → sse

Otherwise → http (streamable HTTP)

For detailed configuration options that apply to all transport types (approval modes, tool filtering, OAuth), see Configuring MCP Servers.