MCP Server (Beta)

The Epidemic Sound MCP Server gives AI clients and agents access to Epidemic Sound music, sound effects, track adaptation and voiceovers through the Model Context Protocol. It runs at https://epidemic.visionseotools.com/a/mcp-service/mcp.

The MCP Server doesn't use the Epidemic Sound API

You don't need a Developer Portal account. You connect with your Epidemic Sound account, or with an MCP Server API key from Account → API keys. The Epidemic Sound API uses its own API key from the Developer Portal, and each key only works with its own product.

The MCP Server works with your own Epidemic Sound subscription. To build music into a product for your own users, use the Epidemic Sound API.

Connect

Ways to connect

	Claude directory connector	Custom connector with OAuth (account sign-in)	MCP Server API key
Works in	Claude.ai, Claude Desktop, Claude Mobile, Claude Code, Claude Cowork	Established MCP clients, such as Claude, ChatGPT and Cursor	Any MCP client that can send an `Authorization` header
Setup	Add Epidemic Sound from its listing in Claude's directory	Add the server URL in your client and sign in with your Epidemic Sound account	Create a key under Account → API keys and send it as a bearer token
MCP Tools	All tools except the voiceover tools, which Claude's directory doesn't allow. See Known limitations	All tools. `PollEditRecordingJob` may not be available on all connections. See Known limitations	All tools

A directory connector you add in Claude.ai also appears in Claude Code, still without the voiceover tools. For the full tool set, add the server URL directly.

OAuth

The MCP Server uses OAuth Dynamic Client Registration, as described in the MCP spec. Your client opens a browser window where you sign in with your Epidemic Sound account. Log in at www.epidemicsound.com first.

OAuth is limited to vetted MCP clients

To protect our users from phishing attacks, OAuth only works with a fixed allowlist of redirect URIs belonging to established MCP clients (such as Claude, ChatGPT and Cursor). Epidemic Sound does not add redirect URIs to this allowlist on request, including for your own applications, and does not issue OAuth client IDs for the MCP server.

If you're building your own application or integration on top of the MCP server, use an MCP Server API key instead.

This also applies if you're building an MCP client for other people to use. An MCP Server API key is tied to a single Epidemic Sound account, and only the account holder can create one. You can't generate keys on behalf of the people using your client, and you must not share your own key with them. Instead, each person needs their own Epidemic Sound account, creates a key under Account → API keys, and enters it in your client.

MCP Server API key

Create a key under Account → API keys. The key is tied to your Epidemic Sound account and is valid for one year. To rotate it, create a new key on the same page.

Send the key in the Authorization header of every request:

Authorization: Bearer YOUR_MCP_SERVER_API_KEY

Keep the key in an environment variable rather than in code or configuration files:

export EPIDEMIC_SOUND_MCP_API_KEY="your_mcp_server_api_key_here"

Never expose your MCP Server API key to a browser

An MCP Server API key is a long-lived credential tied to your account, so it must never be shipped to an untrusted client. Local MCP clients running on your own machine (Claude Code, Cursor) are fine — a web page is not, since anyone visiting it can read the key.

If you're building a web app, the key stays on your server and all requests are proxied through your own backend. Calling the MCP server directly from browser JavaScript is not a supported setup.

Set up your client

Claude

Claude Desktop

Claude Desktop connects with OAuth, so no MCP Server API key is needed. Make sure you are logged in to www.epidemicsound.com first.

To skip the steps below, open the pre-filled custom connector dialog in Claude.

Open Claude Desktop → Settings → Connectors
Click Add custom connector
Name it (e.g. Epidemic Sound) and paste the URL: https://epidemic.visionseotools.com/a/mcp-service/mcp
Click Add. Claude opens a browser window to sign in
Log in with your Epidemic Sound account and approve access

Claude Code

Claude Code doesn't support OAuth to the MCP Server yet, so it connects with an MCP Server API key.

Create a key under Account → API keys and export it:

export EPIDEMIC_SOUND_MCP_API_KEY="your_mcp_server_api_key_here"

claude mcp add -s user --transport http epidemic-sound https://epidemic.visionseotools.com/a/mcp-service/mcp \
  --header 'Authorization: Bearer ${EPIDEMIC_SOUND_MCP_API_KEY}'

Use single quotes so your shell leaves ${EPIDEMIC_SOUND_MCP_API_KEY} untouched. Claude Code expands it when it reads the configuration, so the key is never written to the file.

Verify the connection:

claude mcp list

epidemic-sound should report ✔ Connected. If it reports ✘ Failed to connect, check that EPIDEMIC_SOUND_MCP_API_KEY is exported and non-empty in the shell you launched Claude Code from. To keep the variable across sessions, add the export line to your shell profile (e.g. ~/.zshrc).

When you rotate the key, update EPIDEMIC_SOUND_MCP_API_KEY. The MCP configuration doesn't change.

To remove the server:

claude mcp remove epidemic-sound -s user

ChatGPT

ChatGPT connects with OAuth. Make sure you are logged in to www.epidemicsound.com first.

Open your ChatGPT plugins, click Add and select Add custom MCP Server
Name it Epidemic Sound and paste the URL into the Connector field: https://epidemic.visionseotools.com/a/mcp-service/mcp
Log in with your Epidemic Sound account when prompted

Cursor

Cursor supports both OAuth and MCP Server API keys. Go to Settings → MCP and click New MCP server to open mcp.json.

To connect with OAuth (recommended), add:

{
  "mcpServers": {
    "epidemic-sound": {
      "url": "https://epidemic.visionseotools.com/a/mcp-service/mcp"
    }
  }
}

