Model Context Protocol

Give your AI an ear for music.

Search artists, inspect releases, follow musical threads and manage your playlists without leaving Codex, Claude Code, or another MCP client.

Connect a clientCreate an API token

Streamable HTTP endpoint

https://mcp.raygum.com/mcp
01

Access

Start public. Add a token when you need it.

Catalogue tools are open to every client. A personal token adds private playlist access and permission to make changes on your behalf.

No account needed

Public catalogue

Search music, read public data, inspect tracklists and get recommendations with only the endpoint.

Personal token

Your playlists

Use a client that can send a Bearer header to read private playlists and create, edit or delete your own lists.

Need account access?

Create a token and copy it immediately. Raygum only stores its hash, so it cannot be shown again.

Open API tokens
02

Connect

Choose your client.

These recipes use an environment variable to keep your token out of project files. Omit the authentication lines if you only want public catalogue access.

OpenAI

Codex

Codex CLI, the IDE extension and the desktop app share this configuration. Restart the client, then use /mcp to check it.

Shellready to paste
export RAYGUM_MCP_TOKEN='rg_mcp_your_token_here'
~/.codex/config.tomlready to paste
[mcp_servers.raygum]
url = "https://mcp.raygum.com/mcp"
bearer_token_env_var = "RAYGUM_MCP_TOKEN"
Codex MCP documentation

Anthropic

Claude Code

Claude Code supports remote HTTP servers and custom headers. Confirm the connection with claude mcp list or /mcp.

Shellready to paste
export RAYGUM_MCP_TOKEN='rg_mcp_your_token_here'

claude mcp add-json --scope user raygum \
  '{"type":"http","url":"https://mcp.raygum.com/mcp","headers":{"Authorization":"Bearer ${RAYGUM_MCP_TOKEN}"}}'
Claude Code MCP documentation

Hosted connector

Claude and Claude Desktop

Go to Customize → Connectors, choose Add custom connector, and enter the endpoint. This provides public catalogue access.

Hosted custom connectors cannot send a Raygum personal token. Use Claude Code or Codex for private playlists while Raygum OAuth support is being developed.
Claude connector documentation

Streamable HTTP

Other MCP clients

Some clients call this transport http. Add the Authorization header only when your client can store it securely.

MCP configurationready to paste
{
  "mcpServers": {
    "raygum": {
      "type": "streamable-http",
      "url": "https://mcp.raygum.com/mcp",
      "headers": {
        "Authorization": "Bearer rg_mcp_your_token_here"
      }
    }
  }
}
03

Try it

Ask for music in plain English.

Once the server is connected, your assistant chooses the right Raygum tool for the job.

“Search Raygum for albums by Radiohead.”

“Show me the tracklist and genres for OK Computer.”

“Find releases similar to Kid A.”

“Recommend five jazz releases from the catalogue.”

“Create a private playlist called Late Night.”

Token required

“Add these tracks to my Late Night playlist.”

Token required
04

Tools

Fourteen ways into Raygum.

Eight tools explore the public catalogue. Six authenticated tools work with playlists owned by your account.

Catalogue and discovery

8 public tools

search_releases

Search albums, EPs, and singles by title or artist.

search_artists

Search artists by name.

search_tracks

Search tracks by title or artist.

get_release

Get release metadata, genres, artwork, and the full tracklist.

get_artist

Get an artist biography, genres, artwork, and discography.

get_playlist

Read a public playlist, or a private playlist you own.

get_similar_releases

Find releases with related genres and characteristics.

get_recommendations

Get catalogue recommendations, optionally by genre.

Playlist management

6 personal tools

create_playlist

Create a playlist in your Raygum account.

update_playlist

Change a playlist title, description, or visibility.

add_tracks_to_playlist

Add one or more Raygum tracks to a playlist.

remove_tracks_from_playlist

Remove tracks from one of your playlists.

delete_playlist

Delete a playlist you own.

list_my_playlists

List playlists owned by your account.

05

Reference

Limits and security.

Rate limits

Limits apply per user. Public catalogue traffic shares the anonymous allowance.

OperationPer minute
Search100
Entity retrieval200
Recommendations30
Playlist changes20

Token safety

  • Raygum stores a SHA-256 hash, never the raw token.
  • Private playlists and changes are restricted to their owner.
  • Tokens can be revoked at any time from Settings.
  • Never commit a token or paste one into shared configuration.
06

Troubleshooting

Connected, but not quite working?

Playlist tools fail

Check that your client sends Authorization: Bearer … and that the token begins with rg_mcp_. Create a replacement if it was revoked or lost.

Test the public connection

Ask the official MCP Inspector.

This command connects without a token and asks Raygum to list its tools.

Shellready to paste
npx -y @modelcontextprotocol/inspector@latest --cli \
  https://mcp.raygum.com/mcp --transport http --method tools/list

Still stuck?

Send the client name and connection error—never your token.

Send feedback