Connect an MCP client

Give your AI assistant podcast search and transcripts: ask for an episode and it comes back transcribed, charged to your account’s credits. Audivo’s remote MCP server connects two ways — sign in with your Audivo account, or send an API key. You do not need to run an Audivo server locally, but you can: the same server is on npm as @audivo/mcp, and locally it also transcribes files and YouTube videos; see Run the server locally.

Setting	Value
Server name	`audivo`
Transport	Streamable HTTP
MCP URL	`https://api.audivo.dev/mcp`
Authentication	Sign in (OAuth), or the header `Authorization: Bearer hk_live_...`

This is the production endpoint. Keep /mcp at the end of the URL, and note the host: docs.audivo.dev/mcp is this documentation site’s own search server, not the podcast one. Clients that support MCP sign-in need only the URL. Add https://api.audivo.dev/mcp as a remote server; when the client asks you to connect, a browser opens on Audivo. Sign in (or create an account), check the app named on the screen, and choose Allow.

Claude (web, desktop, and mobile): Settings → Connectors → Add custom connector, paste the URL, then Connect. Claude custom connectors.
ChatGPT: turn on developer mode under Settings → Apps → Advanced settings, create an app with the URL, and choose OAuth. ChatGPT MCP connections.
Claude Code: claude mcp add --transport http --scope user audivo https://api.audivo.dev/mcp, then run /mcp and choose Authenticate.
Codex: codex mcp add audivo --url https://api.audivo.dev/mcp, then codex mcp login audivo.
VS Code, Cursor, and others that support MCP OAuth: add the URL with no header; the client starts sign-in itself.

A connection acts on your account as an API key does and spends the same credits. It appears in the dashboard under Settings → Connected apps, where you can disconnect it; it stops working within five minutes, like a revoked key. Only one thing is shared with the app: a credential for this account, never your password.

Connect with an API key

Every client that can send a header works this way, including the ones below that have no sign-in support.

Create an API key in your Audivo dashboard. Copy it when it is shown; keys are only displayed once.
Choose your client below and add the configuration. Replace hk_live_... with your full key, keeping the Bearer prefix where shown.
Restart or reconnect the client, then try the search prompt below.

Merge the examples into your existing configuration; keep any other servers you already use. Store keys in a personal configuration or your client’s secret input, and keep files containing real keys out of Git and shared chats.

Choose your client

Codex — desktop app, CLI, and IDE extension

CLI: set the key in the terminal where you launch Codex, then add the server:

export AUDIVO_API_KEY='hk_live_...'
codex mcp add audivo \
  --url https://api.audivo.dev/mcp \
  --bearer-token-env-var AUDIVO_API_KEY
codex mcp list

In PowerShell, set the variable with $env:AUDIVO_API_KEY = 'hk_live_...' and run the codex mcp add command on one line.Desktop app or IDE: edit your personal ~/.codex/config.toml:

[mcp_servers.audivo]
url = "https://api.audivo.dev/mcp"
http_headers = { Authorization = "Bearer hk_live_..." }

Use one authentication option: if the CLI already created this entry, replace bearer_token_env_var with http_headers instead of adding a duplicate table. Alternatively, keep bearer_token_env_var = "AUDIVO_API_KEY" if the app’s process has that environment variable. A terminal export alone may not reach an app launched from the Dock.Restart the app or extension. In the CLI, start a new session and use /mcp to check the tools. With a key configured you do not need codex mcp login; that is the sign-in route.Codex MCP configuration reference.

Claude Code

Run this in your terminal, replacing the sample key:

claude mcp add --transport http --scope user audivo \
  https://api.audivo.dev/mcp \
  --header "Authorization: Bearer hk_live_..."
claude mcp get audivo

--scope user makes Audivo available across your projects. The command stores the header in your local Claude configuration; avoid running it in a shared terminal with a real key.For project configuration, merge this into .mcp.json and set AUDIVO_API_KEY in the environment before launching Claude Code:

{
  "mcpServers": {
    "audivo": {
      "type": "http",
      "url": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer ${AUDIVO_API_KEY}" }
    }
  }
}

Choose either user or project configuration. Start a new Claude Code session, run /mcp, and check that audivo connects. Approve the project server when prompted, then try the search prompt below.Claude Code MCP configuration reference.

Claude Desktop — macOS and Windows

Claude Desktop launches local servers, so run Audivo’s server on your computer with the @audivo/mcp package. Install Node.js LTS, then open Settings → Developer → Edit Config in Claude Desktop.Merge this into claude_desktop_config.json:

{
  "mcpServers": {
    "audivo": {
      "command": "npx",
      "args": ["-y", "@audivo/mcp@latest"],
      "env": { "AUDIVO_API_KEY": "hk_live_..." }
    }
  }
}

