Audio Delivery Network

@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

or run on demand

npx @audiodn/mcp

Configure

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 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_..."

Optional overrides:

export ADN_API_BASE_URL="https://api.audiodelivery.net" # default

export ADN_MCP_LIVE_DOCS=1 # refresh bundled docs from the public site at startup

export ADN_MCP_TIMEOUT_MS=30000 # per-request timeout

Environment variables (stdio)

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_..." }

Tools

Knowledge tools (read-only, offline)

On the hosted endpoint these require authentication (OAuth or legacy API key). On stdio they work without ADN_API_KEY.

Live API tools

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:

1. adn_get_guide({ topic: "upload" }) — learn the canonical multi-step flow.
2. adn_create_collection({ title: "My Podcast" })
3. adn_create_upload_session({ collection_id }) — or pass nested track: { file_name } to create the first track in the same call.
4. adn_create_track_in_upload_session({ upload_session_id, file_name: "ep1.mp3" }) (skip if you already nested track above).
5. Your code PUTs the audio bytes to track_upload.upload_url. Create does not upload.
6. 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.
7. adn_list_output_presets() — pick real output indexes (e.g. hq, lq).
8. 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 # vitest npm run smoke # build + spawn the real binary over stdio 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/:

# Terminal 1 — AudioDN API (audiodn-mono)

npm run dev:api # http://127.0.0.1:8787

Terminal 2 — MCP worker (this repo)

cp .dev.vars.example .dev.vars # set ADN_API_KEY to a dashboard API Access key npm run dev:local # http://127.0.0.1:8788 (ADN_API_BASE_URL → local API)

npm run manual:auth # browser consent → writes manual/.env npm run manual # find, create, processing-wait, dry-run, delete

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

Create KV + secrets once:

wrangler kv namespace create MCP_OAUTH

wrangler secret put MCP_JWT_SECRET

wrangler secret put MCP_GRANT_ENCRYPTION_KEY

wrangler secret put MCP_INTERNAL_HMAC

npm run dev:worker