@audiodn/mcp
Model Context Protocol server for AudioDN.
Exposes the AudioDN REST API as MCP tools so AI agents (Cursor, Claude Desktop,
Claude Code, VS Code, Codex, etc.) can configure audio hosting on a user's
behalf, plus offline, read-only knowledge tools grounded in the canonical
AudioDN OpenAPI spec and documentation so agents look up the correct endpoints
instead of guessing.
Install in Cursor
One-click install (hosted endpoint β sign in with your AudioDN account via
OAuth when the client connects):

Prefer a local stdio server with an API Access key? Use this button instead:

Both correspond to the mcp.json shipped with this plugin. See
Cursor's MCP docs for manual setup.
Install
npm install -g @audiodn/mcp
npx @audiodn/mcp
Hosted (recommended for account login)
Point a remote-capable MCP client at https://mcp.audiodelivery.net/mcp with
no Authorization header. The client runs the MCP OAuth flow: you sign in at
account.audiodeliverynetwork.com, pick an organization, and Allow. That mints
a revocable API Access key (visible under Settings β API Keys as MCP Β· β¦).
Delete that key to disconnect.
Legacy configs that still send Authorization: Bearer <API Access key> or
X-ADN-API-Key continue to work.
Local stdio
Knowledge/doc tools work with no key. For live API tools, set a server-side
AudioDN API Access key (mint one in the dashboard at
https://account.audiodeliverynetwork.com under Settings β API Keys).
export ADN_API_KEY="adn_..."
Environment variables (stdio)
| Variable | Required | Default | Purpose |
|---|
ADN_API_KEY | No | β | Server-side API Access key for live-API tools. Knowledge tools work without it. |
ADN_API_BASE_URL | No | https://api.audiodelivery.net | Override the API host. |
ADN_MCP_LIVE_DOCS | No | off | Set to 1 to refresh bundled docs from the public site (falls back to the bundle offline). |
ADN_MCP_TIMEOUT_MS | No | 30000 | Per-request timeout in milliseconds. |
Safety model
- Reads and knowledge tools are annotated read-only.
- Create/update tools are annotated so MCP clients can prompt for approval; the
client is the human-in-the-loop layer.
- Delete tools (
adn_delete_creator, adn_delete_collection, adn_delete_track)
are available whenever live API tools are authenticated. They set
destructiveHint: true so clients should confirm before running them.
Hosted (remote) endpoint
Besides the local npx stdio server above, AudioDN runs the same tool set as a
hosted Streamable HTTP endpoint on Cloudflare Workers.
- URL:
https://mcp.audiodelivery.net/mcp β the MCP endpoint. The root
/ serves a human landing page in a browser (and JSON for tooling), and
/health returns machine-readable server info.
- Auth β OAuth account login: compatible clients discover
/.well-known/oauth-protected-resource and complete authorization code + PKCE
against this host. Unauthenticated /mcp requests return 401 with a
WWW-Authenticate challenge. Knowledge and live tools (including deletes)
require authentication on the hosted endpoint.
- Auth β legacy API key: send your AudioDN API Access key on every request:
Authorization: Bearer adn_...
# or
X-ADN-API-Key: adn_...
Example client configuration (OAuth β no pasted key):
{
"mcpServers": {
"audiodn": {
"url": "https://mcp.audiodelivery.net/mcp"
}
}
}
The hosted Worker lives in worker/ and is deployed with Wrangler
(npm run deploy); it is not part of the published npm package.
Worker secrets (not committed): MCP_JWT_SECRET, MCP_GRANT_ENCRYPTION_KEY,
MCP_INTERNAL_HMAC, plus a KV namespace bound as MCP_OAUTH.
Use with Cursor
Settings β Tools & Integrations β MCP (or edit ~/.cursor/mcp.json):
Hosted (OAuth):
{
"mcpServers": {
"audiodn": {
"url": "https://mcp.audiodelivery.net/mcp"
}
}
}
Local stdio:
{
"mcpServers": {
"audiodn": {
"command": "npx",
"args": ["-y", "@audiodn/mcp"],
"env": { "ADN_API_KEY": "adn_..." }
}
}
}
Use with Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
(or the equivalent on your OS), then restart the app:
{
"mcpServers": {
"audiodn": {
"command": "npx",
"args": ["-y", "@audiodn/mcp"],
"env": { "ADN_API_KEY": "adn_..." }
}
}
}
Use with Claude Code
claude mcp add audiodn --env ADN_API_KEY=adn_... -- npx -y @audiodn/mcp
Use with VS Code (Copilot) / Codex / Windsurf
Any client that speaks MCP over stdio uses the same command. For VS Code, add to
.vscode/mcp.json:
{
"servers": {
"audiodn": {
"command": "npx",
"args": ["-y", "@audiodn/mcp"],
"env": { "ADN_API_KEY": "adn_..." }
}
}
}
For Codex CLI (~/.codex/config.toml):
[mcp_servers.audiodn]
command = "npx"
args = ["-y", "@audiodn/mcp"]
env = { ADN_API_KEY = "adn_..." }
| Tool | Description |
|---|
adn_about | Server version, bundled OpenAPI version, docs source, API base. |
adn_search_docs | Keyword search over bundled docs + OpenAPI summaries. |
adn_list_operations | List all REST operations (operationId, method, path). |
adn_get_operation | Full OpenAPI definition for one operationId. |
adn_get_guide | Canonical guide (authentication, upload, processing, playback, webhooks, output-types / variant-types, security, compatibility). |
adn_list_output_types | The seven output types and which are API-creatable (adn_list_variant_types is a legacy alias). |
On the hosted endpoint these require authentication (OAuth or legacy API
key). On stdio they work without ADN_API_KEY.
| Tool | Description | Annotation |
|---|
adn_get_organization / adn_update_organization | Read/update org (id derived from API key when omitted) | read-only / write |
adn_create_client_key | Mint player / uploader / share key (returned once) | write |
adn_list_creators / adn_get_creator | Read creators | read-only |
adn_create_creator / adn_update_creator | Create/update creator | write |
adn_delete_creator | Delete creator | destructive |
adn_list_collections / adn_get_collection | Read collections | read-only |
adn_create_collection / adn_update_collection | Create/update collection | write |
adn_delete_collection | Delete collection + its tracks | destructive |
adn_create_collection_cover | Mint a fresh collection cover upload URL | write |
adn_list_tracks / adn_get_track | Read tracks. adn_get_track is metadata; use processing tools for readiness | read-only |
adn_find_resource | Exact name lookup for collection, creator, or track. Ambiguous names return candidates and do not create | read-only |
adn_get_processing | Uncached snapshot: upload_accepted, playable, per-output state | read-only |
adn_wait_for_processing | Short wait (default 12s) for playback, one output, settle, or cover. pending means call again with the same ids | read-only |
adn_create_track | One-shot track create (POST /v1/track) with upload URL | write |
adn_update_track | Update track metadata / player fields | write |
adn_delete_track | Soft-delete one track | destructive |
adn_create_track_cover | Mint a fresh track cover upload URL | write |
adn_create_upload_session / adn_get_upload_session | Manage upload sessions (optional nested track) | write / read-only |
adn_create_track_in_upload_session | Register a track, get track_upload.upload_url | write |
adn_create_play_session / adn_get_play_session | Mint/read play sessions (output indexes via variants wire field) | write / read-only |
adn_get_play_track | Signed URLs for a track inside a play session | read-only |
adn_get_play_download | Signed download URL for one output index (downloadable sessions) | read-only |
adn_list_output_presets / adn_get_output_preset | List/get org output presets (legacy: adn_list_variants / adn_get_variant) | read-only |
adn_create_track_output | Add a track-specific transcode/preview output (legacy: adn_create_track_variant) | write |
Resources
The server also exposes canonical docs as MCP resources for clients that attach
context directly: audiodn://openapi.json, audiodn://llms-full.txt, and
audiodn://guide/{topic} for each guide.
Example flow
An agent helping a user host a podcast might call:
adn_get_guide({ topic: "upload" }) β learn the canonical multi-step flow.
adn_create_collection({ title: "My Podcast" })
adn_create_upload_session({ collection_id }) β or pass nested
track: { file_name } to create the first track in the same call.
adn_create_track_in_upload_session({ upload_session_id, file_name: "ep1.mp3" })
(skip if you already nested track above).
- Your code
PUTs the audio bytes to track_upload.upload_url. Create does not upload.
adn_wait_for_processing({ target: "track_playback", track_id }).
pending with UPLOAD_NOT_ACCEPTED means the PUT has not landed.
pending with OUTPUT_PROCESSING or PROCESSING_TIMEOUT means workers are
still running β call the same tool again with the same ids. incomplete can
still be playable. To wait for one file (waveform, preview), use
target: "track_output" and output_index.
adn_list_output_presets() β pick real output indexes (e.g. hq, lq).
adn_create_play_session({ scope: "track", track_id, variants: ["hq"] }) β
returns a play_session_id (for the ADN Player) plus signed file URLs on
first_track (for a custom player).
Build from source
npm install
npm run build
npm test
npm run smoke
node dist/index.js
Local development (API + MCP)
Run the AudioDN API and this MCP worker on different ports, then exercise OAuth
and tools with the manual scripts under manual/:
npm run dev:api
cp .dev.vars.example .dev.vars
npm run dev:local
npm run manual:auth
npm run manual
ADN_API_BASE_URL in .dev.vars (or the stdio environment) is the switch for
which AudioDN API the MCP server calls. Production wrangler.toml keeps the
public API default.
Deploy the hosted endpoint
The Cloudflare Worker in worker/ serves the same tools over Streamable HTTP.
npx wrangler login
npm run dev:worker
npm run dev:local
npm run deploy
curl https://mcp.audiodelivery.net/health
The custom domain mcp.audiodelivery.net is provisioned by Cloudflare from the
routes entry in wrangler.toml (the audiodelivery.net zone must be on the
same Cloudflare account).
To list on the official MCP registry (registry name net.audiodelivery/mcp,
which must match mcpName in package.json): verify the domain once with
mcp-publisher login dns --domain audiodelivery.net (add the printed TXT
record), confirm remotes[0].url in server.json points at the deployed URL,
then mcp-publisher publish.
Keeping docs fresh
Bundled snapshots live in assets/snapshots/. Refresh them from the public site
with npm run sync; prepublishOnly verifies they are consistent before a
release.
Reference