The file lives at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Fully quit and reopen Claude Desktop. Enable audivo in the conversation’s tools/connectors menu and try the search prompt below. If npx cannot be found, use its full path from which npx (macOS) or where npx (Windows).The server runs on your computer, reads the key from env, and calls Audivo over HTTPS with it; it stores nothing. This setup is local to Desktop; it does not install a connector in Claude on the web or mobile.Desktop configuration guide · Server source.

Cursor — editor and CLI

Open your personal ~/.cursor/mcp.json and merge this configuration:

{
  "mcpServers": {
    "audivo": {
      "url": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer hk_live_..." }
    }
  }
}

For a single project, Cursor also reads .cursor/mcp.json in the project root. Keep a file containing your key out of version control.Open Cursor’s MCP settings, enable audivo, and check that its tools appear. Start an Agent conversation and try the search prompt below. If using the Cursor CLI, run agent mcp list and agent mcp list-tools audivo to inspect the connection and tools.Cursor MCP setup · Cursor CLI MCP commands.

VS Code — GitHub Copilot Chat

Open the Command Palette and run MCP: Open User Configuration. Merge this into the mcp.json file it opens:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "audivo-api-key",
      "description": "Audivo API key",
      "password": true
    }
  ],
  "servers": {
    "audivo": {
      "type": "http",
      "url": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:audivo-api-key}" }
    }
  }
}

Run MCP: List Servers, select audivo, and start it. Enter your API key when prompted. Open Copilot Chat in Agent mode and enable Audivo’s tools. VS Code stores the prompted value separately from this file.For workspace configuration, use .vscode/mcp.json. VS Code uses the root key servers, not mcpServers. This example targets Copilot Chat in the extension host; input-prompt servers are not forwarded to the Agent Host.VS Code MCP configuration reference.

Windsurf / Cascade

Open Cascade’s MCP Servers settings and edit the raw configuration, or open ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "audivo": {
      "serverUrl": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer hk_live_..." }
    }
  }
}

Save, refresh the MCP servers, and enable Audivo’s tools in Cascade. Start a conversation and try the search prompt below.This is the Cascade configuration. Newer Devin Desktop installations use separate settings for the Devin Local agent; open Cascade to use this file.Cascade MCP configuration reference.

Gemini CLI

Merge this into your personal ~/.gemini/settings.json:

{
  "mcpServers": {
    "audivo": {
      "httpUrl": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer hk_live_..." },
      "trust": false
    }
  }
}

Restart Gemini CLI and run /mcp to check the server and tools. Keep trust set to false so tool calls retain approval prompts.Gemini uses httpUrl for Streamable HTTP. Its url field selects legacy SSE and is not the right transport for Audivo. A project can instead use .gemini/settings.json; keep real keys out of committed files.Gemini CLI MCP configuration reference.

Cline — IDE extension and CLI

In the Cline panel, open MCP Servers → Configure → Configure MCP Servers. For the CLI, edit ~/.cline/mcp.json. Merge:

