---
title: "AudD MCP Server"
description: "Let AI agents manage your AudD account over the Model Context Protocol — check usage, read or rotate the API token, and handle plans and payments, with OAuth sign-in and scope-based permissions."
url: "https://docs.audd.io/mcp"
source: "https://docs.audd.io/mcp.md"
---
# AudD MCP Server

Let your AI agents work with your AudD account by using our MCP server:

```text
https://mcp.audd.io
```

The AudD Model Context Protocol (MCP) server gives agents a set of tools
for working with your AudD account: usage statistics, the API token, plans
and billing, the official API docs, and one-off API calls — an agent can
check how many requests you have left, fetch or rotate the `api_token`,
identify a song from a URL, or prepare a plan upgrade for you to approve.
For repeated or programmatic recognition, the right pattern is still the
[HTTP API](/) and the [SDKs](/sdks) called directly with the `api_token` —
`make_api_request` exists for one-off and interactive calls.

Everything is authorized through your [dashboard](https://dashboard.audd.io)
sign-in with OAuth, scoped to exactly what you grant. Payment tools never
charge anything by themselves — they return a Stripe payment link that you
open and approve in a browser.

## Connect

**claude-code:**

```bash
claude mcp add --transport http audd https://mcp.audd.io/
```

Then run `/mcp` inside Claude Code to sign in via the browser.

**claude:**

In Claude (web or desktop): Settings → Connectors → **Add custom
connector** → paste `https://mcp.audd.io` — Claude walks you through the
sign-in.

**cursor:**

```json
{
  "mcpServers": {
    "audd": {
      "url": "https://mcp.audd.io"
    }
  }
}
```

**vscode:**

```json
{
  "servers": {
    "audd": {
      "type": "http",
      "url": "https://mcp.audd.io"
    }
  }
}
```

**other:**

Any MCP client that speaks Streamable HTTP with OAuth works. The server
publishes standard discovery metadata
(`/.well-known/oauth-authorization-server` and
`/.well-known/oauth-protected-resource`) and supports **dynamic client
registration**, so there is nothing to pre-register: point the client at
`https://mcp.audd.io`, and it takes care of the rest.

## Authentication and scopes

The server uses OAuth 2.0 (authorization code with PKCE, refresh tokens).
When a client connects, you sign in through
[dashboard.audd.io](https://dashboard.audd.io) and approve the scopes it
asked for. Grant only what the workflow needs:

| Scope | Grants |
|---|---|
| `profile:read` | Account email and connected sign-in methods |
| `account:read` | Plan, subscription status, paid-until date, bonus requests |
| `usage:read` | Aggregate daily request counts and allowance |
| `billing:read` | Payment history, amount owed, available plans |
| `billing:pay` | Creating Stripe payment links (never charges by itself) |
| `api:request` | Calling the AudD API as the account — recognition, lyrics, streams management — on the account's quota |
| `token:read` | Reading the account `api_token` — sensitive |
| `token:write` | Rotating the `api_token` — the old token stops working immediately |

The tool list itself is scoped: tools whose scope you didn't grant don't
appear to the client at all. Dynamically-registered clients receive a
default grant that excludes `token:write`, and the authorization endpoint
rejects scope requests beyond a client's registration (`invalid_scope`)
rather than silently narrowing them. Access tokens are short-lived with
refresh tokens issued alongside; access can be revoked at any time via the
standard OAuth revocation endpoint (published in the discovery metadata),
and removing the connector from your client stops it from making further
calls.

## Tools

| Area | Tool | Description |
|---|---|---|
| API | `make_api_request` | Call the AudD API as the account — recognition, lyrics, streams management. Audio by URL only; spends the plan's quota like a direct call |
| | `get_api_docs` | The official API documentation as markdown, by topic: `api`, `streams`, `enterprise`, `file-upload` |
| Account | `get_profile` | The account email and connected sign-in methods |
| | `get_account_status` | Current plan, subscription status, paid-until date, bonus requests, auto-renew |
| Usage | `get_usage_stats` | Current billing-cycle total, allowance, remaining, and per-day counts; optionally the last N days |
| API token | `get_api_token` | Returns the `api_token` — the preferred way to set up an integration that then calls the API directly |
| | `rotate_api_token` | Replaces the `api_token` with a new one; the old token stops working immediately |
| Billing | `list_plans` | The available subscription plans with pricing and included requests |
| | `get_billing_history` | Recent payments: subscriptions, renewals, extras, bonus purchases |
| | `get_amount_owed` | Over-allowance usage accrued this cycle and what it will cost at the next renewal |
| Payments | `subscribe_to_plan` | Payment link to subscribe to (or switch to) a plan from `list_plans` |
| | `create_renewal_payment` | Payment link to renew the subscription, including any owed extras |
| | `buy_bonus_requests` | Payment link for N extra API requests (multiples of 1,000) |

The three payment tools create a Stripe-backed payment link that the account
owner must open and approve in a browser. **Nothing is ever charged
automatically.**

Usage data is aggregate daily statistics only — the server exposes no
per-request detail.

`make_api_request` is for one-off, interactive calls ("what's this song?").
For anything repeated or programmatic, have the agent call `get_api_token`
once and use the [API](/) or an [SDK](/sdks) directly — more efficient and
reliable than routing every request through the MCP server. Binary file
upload is not possible through the tool; pass audio by URL.

## Things to ask your agent

- *"What song is playing in this clip? https://…/clip.mp3"*
- *"How many AudD requests do I have left this cycle?"*
- *"Plot my AudD usage for the last 30 days."*
- *"Set up this project's `AUDD_API_TOKEN` from my account."*
- *"My token may have leaked — rotate it and update my env."*
- *"I keep hitting the allowance — what would the next plan up cost? Prepare the payment link."*

## Security notes

- **Grant scopes narrowly.** A usage-monitoring agent needs `usage:read` and
  nothing else. Reserve `token:read`/`token:write` and `billing:pay` for
  workflows that genuinely need them.
- **Token rotation is immediate.** `rotate_api_token` kills the old token
  the moment it runs — anything still using it starts failing. Keep human
  confirmation enabled for this tool and for the payment tools.
- **`make_api_request` spends real quota and can change stream state.**
  Each call bills like a direct API request, and paths like `setCallbackUrl`
  or `addStream` mutate the account's stream configuration — keep
  confirmation on if you grant `api:request` to an autonomous agent.
- **Watch for prompt injection.** As with any MCP setup, be cautious about
  running this server alongside tools that feed untrusted content (web
  pages, user uploads) to the same agent, and keep tool-call confirmation on
  in your client.
- **Prefer the MCP over pasting tokens.** An agent that can call
  `get_api_token` under a scoped, revocable grant is safer than an
  `api_token` hard-coded into prompts or config it doesn't need.

## See also

- [API reference](/) — the recognition API itself
- [Official SDKs](/sdks) — call the API from your language
- [Dashboard](https://dashboard.audd.io) — the human-facing account console

## Sitemap

See the [docs sitemap](https://docs.audd.io/sitemap.md) for every page and the [glossary](https://audd.io/resources/reference/glossary.md) for AudD terms.