Connect an MCP client

Give your AI assistant access to podcast search, episode discovery, pricing, and transcripts. Audivo’s remote MCP server uses your existing API key and account credits. You do not need to run an Audivo server locally, but you can: the same server is on npm as @audivo/mcp; see Run the server locally.

Before you connect

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.

Setting	Value
Server name	`audivo`
Transport	Streamable HTTP
MCP URL	`https://api.audivo.dev/mcp`
Authentication	`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. Audivo uses API-key headers; there is no Audivo OAuth login flow.

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. Skip codex mcp login: Audivo takes an API key.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"],
      "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 exposes the same nine tools, calls api.audivo.dev with your key, and stores nothing. 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`.

Claude Code

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

Codex

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

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

{
  "mcpServers": {
    "audivo": {
      "command": "npx",
      "args": ["-y", "@audivo/mcp"],
      "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.

ChatGPT and Claude on the web

Audivo currently requires a static API key in an Authorization header and has no OAuth discovery or sign-in endpoints. The standard hosted connector setup flows do not provide a documented way to attach an Audivo API key as a custom header, so we do not currently offer a direct setup for those flows. Pasting the endpoint alone is not enough. Use Codex, Claude Code, or the local server in Claude Desktop above. A hosted integration would need an adapter that supplies the header and supports the host’s authentication requirements. Do not put your API key in the endpoint URL. Host references: ChatGPT MCP connections and Claude custom connectors.

Other MCP clients and custom agents

Choose Streamable HTTP and enter the MCP URL and Authorization header from the settings table above. The client must support custom headers on its MCP requests. Clients that only launch local stdio servers can run the server on your machine instead; see Run the server locally. 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 server exposes nine tools; a connected status or tool list alone does not prove an authenticated tool call works. Next, try:

Find the latest episode of the show I choose. Quote the transcript, show me the maximum credits, and wait for my approval before confirming.

Continue with Using the MCP tools for the full quote-to-transcript workflow, example prompts, 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.
OAuth login opens or fails	Use the API-key header configuration. Audivo does not provide an OAuth login.
`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.
`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

Before you connect

Choose your client

Run the server locally

ChatGPT and Claude on the web

Other MCP clients and custom agents

Verify the connection

Troubleshooting

​Before you connect

​Choose your client

​Run the server locally

​ChatGPT and Claude on the web

​Other MCP clients and custom agents

​Verify the connection

​Troubleshooting

Before you connect

Choose your client

Run the server locally

ChatGPT and Claude on the web

Other MCP clients and custom agents

Verify the connection

Troubleshooting