Skip to content

MCP Server Tooling

Context

Turbot's internal runbook is designed to be "Built by LLM, for LLM." The MCP (Model Context Protocol) server makes this concrete: it exposes the runbook's markdown content as queryable tools so that LLM clients (Claude Code, Cursor, and any MCP-compatible tool) can retrieve runbook knowledge directly during a session — without a human having to find and paste the relevant page.

Without the MCP server, the runbook is passive documentation: useful only when someone remembers to look at it. With the MCP server, it becomes ambient context: LLM tools can pull in the right runbook page automatically when working on infrastructure, handling an incident, or onboarding.

Current State

The MCP server is implemented as a Python serverless function deployed alongside the runbook site on Vercel.

Property Value
Endpoint https://runbook.turbot.com/api/mcp
Runtime Python 3.9 (Vercel serverless)
Source api/mcp.py in the turbot/runbook GitHub repo
Auth Bearer token via RUNBOOK_API_KEY environment variable
Protocol MCP 2024-11-05 over HTTP (JSON-RPC 2.0)

Available Tools

Tool Description
search_runbook Keyword search across all docs — returns title, path, and excerpt
get_page Returns full markdown content of a page given its path
list_pages Lists every page in the runbook with path and title

Decisions & Rationale

Why MCP over a standard REST API? MCP is the native protocol for LLM tool use. An MCP server registers directly in Claude Code, Cursor, and other LLM clients as a named tool set. A generic REST API would require custom integration per client. MCP is becoming the standard for LLM-accessible services, so building to it now avoids migration later.

Why a Vercel serverless function rather than a separate service? The runbook is already deployed on Vercel. Adding an api/ route costs nothing extra, requires no new infrastructure, and deploys automatically with every push to main. A separate service (EC2, ECS, Lambda) would add operational overhead for a low-traffic internal tool.

Why keyword search rather than vector/semantic search? The runbook pages follow a strict schema and use consistent terminology. Keyword search is fast, requires no external dependencies (no vector DB, no embeddings API), and works well for structured internal docs. Semantic search can be added later if the corpus grows large enough to need it.

**Why bundle docs/** into the function rather than reading from S3 or similar?** Simplicity. The markdown files are small, already in the repo, and change only on deploy. Bundling them avoids an external read dependency and cold-start latency from a remote store.

Configuring the MCP Server in Claude Code

Each team member adds the following to their Claude Code settings file at ~/.claude/settings.json:

{
  "mcpServers": {
    "runbook": {
      "type": "http",
      "url": "https://runbook.turbot.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with the shared key from 1Password (see Access & Ownership below).

To verify the connection is working:

curl https://runbook.turbot.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY"
# Should return: {"status":"ok","server":"runbook-mcp","pages":N}

Using the MCP Server in a Session

Once configured, the tools are available in any Claude Code session. You can call them explicitly or Claude will use them automatically when relevant.

Search for a topic:

"Search the runbook for how we handle AWS SSO credentials"

Fetch a specific page:

"Get the runbook page for identity-access/cloud/aws-sso.md"

During infrastructure work: Claude Code will automatically call search_runbook when it detects you are working on infrastructure that is likely documented — e.g. editing Terraform for an AWS account it has seen referenced in the runbook.

During incident response:

"Check the runbook ops log for anything related to EventBridge and CloudTrail"

Setting Up the Vercel Environment Variable

The RUNBOOK_API_KEY environment variable must be set in the Vercel project for auth to be enforced. Without it, the endpoint is open (development mode only — do not leave unset in production).

  1. Go to the Vercel project dashboard → Settings → Environment Variables
  2. Add RUNBOOK_API_KEY with a strong random value
  3. Set scope to Production and Preview
  4. Redeploy for the variable to take effect

To generate a suitable key:

openssl rand -hex 32

Access & Ownership

What Who / Where
RUNBOOK_API_KEY value Stored in 1Password under "Turbot Internal Tools"
Vercel project access Turbot Vercel team — ask Venu for access
Source code api/mcp.py in github.com/turbot/runbook
Owner Venu

Last Updated

2026-04-04 — Venu