> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audivo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP client

> Add Audivo to Codex, Claude Code, Claude Desktop, Cursor, VS Code, and other MCP clients.

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](#run-the-server-locally).

## Before you connect

1. Create an API key in your Audivo dashboard. Copy it when it is shown;
   [keys are only displayed once](/authentication).
2. Choose your client below and add the configuration. Replace `hk_live_...`
   with your full key, keeping the `Bearer ` prefix where shown.
3. 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.

<Note>
  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.
</Note>

## Choose your client

<AccordionGroup>
  <Accordion title="Codex — desktop app, CLI, and IDE extension" defaultOpen>
    **CLI:** set the key in the terminal where you launch Codex, then add the server:

    ```bash theme={null}
    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`:

    ```toml theme={null}
    [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](https://developers.openai.com/codex/mcp).
  </Accordion>

  <Accordion title="Claude Code">
    Run this in your terminal, replacing the sample key:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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](https://code.claude.com/docs/en/mcp).
  </Accordion>

  <Accordion title="Claude Desktop — macOS and Windows">
    Claude Desktop launches local servers, so run Audivo's server on your
    computer with the [`@audivo/mcp`](https://www.npmjs.com/package/@audivo/mcp)
    package. Install [Node.js LTS](https://nodejs.org/en/download), then open
    **Settings → Developer → Edit Config** in Claude Desktop.

    Merge this into `claude_desktop_config.json`:

    ```json theme={null}
    {
      "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](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
    · [Server source](https://github.com/AudivoDotDev/mcp).
  </Accordion>

  <Accordion title="Cursor — editor and CLI">
    Open your personal `~/.cursor/mcp.json` and merge this configuration:

    ```json theme={null}
    {
      "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](https://cursor.com/help/customization/mcp)
    · [Cursor CLI MCP commands](https://cursor.com/docs/cli/mcp).
  </Accordion>

  <Accordion title="VS Code — GitHub Copilot Chat">
    Open the Command Palette and run **MCP: Open User Configuration**. Merge
    this into the `mcp.json` file it opens:

    ```json theme={null}
    {
      "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](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
  </Accordion>

  <Accordion title="Windsurf / Cascade">
    Open Cascade's **MCP Servers** settings and edit the raw configuration,
    or open `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "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](https://docs.windsurf.com/windsurf/cascade/mcp).
  </Accordion>

  <Accordion title="Gemini CLI">
    Merge this into your personal `~/.gemini/settings.json`:

    ```json theme={null}
    {
      "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](https://geminicli.com/docs/tools/mcp-server/).
  </Accordion>

  <Accordion title="Cline — IDE extension and CLI">
    In the Cline panel, open **MCP Servers → Configure → Configure MCP Servers**.
    For the CLI, edit `~/.cline/mcp.json`. Merge:

    ```json theme={null}
    {
      "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](https://docs.cline.bot/mcp/mcp-overview).
  </Accordion>

  <Accordion title="OpenCode">
    Merge this into your personal `~/.config/opencode/opencode.json`:

    ```json theme={null}
    {
      "$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](https://opencode.ai/docs/mcp-servers/).
  </Accordion>
</AccordionGroup>

## Run the server locally

The hosted endpoint is the simplest route, but the same server is published
as [`@audivo/mcp`](https://www.npmjs.com/package/@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](https://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**

```bash theme={null}
claude mcp add --scope user audivo -e AUDIVO_API_KEY=hk_live_... -- npx -y @audivo/mcp
```

**Codex**

```bash theme={null}
codex mcp add audivo --env AUDIVO_API_KEY=hk_live_... -- npx -y @audivo/mcp
```

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

```json theme={null}
{
  "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](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt)
and [Claude custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## 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](#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](/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](/mcp-tools#workflow-troubleshooting)
and [API errors](/errors).