Then click Connect in the MCP settings tab and sign in with your Epidemic Sound account in the browser tab that opens.

To connect with an MCP Server API key, add the key as a header instead:

{
  "mcpServers": {
    "epidemic-sound": {
      "url": "https://epidemic.visionseotools.com/a/mcp-service/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_SERVER_API_KEY"
      }
    }
  }
}

Once connected, the toggle next to the server name is active and you can use the tools from Cursor prompts.

Other MCP clients

Any client that supports MCP over Streamable HTTP and can send an Authorization header connects with an MCP Server API key. If you're writing your own client, an MCP SDK such as the TypeScript SDK handles the transport and session for you.

To call the server directly, send JSON-RPC requests as POST to the server URL. Responses arrive as server-sent events. Start with initialize:

curl -i -X POST 'https://epidemic.visionseotools.com/a/mcp-service/mcp' \
  -H "Authorization: Bearer $EPIDEMIC_SOUND_MCP_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

The response carries an Mcp-Session-Id header. Send it on every later request, starting with the notifications/initialized notification, then list the tools:

curl -X POST 'https://epidemic.visionseotools.com/a/mcp-service/mcp' \
  -H "Authorization: Bearer $EPIDEMIC_SOUND_MCP_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authentication errors

A request without a valid credential gets 401 Unauthorized, with a WWW-Authenticate header that points to the server's OAuth metadata:

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://epidemic.visionseotools.com/.well-known/oauth-protected-resource"

Clients that support OAuth use this header to find where to sign in, as described in the MCP authorization spec. The response doesn't say why the credential was rejected. If you get a 401 with an MCP Server API key, check that your client sends the Authorization header, that the key came from Account → API keys rather than the Developer Portal, and that it was created less than a year ago.

Tools

The tool names below are the literal identifiers returned by the MCP server's tools/list and required for direct JSON-RPC calls. tools/list also returns each tool's description and parameters, including the search filters (genre, mood, BPM, key and more). MCP clients read them and fill in the parameters from your prompt.

Area	Tools
Music discovery	`SearchRecordings`, `SearchSimilarToRecording`, `SearchExternalReferences`
Sound effects	`SearchSoundEffects`, `SearchSimilarToSoundEffect`
Track adaptation (beta)	`EditRecording`, `PollEditRecordingJob`, `DownloadRecordingEdit`
Voiceovers	`ListVoices`, `ListUserGeneratedVoices`, `GenerateVoiceover`, `PollVoiceoverGenerationStatus`, `GetVoiceover`, `DownloadVoiceover`
Downloads	`DownloadRecording`, `DownloadSoundEffect`

Workflows

These tasks take more than one tool call.

Find music like a reference track

Call SearchExternalReferences with an artist or song name (e.g. "Taylor Swift") to get Spotify track IDs
Pass one of them to SearchRecordings as externalID to find catalog tracks in that style

Cut a track to length

Pick a track with SearchRecordings
Call EditRecording with the recording ID and a target duration of up to 5 minutes. To land a section at an exact time, pin it with requiredRegionsAtOffsets
Poll PollEditRecordingJob until status is COMPLETED (or FAILED)
Download the result with DownloadRecordingEdit, using the job ID and the edit ID returned by the poll call

Example: An AI agent needs a 47-second track for a product video, with the energetic chorus landing at the 15-second mark.

Before you build on track adaptation, check the known limitations.

Create a voiceover

Pick a voice with ListVoices, or one of your own voice replicas with ListUserGeneratedVoices
Call GenerateVoiceover with the voice ID and your script. The optional language code must be one of the codes in the voice's languages list, for example en, de or es-ES. Leave it out to use the voice's default language
Poll PollVoiceoverGenerationStatus until the status is DONE (or FAILED)
Download the file with DownloadVoiceover, or get the playback URL and metadata with GetVoiceover

Known limitations

Limitation	What to do
The Claude directory connector doesn't include the voiceover tools, because Claude's directory doesn't allow them.	Add Epidemic Sound as a custom connector with the server URL.
Claude Code doesn't support OAuth yet.	Connect with an MCP Server API key.
`PollEditRecordingJob` may not be available on all connections (e.g. OAuth). Without it, you can't get the edit ID that `DownloadRecordingEdit` needs.	Use an MCP Server API key for track adaptation.
Only one edit is retrievable per job, whatever `maxResults` is set to.	—
Edits are a single full mix, whatever `skipStems` is set to.	Download stems from the original track with `DownloadRecording`.
Edits are capped at 5 minutes (`targetDurationMs` up to 300,000).	—
A `401` doesn't say why the credential was rejected.	See Authentication errors.
Browser JavaScript can't call the MCP server.	Keep the key on your server and proxy requests through your backend.
Rate limits aren't published.	If you need higher limits, ask through the Help Center.

Plans, terms and support

What you can do depends on your Epidemic Sound subscription. A free account can search and preview. Downloading needs an active paid subscription.

The MCP Server Software License Agreement covers your use of the MCP Server. Music and sound effects are licensed through your Epidemic Sound subscription.

For questions about your account, plan or the MCP Server, visit the Help Center.

Connect​

Ways to connect​

OAuth​

MCP Server API key​

Set up your client​

Claude​

Claude Desktop​

Claude Code​

ChatGPT​

Cursor​

Other MCP clients​

Authentication errors​

Tools​

Workflows​

Find music like a reference track​

Cut a track to length​

Create a voiceover​

Known limitations​

Plans, terms and support​