Transports
Stdio vs. HTTP, session lifecycle, and authentication for the Debriefer MCP server.
The MCP server supports two transports: stdio for local AI assistants that spawn the server as a subprocess, and HTTP for remote clients and hosted deployments. Pick one — you don't need both.
Pick a transport
| You want to... | Use |
|---|---|
| Connect Claude Desktop, Cursor, Windsurf, or Zed locally | Stdio |
| Expose Debriefer to ChatGPT via the Connectors surface | HTTP |
| Run Debriefer from an autonomous agent in production | HTTP |
| Host the server once and serve many per-user sessions | HTTP |
Stdio
The server reads JSON-RPC from stdin and writes it to stdout. The client (an AI assistant) spawns the server as a subprocess and manages its lifecycle.
Authentication: the server reads DEBRIEFER_API_KEY from the environment at startup. One process = one key = one organization.
Start it:
export DEBRIEFER_API_KEY=sk_live_...
debriefer-mcpOr pass the key inline:
debriefer-mcp stdio --api-key=sk_live_...HTTP
The server runs as a long-lived HTTP service. Each client authenticates per-request with its own API key — the server does not take a key on startup.
Start it:
debriefer-mcp serve --port=8080 --host=0.0.0.0Endpoints
| Path | Methods | Description |
|---|---|---|
/mcp | GET, POST, DELETE | MCP Streamable HTTP transport |
/health | GET | Health check; returns {"status":"ok"} |
Session lifecycle
- Client sends
POST /mcpwithAuthorization: Bearer <api_key>and a JSON-RPCinitializerequest. - Server responds with an
Mcp-Session-Idheader. - Client includes
Mcp-Session-Idon every subsequent request. - Idle sessions expire after the timeout (default 30 minutes).
- Client can close a session explicitly with
DELETE /mcp.
Flags
| Flag | Default | Description |
|---|---|---|
--port=<port> | 8080 | Listen port |
--host=<host> | 0.0.0.0 | Listen host |
--api-url=<url> | http://localhost:3000 | Debriefer API base URL |
--session-timeout=<secs> | 1800 | Session idle timeout |
Authentication
API keys are scoped to an organization. In HTTP mode, the server creates a per-session Debriefer API client using the key from each request's Authorization header — sessions are isolated by key.
Rotate a key by creating a new one in the dashboard and updating the client's config. Old sessions continue until they expire or are explicitly closed.
Deployment
Run the HTTP server behind any reverse proxy that supports streaming (nginx, Caddy, AWS ALB, Cloudflare). Two things to configure:
- Streaming: MCP's Streamable HTTP transport uses chunked responses. Disable response buffering at the proxy.
- Timeouts: Set the proxy's read timeout higher than
--session-timeoutso idle sessions close at the server, not the proxy.
Point /health at your load balancer's healthcheck.
For a full agent-to-MCP example, see Let an agent run an interview.