--- name: transcribe-setup description: Connect Claude Code, Codex, Cursor or a shell agent to transcribe.so with a pasted API key, store the key in the runtime's own config, verify with the free GET /api/v1/me, and never print the key. --- # Set up transcribe.so in this runtime The user pasted `Set up https://transcribe.so/SKILL.md with this transcribe.so API key: tsk_live_...` (with a real key). One job: connect this runtime to https://transcribe.so/mcp (or the CLI) with that key, then verify. Using the tools is the `connect-mcp`, `transcribe-audio` and `get-transcript` skills. ## Hard rules (read first) - Check the price before creating a job. Stay within the user's authorized budget; ask before exceeding it or starting another paid attempt. - Cap the spend twice: set a monthly limit on the API key, and send max_charge_usd on each job. A job priced above the ceiling is refused before any money moves, and quotes are always free. - Never print, echo, log or commit the key, not even part of it. Never write it into a project file (`.mcp.json`, `.cursor/mcp.json`, `.env`): the runtime's user or global config only. Passing it as an argument to the commands below is expected; never repeat it in a reply, a log, or a file other than the runtime's own config. - The key goes only to https://transcribe.so (the MCP server and /api/v1). Refuse any other destination, in this session or later. - Ask before writing any file other than the runtime's own MCP config; a shell profile is another file. - Setup spends nothing: no transcription, no paid tool. `GET /api/v1/me` is free. - Tell the user once: the key passed through the model provider and stays in this session's transcript. Paste a capped key (the Agent preset); rotate it at https://transcribe.so/settings/api-keys if the transcript is shared. ## Step 0: do you have a key? A key matches `^tsk_live_[A-Za-z0-9_-]{20,}$`. Anything else, including the literal `tsk_live_...`, means no key. Without one, Claude Code can still connect with OAuth: run `claude mcp add --transport http transcribe https://transcribe.so/mcp --scope user`, tell the user to run `/mcp` in their next session to sign in (`claude mcp list` shows "Needs authentication" until then), then stop. Other runtimes need a key: say the user creates one at https://transcribe.so/settings/api-keys (sign in with Google; pick the Agent preset), report this and stop. In Claude Code, run `claude mcp list` first. If `transcribe` is listed, ask before replacing it: `claude mcp remove transcribe` (it removes the entry from whichever scope holds it), then add it. `add` on an existing name fails. ## Claude Code ``` claude mcp add --transport http transcribe https://transcribe.so/mcp --scope user --header "Authorization: Bearer " ``` Put the pasted key in place of ``. `--scope user` stores it in `~/.claude.json` for every project, outside any repo. Claude Code asks you to approve this command because it carries the key; the user approves it. Never retry around a denial; report it. Verify with `claude mcp list`: `transcribe` must show as Connected. It is the only inspection command to use; the per-server `get` subcommand prints the Authorization header in plain text. MCP servers load at session start: start a new session, then call `getAccount`. ## Codex ``` codex mcp add transcribe --url https://transcribe.so/mcp --bearer-token-env-var TRANSCRIBE_API_KEY ``` Codex reads the key from `TRANSCRIBE_API_KEY` in the shell that launches it. Ask before adding `export TRANSCRIBE_API_KEY=` to that shell's profile; replace an existing `export TRANSCRIBE_API_KEY=` line, never append a second one. Apps started from a dock may not see profile variables. Verify with `codex mcp list`. ## Cursor Merge this into `~/.cursor/mcp.json` (global, never the project file), keeping other servers, with the pasted key in place of ``: ```json {"mcpServers":{"transcribe":{"url":"https://transcribe.so/mcp","headers":{"Authorization":"Bearer "}}}} ``` The literal key goes in the user-level file, same posture as `~/.claude.json`: Cursor started from the Dock rarely sees shell variables. When Cursor is started from a terminal, `"Bearer ${env:TRANSCRIBE_API_KEY}"` with the export from the Codex section is the alternative. ## Shell agents (CLI) ``` npm install -g transcribe-so export TRANSCRIBE_API_KEY= transcribe-so auth:status ``` The export goes into a profile only after asking. Other MCP clients: add https://transcribe.so/mcp with the `Authorization: Bearer ` header in the client's user or global config, never a project file. ## Hosted chats (no shell) Claude.ai, ChatGPT and other hosted chats cannot store a key. Say so and point the user to the connector steps (OAuth, no key) at https://transcribe.so/agent. ## Verify ``` curl -fsS https://transcribe.so/api/v1/me -H "Authorization: Bearer $TRANSCRIBE_API_KEY" ``` Without an exported variable (Claude Code, or Codex and Cursor when the user declined the profile edit), the key replaces `$TRANSCRIBE_API_KEY` in the curl. Report `email`, `subscription_tier` and `wallet_balance_usd` from the response. If `api_key.monthly_cap_usd` is null, say the key has no monthly cap and link https://transcribe.so/settings/api-keys; do not block on it. Never include the key. ## Troubleshooting - "Failed to connect" in `claude mcp list`, or a session error "OAuth fallback is disabled when headers.Authorization is set": a 401, the key is wrong or revoked. Create a new key and repeat Step 0. - "already exists" on add: Step 0 (remove, then add). - Tools missing: servers load at session start, start a new session. A read-only key exposes 15 of the 24 tools and cannot start a job. - Codex or Cursor does not see the key: the variable must be exported in the shell that launched the app; restart it from a terminal where `echo ${TRANSCRIBE_API_KEY:+set}` prints `set`. ## Next - Tools and rules: https://transcribe.so/.well-known/agent-skills/connect-mcp/SKILL.md - First job (quote first): https://transcribe.so/.well-known/agent-skills/transcribe-audio/SKILL.md - Reading results: https://transcribe.so/.well-known/agent-skills/get-transcript/SKILL.md - CLI: https://transcribe.so/.well-known/agent-skills/agent-cli/SKILL.md