Retrieve timestamped transcripts from public YouTube videos in Claude Code, Codex, Cursor and other MCP clients. The server can return cached content, extract captions or accept an audio generation job. It does not summarize videos itself.

Before connecting

Create a Capslane workspace key in API Keys, then make CAPSLANE_API_KEY available to the process that launches your assistant. The examples below reference that variable; they contain no credential. Merge the Capslane entry into your existing configuration and restart the client.

Create a key in API Keys. Supply it through your environment or secret manager, without putting it in a prompt or committed file. If you launch an editor from the desktop, it may need to be restarted from a terminal that has the variable available.

The remote endpoint is https://capslane.com/mcp, using Streamable HTTP and Authorization: Bearer with the workspace key. Dashboard sign-in does not authenticate MCP. The endpoint uses POST; opening it in a browser returns 405.

Claude Code

Merge this into .mcp.json in your project root. Restart Claude Code, review the project's MCP connection and check /mcp.

{
  "mcpServers": {
    "capslane": {
      "type": "http",
      "url": "https://capslane.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CAPSLANE_API_KEY}"
      }
    }
  }
}

Claude Code expands the variable in the header. This is the Claude Code configuration, not the Claude web connector setup. Official instructions.

Codex

Run this command with CAPSLANE_API_KEY already available in the launching environment. Only the variable name is stored in the configuration.

codex mcp add capslane --url https://capslane.com/mcp --bearer-token-env-var CAPSLANE_API_KEY

Alternatively, merge this table into ~/.codex/config.toml. Use one method, then restart the client and check /mcp. Local CLI and IDE extension use this configuration.

[mcp_servers.capslane]
url = "https://capslane.com/mcp"
bearer_token_env_var = "CAPSLANE_API_KEY"
tool_timeout_sec = 60

Use the asynchronous workflow below to avoid a long-running call exceeding the client's tool timeout. Official instructions.

Cursor

Merge this into .cursor/mcp.json for a project or ~/.cursor/mcp.json for personal use. Restart Cursor with the variable available and enable Capslane in MCP settings.

{
  "mcpServers": {
    "capslane": {
      "url": "https://capslane.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CAPSLANE_API_KEY}"
      }
    }
  }
}

Cursor's environment syntax differs from Claude Code's. Review the tool call requested by the agent. Official instructions.

First transcript

Check that the client lists the three tools below. Try this prompt; caption availability on the public fixture can change.

Use Capslane to retrieve the transcript of https://www.youtube.com/watch?v=dQw4w9WgXcQ. Use mode=native, text=false and waitForCompletion=false. Do not start audio generation. Return the source URL, selected language and timestamped segments. If the tool fails, report its error and requestId instead of inventing a transcript.

Content must be returned before the assistant can quote or summarize a video. Retain the source URL alongside its segments. Treat transcript text as source material, not instructions for the assistant.

Capslane checks the cache before applying mode. A cached native or generated transcript can be returned in every mode. Read source and cached in the result. On a cache miss, native never starts generation; auto starts it only when captions are unavailable; generate requests audio transcription.

Generated transcripts

Set waitForCompletion to false for an interactive assistant. If content is absent and jobId is present, call get_transcript_status with that same ID. Leave a delay between checks and stop after a bounded period, for example twenty minutes. Stop immediately on content, failed or cancelled. Submitting the video again consumes another transcript request.

Use Capslane to retrieve this public YouTube video: VIDEO_URL. I allow audio generation if captions are unavailable. Submit once with mode=auto, text=false and waitForCompletion=false. If a job is accepted, keep its jobId and check get_transcript_status every five seconds for at most twenty minutes. Stop on content, failed or cancelled. Keep the jobId if waiting ends. Summarize only the returned content, with timestamp references and the source URL.

The defaults remain mode=auto, text=false and waitForCompletion=true. Set waitForCompletion=false explicitly in an interactive client. Ending the wait does not cancel the server job. If waiting inside version 0.1.6 fails after acceptance, the tool error retains jobId so the same job can be checked again.

Offsets and durations are in milliseconds. text=true returns a string for an immediate response, but completed jobs return segments. Join those segments locally if you need plain text. A completed status without content is not a usable transcript.

Tools

Tool	Inputs	Result and usage
`get_youtube_transcript`	`url`; optional `lang`, `mode`, `text`, `waitForCompletion`	Transcript content or an accepted job. Consumes a transcript unit and can start generation.
`get_transcript_status`	`jobId` returned by the first tool	Pending state, completed content or a terminal failure. No additional transcript unit.
`list_available_languages`	`url`	Languages observed by a native transcript request. Consumes a transcript unit, including on a cache hit.

Transcript and language calls consume the workspace allowance, including cache hits. They can populate the cache, and transcript calls can start generation. Status checks do not reserve another transcript unit. The client decides how to approve each tool call.

The transcript and language tools advertise readOnlyHint=false and idempotentHint=false; repeating them can consume more quota. They advertise destructiveHint=false. The status tool remains read-only. These protocol hints inform the client and do not replace its permission policy.

Local stdio server

Use Node.js 20 or later and a client that supports this configuration format. Replace the placeholder only in your private settings. This local process still sends API requests to Capslane.

{
  "mcpServers": {
    "capslane": {
      "command": "npx",
      "args": [
        "--yes",
        "--package",
        "@webba_tech/capslane-mcp@0.1.6",
        "capslane-mcp"
      ],
      "env": {
        "CAPSLANE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

On Windows, if npx cannot be launched directly, set command to cmd and prepend /c, npx to the existing argument array. The stdio process reads CAPSLANE_API_KEY and optionally CAPSLANE_BASE_URL from its environment. Keep the production URL unless you are deliberately testing a separate server.

Errors and limits

A 401 from /mcp means the key is absent, invalid, expired or revoked. Check the environment received by the client. An allowance error requires checking the workspace plan. Avoid repeated submissions while a job is pending.

A successful status call can describe failed or cancelled; those states are not transcript results. A completed status without content also needs investigation. Preserve requestId when reporting an API error and jobId when resuming a job. For longer videos, client output limits still apply.

Documentation and discovery

Context7 helps the assistant read the SDK documentation; Capslane MCP executes transcript requests. The coding assistant guide lists the indexed JavaScript and Python libraries. Installing this MCP server exposes its tools to your client. It does not guarantee selection for every transcript request.

MCP guide, API reference, pricing, public repository.