{
  "mcpServers": {
    "audivo": {
      "type": "streamableHttp",
      "url": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer hk_live_..." },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Save and reconnect the server. Check the tool list in the MCP panel, or use cline mcp in the CLI. Start a task and try the search prompt below. Leave autoApprove empty to review tool calls.Set type explicitly: Cline defaults to legacy SSE when it is omitted.Cline MCP configuration reference.

OpenCode

Merge this into your personal ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "audivo": {
      "type": "remote",
      "url": "https://api.audivo.dev/mcp",
      "headers": { "Authorization": "Bearer {env:AUDIVO_API_KEY}" },
      "oauth": false,
      "enabled": true
    }
  }
}

Set AUDIVO_API_KEY in the environment where OpenCode runs, restart it, and run opencode mcp list. Ask OpenCode to use Audivo for the search prompt below. oauth: false keeps this API-key connection from starting an OAuth flow.OpenCode MCP configuration reference.

Run the server locally

The hosted endpoint is the simplest route, but the same server is published as @audivo/mcp for clients that only launch local processes, or for when you would rather run it yourself. It has the hosted server’s eleven tools and two more, because it can reach your machine: transcribe also takes a file path or a YouTube link, upload_audio sends a file on its own, and youtube_search finds an episode that has no podcast feed (see Transcribe audio you have). It calls api.audivo.dev with your key and stores nothing but a copy of yt-dlp, fetched the first time you use YouTube. Source and issues: github.com/AudivoDotDev/mcp. It needs Node.js 22 or newer. Set the key in the environment the client starts the server with:

Variable	Required	Meaning
`AUDIVO_API_KEY`	Yes	Your API key. `Bearer` in front of it is accepted.
`AUDIVO_API_BASE_URL`	No	The API origin. Defaults to `https://api.audivo.dev`.
`AUDIVO_YTDLP_PATH`	No	A yt-dlp to use for YouTube instead of the managed one.

Claude Code

claude mcp add --scope user audivo -e AUDIVO_API_KEY=hk_live_... -- npx -y @audivo/mcp@latest

Codex

codex mcp add audivo --env AUDIVO_API_KEY=hk_live_... -- npx -y @audivo/mcp@latest

Any JSON-configured client (Cursor, Windsurf, Claude Desktop, and others)

{
  "mcpServers": {
    "audivo": {
      "command": "npx",
      "args": ["-y", "@audivo/mcp@latest"],
      "env": { "AUDIVO_API_KEY": "hk_live_..." }
    }
  }
}

The server writes only protocol messages to stdout. Its log lines go to stderr and never include the key.

Updates

The hosted server at https://api.audivo.dev/mcp is always the current release. The local one updates itself: @audivo/mcp@latest makes npx look the package up on npm each time your client starts the server, so a new release arrives with your next session. To pick it up in the session you are in, restart the server; in Claude Code, run /mcp, choose audivo, then Reconnect. Keep @latest in your configuration: a bare @audivo/mcp resolves to a copy installed in the current project first, when there is one. If you installed the Audivo plugins for Claude Code, the servers update the same way. The plugin itself updates from its marketplace, which Claude Code leaves on manual for marketplaces other than Anthropic’s: turn on Enable auto-update for audivo under Marketplaces in /plugin, or run claude plugin marketplace update audivo and then claude plugin update audivo-local@audivo.

Other MCP clients and custom agents

Choose Streamable HTTP and enter the MCP URL. Then either let the client sign in — Audivo publishes the standard OAuth discovery documents, supports dynamic client registration and client metadata documents, and requires PKCE — or send the Authorization header. Clients that only launch local stdio servers can run the server on your machine instead; see Run the server locally. Never put an API key in the endpoint URL. Configuration names differ between clients: url, httpUrl, serverUrl, servers, and mcpServers are not interchangeable. Use your client’s format. There is no separate SSE endpoint and no npm package needed for a direct HTTP connection.

Verify the connection

Ask your assistant:

Use Audivo to search for “The Changelog” and show me the matching podcasts.

It should call search_shows and return show identifiers and titles. This checks authentication and the API connection without spending credits. The hosted server exposes eleven tools and the local server thirteen; a connected status or tool list alone does not prove an authenticated tool call works. Next, try:

Transcribe the latest episode of the show I choose. Spend at most 90 credits.

Continue with Using the MCP tools for example prompts, batches priced before spending, and the tool reference.

Troubleshooting

Symptom	What to check
Host cannot be resolved	Use the production URL above. Older examples built on an `execute-api.us-east-1.amazonaws.com` address are superseded.
`401` or `unauthenticated`	Replace the sample with an active key and send `Authorization: Bearer` followed by that key. Check that the app process can read any referenced environment variable.
Sign-in opens but does not finish	Sign in to the dashboard in the same browser and choose Allow within ten minutes. If the page says the request expired, start connecting again from the client.
A key is configured but sign-in opens	The client did not send the header. Check its exact field name for headers, or remove the key and use sign-in.
`404`, `403`, or a transport error	Keep `/mcp`, choose Streamable HTTP, and remove any extra `/v1` or `/sse`. Visiting the URL in a browser sends a GET and is not a valid connection test.
Server is absent or tools are missing	Check the file location and JSON/TOML syntax, restart the client, and enable the server and tools. Check workspace policy if MCP is disabled by an administrator.
Claude Desktop reports `npx` missing	Install Node.js LTS and give the server the full path to `npx`. Fully quit and reopen Claude Desktop.
`upload_audio` or YouTube is missing	Both exist only on the local server (`npx -y @audivo/mcp@latest`), because they read from your disk or fetch on your machine. The hosted endpoint does neither.
`429` or `rate_limited`	Follow `Retry-After` and reduce repeated calls. All clients using the account share its limits.

For quote, credit, and transcript errors, see MCP workflow troubleshooting and API errors.

Start

Guides

MCP server

Reference

Billing

Trust

Connect an MCP client

Connect with an API key

Choose your client

Run the server locally

Updates

Other MCP clients and custom agents

Verify the connection

Troubleshooting

​Sign in instead of a key

​Connect with an API key

​Choose your client

​Run the server locally

​Updates

​Other MCP clients and custom agents

​Verify the connection

​Troubleshooting

Sign in instead of a key

Connect with an API key

Choose your client

Run the server locally

Updates

Other MCP clients and custom agents

Verify the connection

Troubleshooting