Developer Quickstart

The Debriefer MCP server ships as an npm package. It exposes the full Debriefer API as a set of MCP tools and resources, over either stdio (for local AI assistants) or HTTP (for remote agents and hosted deployments).

Prerequisites

• Node.js 22 or newer
• A Debriefer API key (create one at app.debriefer.ai → Settings → API keys)

Install

npm install -g @debriefer/mcp-server

Or run without installing:

npx @debriefer/mcp-server --api-key=sk_live_...

Run it

Stdio (default). For AI assistants that spawn the server as a subprocess:

export DEBRIEFER_API_KEY=sk_live_...
debriefer-mcp

HTTP. For remote clients and agent workflows:

debriefer-mcp serve --port=8080

In HTTP mode, each client authenticates with its own API key in the Authorization header — the server doesn't take a key on startup.

See Transports for the full stdio vs. HTTP decision guide.

Authenticate

In HTTP mode, send:

Authorization: Bearer sk_live_...
Mcp-Session-Id: <from-initialize-response>

API keys are scoped to an organization. Each authenticated client gets an isolated session.

Make your first tool call

Initialize a session:

curl -sX POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $DEBRIEFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

The response includes an Mcp-Session-Id header. Use it for subsequent requests, then call a tool:

curl -sX POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $DEBRIEFER_API_KEY" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"scaffold_interview",
      "arguments":{
        "topic":"post-churn discovery",
        "question_count":5
      }
    }
  }'

You'll get back an agent ID, a blueprint ID, and a hosted URL.

Next steps

• Build an agent workflow: Let an agent run an interview
• Browse every tool: Tool reference
• Deploy the HTTP server: Transports