Capslane

Connect your assistant to Capslane

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.

Get the key from API Keys. Use your local environment or secret manager to supply it. Keep it out of prompts and committed files. An app opened from the desktop may need to be relaunched from a terminal that has the variable available.

The endpoint is https://capslane.com/mcp. It uses Streamable HTTP with an Authorization: Bearer header. Capslane MCP uses your API key; dashboard sign-in does not authenticate the connection. Choose your client below.

Claude Code, Codex or Cursor. You can also give an assistant this guide in Markdown.

Claude Code

Install the skill and connection together

The Capslane plugin bundles the transcript skill and remote MCP connection. Make CAPSLANE_API_KEY available in your terminal environment first, then run these commands. The user scope makes the plugin available across your projects.

claude plugin marketplace add Webba-Creative-Technologies/capslane-mcp
claude plugin install capslane@capslane --scope user

Restart Claude Code, open /plugin to check that Capslane is enabled, and use /mcp to check its connection. Review any permission request from your client. You can invoke the installed skill directly:

/capslane:capslane-youtube-transcripts Retrieve https://www.youtube.com/watch?v=dQw4w9WgXcQ with native captions and timestamp citations.

The plugin is published in the Capslane GitHub marketplace. It is free to install; transcript requests use your Capslane workspace allowance. Once enabled, Claude can load the skill for relevant requests. It respects a provider you explicitly choose and uses supplied transcripts directly when retrieval is unnecessary.

If you already installed the standalone skill or a Capslane MCP connection, choose one setup to avoid duplicate commands and tools. The plugin uses the same skill and endpoint. It does not require Node.js for the remote connection; the bundled HTTP fallback needs Node.js 22 or later.

Update or remove the plugin

Refresh the marketplace, update the plugin, then restart Claude Code.

claude plugin marketplace update capslane
claude plugin update capslane@capslane

Remove the user installation with this command. Revoke the workspace key separately in API Keys if you no longer need it.

claude plugin uninstall capslane@capslane --scope user

Configure only the MCP connection

Add this entry to .mcp.json at your project root. Claude Code expands the environment variable in the header when it loads the configuration. Open the project, review its MCP server request and run /mcp to check the connection.

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

Download the Claude Code configuration. These instructions target Claude Code. The Claude web connector has a different setup. See the Claude Code MCP documentation.

Codex

Run this command in a terminal where CAPSLANE_API_KEY is available. The command stores the variable name, so you do not need to put a key value in shell history.

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

You can instead merge the following table into ~/.codex/config.toml. Use one method. Restart the client and check /mcp; the configuration is shared by the local CLI and IDE extension.

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

Download the Codex configuration. For generated transcripts, use the job workflow below so the call fits the client's tool timeout. See the official Codex MCP documentation.

Cursor

Merge this entry into .cursor/mcp.json for one project, or ~/.cursor/mcp.json for your personal configuration. Cursor uses a different variable syntax from Claude Code. Restart Cursor with the environment variable available, then check that Capslane is enabled in its MCP settings.

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

Download the Cursor configuration. Review the requested tool call when the agent uses Capslane. See Cursor's MCP documentation.

Get a first transcript

Confirm that the three tools below appear in your client. Then try this prompt with the public example video. Caption availability can change; an explicit unavailable error is a valid outcome.

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.

{
  "url": "dQw4w9WgXcQ",
  "lang": "en",
  "mode": "native",
  "text": false,
  "waitForCompletion": false
}

The result must contain content before the assistant can quote or summarize the video. Retain the source URL alongside the returned segments. Capslane supplies transcript content; the assistant writes the summary.

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.

Handle a video without captions

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 tool defaults remain mode=auto, text=false and waitForCompletion=true. Passing the explicit values above avoids holding an interactive tool call open during generation. Ending the wait does not cancel the server job.

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 and workspace usage

Add the Capslane agent skill if you also want your assistant to have instructions for choosing transcript modes, following jobs and citing timestamps with these tools.

Tool	Purpose	Usage
get_youtube_transcript	Retrieve a transcript or accept a generation job.	One transcript request; generation limits can also apply.
get_transcript_status	Read the state or completed content of the same job.	No additional transcript unit.
list_available_languages	Read languages observed during a native transcript request.	One transcript request, 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.

Context7 provides documentation for writing an integration. The Capslane MCP server executes transcript requests. You can use both in the same project; the documentation guide lists the two SDK libraries.

Use the local stdio package

If your client cannot send an HTTP authentication header, use the npm package with Node.js 20 or later. This pinned configuration is intended for clients that support mcpServers and stdio. It still calls Capslane over the network.

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

Download the stdio configuration. Replace its placeholder in your private client settings. On Windows, if the client cannot launch npx directly, use cmd as the command and put /c and npx before the existing arguments.

The package and its registry metadata are maintained in the public MCP repository. Installing a server makes its tools available in that client; the client still chooses when to call them.

When the connection or request fails

A 401 from /mcp means the key is missing, invalid, expired or revoked. Check whether the assistant process received the variable. Do not use a dashboard session cookie or paste a key into the conversation. A browser visit to the endpoint returns 405 because the protocol uses POST requests.

If a job was already accepted, retain its ID after a timeout and resume with get_transcript_status. A terminal failed or cancelled state requires investigation, even if the status tool itself succeeded. An allowance error requires checking your plan, rather than rapid retries.

Keep returned transcript text separate from instructions to the assistant. For long videos, save segments in your application or request plain text when timestamps are unnecessary; client output limits still apply. The API error reference explains the common codes.