MCP Server

AI assistants that speak the Model Context Protocol (MCP) can search your libraries directly and look after them. Claude, ChatGPT, Cursor and other clients that support remote MCP servers connect to one URL, ask you to sign in once, and then call Spondulix themselves when you ask them for music or about a library.

The server URL is:

https://app.spondulix.ai/mcp

Nothing needs to be set up on the Spondulix side first. Any user with a library can connect.

What the assistant can do

The server exposes thirteen tools, grouped into three permissions that you approve when connecting.

Tool Permission What it does
list_libraries Read the catalog The libraries your account can see
library_status Read the catalog How ready a library is: the setup steps done and to do, what it holds, lyric embedding progress, and what its prompt gets wrong
describe_library Read the catalog A library’s built-in fields, custom metadata types and tag values, plus a hint on building filters
get_track Read the catalog One track with its metadata, composers and publishers
find_tracks Read the catalog A plain lookup by words in a title, description, lyrics, tags or credits, with no model call and at no cost
list_searches Read the catalog The searches run against a library from any client, newest first
get_search Read the catalog A search already run, with its ranked tracks, without running it again
explain_search Read the catalog Why a search found what it found: the model’s reading of the request and how many tracks each clause of the filter matches on its own
get_prompt Read the catalog A library’s prompt, its tag types, its examples and its lint findings
search_tracks Run searches A plain-language search, optionally with a structured filter, boost or sort, returning the top tracks with scores
continue_search Run searches Refine a previous search in conversation, for example “the same but slower”
save_search_as_example Change the catalog Keep a search you approved of as a worked example for the prompt it ran with
update_prompt Change the catalog Give a prompt new text, as a new version; the old one is kept

Each search runs through the library’s configured AI provider, costs the same as a search on the site, and appears in the library’s search history with the source mcp. Tracks are read through an assistant, never changed. Administering a library, its settings, keys and membership, is never offered to an assistant; that is done on the site or through the API.

An assistant that connects without asking for particular permissions gets the first two, reading and searching. Changing prompts and examples has to be asked for.

Connecting

  1. Add the server to your assistant. In claude.ai open Settings, then Connectors, and choose “Add custom connector”. In Claude Code run:

    claude mcp add --transport http spondulix https://app.spondulix.ai/mcp

    Other clients that support OAuth-protected remote servers take the same URL.

  2. Sign in and approve. The assistant opens a browser window. Sign in with your Spondulix account, review the permissions it asks for and click Allow. The window closes and the assistant is connected.

  3. Ask in plain language. “What libraries do I have?”, “Find upbeat instrumental tracks under two minutes in Frivolous Music”, “More like that but with female vocals”, “Is my library set up?”, “Why did that search find nothing?”. The assistant calls the tools itself.

Disconnecting

Open your account page and click Disconnect next to the application. That revokes its tokens; the assistant will have to sign in again to reconnect.

Clients without OAuth

A client that can only send a fixed header can use the API token from your account page instead. It grants all three permissions:

claude mcp add --transport http spondulix https://app.spondulix.ai/mcp \
  --header "Authorization: Bearer your-api-token-here"

Technical notes

  • The endpoint is stateless Streamable HTTP at POST /mcp.
  • Spondulix is its own OAuth 2.1 authorization server. Discovery documents are at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server.
  • Clients register dynamically at POST /oauth/register (RFC 7591) or identify themselves with a Client ID Metadata Document URL. PKCE is required. A token is issued for one resource: one for the MCP URL is refused by the REST API, which takes tokens of its own.
  • Access tokens last an hour and come with refresh tokens.