> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true # MCP Server > Connect Captain to Claude Code, Codex, Cursor, GitHub Copilot, Devin, or any MCP client. Search your indexed files and save project notes without leaving your editor. ## Agent Quick Reference: Captain MCP server * Hosted server (recommended): remote HTTP at `https://mcp.captain.dev/mcp`, nothing to install. 70 tools. * Authentication: add the URL with no headers. The client opens a browser, the user signs in to Captain and, on the approval page, picks the organization and the scope: which environments (development, staging, production) and whether the connection can write. No key to paste. * Every tool takes an optional `environment` argument (`development`, `staging`, `production`) within the approved scope; without it, development when approved, otherwise the first approved environment. To change the organization or scope, reauthenticate. * The local stdio build (`npx -y @captain-sdk/captain-mcp`) is deprecated. New tools and fixes ship only to the hosted server. Existing installs keep working and will fall behind. * Tools: `captain_search` / `captain_search_v3` (v3 takes `max_chunks_per_document` for document-level diversity), `captain_list_collections`, document tools (`captain_list_documents` with `metadata_filter`, `captain_get_document`, `captain_get_document_page`, `captain_create_asset_urls`, `captain_set_document_metadata` / `captain_update_document_metadata`), `captain_index_*` (url, youtube, text, file, s3, gcs, azure, r2, dropbox, supabase, backblaze, sharepoint, onedrive, gdrive; all accept `custom_metadata`, `mask_pii`, `max_files`, `skip_existing`, `overwrite_existing`, `transcription_language`, `parsing_script` where the endpoint does; R2 takes `jurisdiction` incl. `us`; YouTube takes `mode` transcript/audio/video), jobs (`captain_list_jobs`, `captain_job_status` with credits billed and per-file results, `captain_cancel_job`, `captain_rollback_job`, `captain_get_pii_report`, `captain_delete_pii_report`, `captain_validate_parsing_script`), sync tools (`captain_create_s3_sync` / `_r2_sync` / `_supabase_sync` / `_backblaze_sync` / `_azure_sync` / `_gcs_sync`, `captain_validate_sync`, `captain_list_syncs`, `captain_get_sync`, `captain_update_sync`, `captain_delete_sync`, `captain_reconcile_sync`, `captain_subscribe_sync_webhook`), chunk tools (`captain_list_chunks`, `captain_get_chunk`, `captain_*_chunk_metadata`, `captain_*_chunk_relation`), batch writes (`captain_batch_document_metadata`, `captain_batch_chunk_metadata`, `captain_batch_chunk_relations`: up to 100 items per request, one result per item), `captain_save`, `captain_find`, `captain_wizard`, `captain_copy_collection`, `captain_change_environment`, query history (`captain_list_queries`, `captain_get_query`: the org's stored queries, scoped to the key's environment, with opt-in exact request/response bodies and normalised results; `captain_get_query` accepts a `query_id` or the `request_id` a query response returns), evaluation (`captain_eval` scores a client-side question set as a paired test; `captain_create_eval_upload` / `captain_run_eval` / `captain_get_eval_results` hand a case set of up to 10,000 questions to Captain as a job under 1 to 8 named v3 configurations and read back scorecards, per-case hits and stored answers, API-key connections only). * Hosted `captain_index_file` cannot read local paths. Pass `urls` or inline base64 `files`. The deprecated stdio build also accepts local `paths`. * For OpenClaw and Hermes, see [OpenClaw & Hermes](/guides/integrations/openclaw-hermes). Connect to the hosted server at `https://mcp.captain.dev/mcp`: nothing to install, nothing to keep updated. ## Connect Pick your coding agent below and add the server to it. The first time the agent connects, it opens a browser window where you sign in to Captain. On the approval page you choose which organization the connection belongs to and what it is allowed to reach: the environments it can use (development, staging, and production) and whether it is allowed to write. Once you approve, the agent is connected and ready to use. Every tool accepts an optional `environment` argument, so a single connection can work across all of the environments you approved without reconnecting. If you want to change the organization or the scope later, simply reauthenticate. ## Try it Once the server is connected, talk to your agent normally: ``` > List my collections in production > Search finance-docs for the Q3 revenue figures > Index https://example.com/reports/q4.pdf into finance-docs and tell me when the job finishes > Which documents in finance-docs failed to index? > Read page 3 of the Q4 report > Save this to project-notes: chose Lambda over a Worker because NCBI does not rate-limit by IP > What did we decide about PubMed proxying? ``` ## What you get 70 tools, grouped below by what they do. Every tool name is clickable in most MCP clients' tool pickers; this table is the same information laid out for scanning. ### Search and collections | Tool | What it does | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `captain_search` | Deterministic File Search over a collection. | | `captain_search_v3` | Multimodal search with metadata filters, boosts, regions, relations, and `max_chunks_per_document` for one-chunk-per-document results. | | `captain_list_collections` | List collections in the organization. | | `captain_create_collection` | Create a collection. | | `captain_delete_collection` | Delete a collection. | | `captain_copy_collection` | Clone a collection with its vectors branched server-side; returns immediately no matter how large the collection is. | | `captain_list_documents` | List documents in a collection, with indexing status; filter by custom metadata. | | `captain_get_document` | Read one document: metadata, every chunk with page or timestamp, optional layout regions. | | `captain_get_document_page` | Read one page of a parsed document in reading order. | | `captain_create_asset_urls` | Mint short-lived viewable URLs for figure regions. | | `captain_set_document_metadata` | Replace a document's custom metadata. | | `captain_update_document_metadata` | Merge keys into a document's custom metadata. | | `captain_batch_document_metadata` | Merge or replace custom metadata on up to 100 documents in one request, with a result per item. | | `captain_delete_document` | Delete a single document. | | `captain_wipe_documents` | Delete every document in a collection. | ### Indexing | Tool | Source | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `captain_index_url` | A web URL | | `captain_index_youtube` | A YouTube video: its captions by default (timestamped transcript), or with `mode` the audio or the full video; `on_missing_transcript` picks the fallback when there are no captions | | `captain_index_text` | Inline plain text | | `captain_index_file` | An uploaded file | | `captain_index_s3` | AWS S3 | | `captain_index_gcs` | Google Cloud Storage | | `captain_index_azure` | Azure Blob Storage | | `captain_index_r2` | Cloudflare R2 | | `captain_index_dropbox` | Dropbox | | `captain_index_supabase` | Supabase Storage | | `captain_index_backblaze` | Backblaze B2 | | `captain_index_sharepoint` | SharePoint | | `captain_index_onedrive` | OneDrive | | `captain_index_gdrive` | Google Drive | Every indexing tool also takes `custom_metadata`, `mask_pii` (mask detected personal data before embedding; a report is kept on the job), `max_files`, `skip_existing`, `overwrite_existing`, `transcription_language`, and `parsing_script` where the endpoint supports them. `captain_index_r2` takes the bucket's `jurisdiction`, including `us` for US data residency, and `captain_index_s3` accepts a cross-account IAM role instead of keys. In single-file mode, the S3, GCS, Azure, R2 and Dropbox tools also take `source_identity`: a stable identity for the document that is independent of where the object is read from, so indexing the same content from another location updates the same document instead of creating a second one. ### Syncs A sync keeps a collection aligned with a cloud-storage bucket: it backfills, reconciles on a schedule, can listen for real-time events, and propagates deletions. | Tool | What it does | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `captain_create_s3_sync` | Create an S3 sync | | `captain_create_r2_sync` | Create an R2 sync | | `captain_create_supabase_sync` | Create a Supabase sync | | `captain_create_backblaze_sync` | Create a Backblaze sync | | `captain_create_azure_sync` | Create an Azure Blob Storage sync (account name + account key; 60-minute default cadence) | | `captain_create_gcs_sync` | Create a Google Cloud Storage sync (service-account JSON) | | `captain_validate_sync` | Dry-run a sync's credentials and bucket before creating it | | `captain_list_syncs` | List syncs, across all storage types | | `captain_get_sync` | Get one sync's details | | `captain_update_sync` | Update a sync's config | | `captain_delete_sync` | Delete a sync | | `captain_reconcile_sync` | Run an on-demand diff and index | | `captain_subscribe_sync_webhook` | Enable real-time change events (SNS/SQS for S3, a signed ingest URL for other providers); rotate the secret after a leak | ### Chunks | Tool | What it does | | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `captain_list_chunks` | List a document's chunks | | `captain_get_chunk` | Get one chunk | | `captain_get_chunk_metadata` | Read a chunk's custom metadata | | `captain_set_chunk_metadata` | Overwrite a chunk's custom metadata | | `captain_update_chunk_metadata` | Merge into a chunk's custom metadata | | `captain_delete_chunk_metadata` | Delete a chunk's custom metadata | | `captain_batch_chunk_metadata` | Merge or replace custom metadata on up to 100 chunks in one request, with a result per item | | `captain_list_chunk_relations` | List relations between chunks | | `captain_create_chunk_relation` | Create a relation between chunks | | `captain_delete_chunk_relation` | Delete a relation | | `captain_batch_chunk_relations` | Create or update up to 100 relations in one request, matched by source chunk, target chunk, and relation type | ### Jobs | Tool | What it does | | --------------------------------- | ---------------------------------------------------------------------------------------------------- | | `captain_list_jobs` | List the organization's indexing jobs, newest first, with status, collection and environment filters | | `captain_job_status` | Check an indexing job's status: progress, per-file results, credits billed, PII report pointer | | `captain_cancel_job` | Cancel an in-progress job | | `captain_rollback_job` | Undo a finished job by removing the documents it wrote | | `captain_get_pii_report` | Read the PII masking report of a job that ran with `mask_pii` | | `captain_delete_pii_report` | Delete a retained PII report early | | `captain_validate_parsing_script` | Check a JavaScript parsing script in the sandbox before using it | ### Query history The queries your agents have run in the environment named on the call. Use them to see what an agent actually asked and what came back. | Tool | What it does | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `captain_list_queries` | List stored queries, newest first; filter by collection, status, and time window; page by cursor; opt in to `include` (results, request, response) for each query's retrieved chunks and exact bodies | | `captain_get_query` | One stored query by `query_id`, or by the `request_id` a query response returns: summary, exact request body, normalised results, optional exact response body | ### Evaluation Measure how well a collection retrieves the right documents, and compare query configurations on the same questions. `captain_eval` runs the questions from the client and scores them in the conversation; the other three hand the set to Captain as a job that keeps every answer. The [Evaluation API](/guides/evaluations) accepts API keys only in v1, so its three tools need a connection authenticated with a key rather than by signing in. Point an entry at the same hosted URL with a Captain API key as a bearer token, and the evaluation tools become available on it: ```json { "mcpServers": { "captain-evals": { "url": "https://mcp.captain.dev/mcp", "headers": { "Authorization": "Bearer cap_..." } } } } ``` The key implies its organization and environment, so a key-authenticated entry takes no consent step. The other tools on this page work over either kind of connection. | Tool | What it does | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `captain_eval` | Run a question set through `captain_search_v3` under each candidate configuration and score them as a paired test, so a gain between two configurations is reported as real or not | | `captain_create_eval_upload` | Serialise a case set of up to 10,000 questions with the documents each should retrieve, mint a single-use upload for the collection, and upload it; returns the `upload_id` | | `captain_run_eval` | Run an uploaded case set under one to eight named v3 configurations as an asynchronous job, replayable through an idempotency key; returns the `eval_id` | | `captain_get_eval_results` | Read an eval's status, progress, per-configuration scorecards (recall at 1, 3 and 10, MRR, nDCG at 10, latency percentiles), billing, and per-case hits and ranks; optionally the stored answers | [Evaluations](/guides/evaluations) covers the case-set format, scoring, limits and billing. [Compare Query Configs](/guides/mcp/evaluate-and-tune) walks through the client-side loop. ### Environments | Tool | What it does | | ---------------------------- | -------------------------------------------------------------- | | `captain_change_environment` | Move a collection between development, staging, and production | A moved collection is reachable through the same connection by naming the new environment in the `environment` argument every tool accepts. Attached syncs do not follow it. ### Project notes | Tool | What it does | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `captain_save` | Write a short note (a decision, a gotcha, a bug repro, a design constraint) to a per-project collection under a timestamped filename, creating the collection on first use | | `captain_find` | Search those notes; surfaces the timestamps, so a stale note is easy to spot | ### Integration wizard **`captain_wizard`** writes Captain into your codebase. It reads Captain's own agent docs at [llms.txt](https://docs.captain.dev/llms.txt) as the source of truth for the current API surface, covering indexing calls, search wiring, collection setup, and auth, then applies the changes for a task you describe. The first time you run it, it asks permission to send de-identified feedback about the integration (friction, missing capabilities, confusing docs) to Captain's [feedback endpoint](https://docs.captain.dev/reference/feedback/submit-feedback). No API key, no code, no personal data. Decline it if you prefer, and change the answer later at any time. ## Local install (deprecated) > **Warning** > > The local stdio build (`npx @captain-sdk/captain-mcp`) is deprecated and no > longer maintained. New tools and fixes ship only to the hosted server, so local > installs will fall behind. The one thing it still does that the hosted server > cannot is let `captain_index_file` read local filesystem `paths`. The hosted > server takes `urls` or inline base64 `files` instead. If you still need it, your client launches it with `npx` and it reads `CAPTAIN_API_KEY` from the environment: ```json { "mcpServers": { "captain": { "command": "npx", "args": ["-y", "@captain-sdk/captain-mcp@latest"], "env": { "CAPTAIN_API_KEY": "cap_..." } } } } ``` ## Links * [npm package](https://www.npmjs.com/package/@captain-sdk/captain-mcp) * [Source on GitHub](https://github.com/runcaptain/captain-mcp) * [Model Context Protocol](https://modelcontextprotocol.io) * [OpenClaw & Hermes](/guides/integrations/openclaw-hermes) for agent runtimes outside the MCP client ecosystem