@captain-sdk/captain-mcp

MCP server for Captain — multimodal RAG search and persistent project search. Works with Claude Code, Cursor, Windsurf, and any MCP-aware client.

What it does

Exposes 19 tools:

Core search & collection management (17):

• captain_search, captain_list_collections, captain_create_collection, captain_delete_collection
• captain_list_documents, captain_delete_document, captain_wipe_documents
• captain_job_status, captain_cancel_job
• captain_index_url, captain_index_youtube, captain_index_text, captain_index_file
• captain_index_s3, captain_index_gcs, captain_index_azure, captain_index_r2

captain_index_file uploads local paths (PDF, DOCX, XLSX, CSV, TXT, images, …) via multipart/form-data — max 20 files, 100MB each.

Live search (2):

• captain_save — save a short note (decision, gotcha, bug repro, design constraint) to a per-project collection with a timestamped, slugified filename. Auto-creates the collection on first use.
• captain_find — semantic search over saved notes, with timestamps surfaced so stale notes are obvious.

Storage syncs (10):

• captain_create_s3_sync, captain_create_r2_sync, captain_create_supabase_sync, captain_create_backblaze_sync — create a sync that keeps a collection continuously up to date with a cloud-storage bucket (initial backfill + scheduled/event/on-demand updates).
• captain_list_syncs, captain_get_sync, captain_update_sync, captain_delete_sync — manage existing syncs (scope, schedule, deletion policy, pause/resume; delete is a soft-delete that retains indexed docs).
• captain_reconcile_sync — run an on-demand diff-and-index now; returns counts of added/modified/removed.
• captain_subscribe_sync_webhook — mint a webhook secret + subscribe URL for near-real-time S3 event updates.

Integration wizard (1):

• captain_wizard — writes Captain into a codebase, using Captain's own agent docs (llms.txt) as the source of truth for the current API surface. On first use it asks the user's permission to send routine, de-identified feedback about the integration to Captain's public feedback endpoint (no key, no code, no personal data).

The hosted server (see below) also adds more indexing sources (Dropbox, Supabase, Backblaze, SharePoint, OneDrive, Google Drive), storage syncs, v3 search, and chunk-level tools — 46 tools total.

Credentials

Set these env vars in your shell (every client reads them the same way):

export CAPTAIN_API_KEY=cap_...
export CAPTAIN_ORGANIZATION_ID=019a...

Get an API key at runcaptain.com/studio.

Install — Claude Code

Add to ~/.claude/settings.json (user scope) or .claude/settings.json (project scope):

{
  "mcpServers": {
    "captain": {
      "command": "npx",
      "args": ["-y", "@captain-sdk/captain-mcp"],
      "env": {
        "CAPTAIN_API_KEY": "${CAPTAIN_API_KEY}",
        "CAPTAIN_ORGANIZATION_ID": "${CAPTAIN_ORGANIZATION_ID}"
      }
    }
  }
}

Restart Claude Code. /mcp shows captain connected.

Install — Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "captain": {
      "command": "npx",
      "args": ["-y", "@captain-sdk/captain-mcp"],
      "type": "stdio",
      "env": {
        "CAPTAIN_API_KEY": "${env:CAPTAIN_API_KEY}",
        "CAPTAIN_ORGANIZATION_ID": "${env:CAPTAIN_ORGANIZATION_ID}"
      }
    }
  }
}

Install — any other MCP client

{
  "mcpServers": {
    "captain": {
      "command": "npx",
      "args": ["-y", "@captain-sdk/captain-mcp"],
      "env": {
        "CAPTAIN_API_KEY": "cap_...",
        "CAPTAIN_ORGANIZATION_ID": "019a..."
      }
    }
  }
}

Usage

> Search runcaptain-docs for how the scientific/medical/ask streaming works
> Save this to runcaptain: We picked Lambda over CF Worker for PubMed — NCBI doesn't IP-rate-limit.
> What did we decide about PubMed proxying?
> Index https://docs.runcaptain.com/api-reference into runcaptain-docs

Optional: agent guidance

Drop a .cursor/rules/captain.mdc (Cursor) or CLAUDE.md snippet (Claude Code) in your repo to nudge the agent toward the Captain tools:

When searching docs or recalling past decisions, prefer captain_search, captain_save, and captain_find over grep/WebFetch. Use the repo basename as the search collection; captain_save auto-creates it.

Hosted (remote) server

Instead of running the stdio server locally, connect to the hosted Captain MCP over HTTP at https://mcp.runcaptain.com/mcp. Authenticate with your Captain API key as a bearer token — the key implies your organization, so no organization id is needed.

{
  "mcpServers": {
    "captain": {
      "url": "https://mcp.runcaptain.com/mcp",
      "headers": { "Authorization": "Bearer cap_..." }
    }
  }
}

Same tools as the stdio build, with two differences: the server stores no credentials (your key is used per-request and never persisted), and captain_index_file cannot read local paths — pass urls (which the server fetches) or inline base64 files instead.

Self-hosting: the server is a container (Dockerfile) serving the MCP at /mcp and a health check at /health on PORT (default 8080). Run npm run start:http locally, or deploy the image behind TLS.

Links

• Captain API docs
• npm package
• OpenClaw Captain plugin — equivalent tools for the OpenClaw runtime.

License

MIT.