MCP integration guide
The artist.tools MCP server lets compatible AI clients access artist.tools through the Model Context Protocol. It is designed for interactive research, analysis, and workspace tasks where an AI client selects the appropriate tool based on the user's request.
This guide explains how to build a reliable integration without depending on a fixed list of tools or parameters.
MCP or REST API?
Choose the interface that best matches your application.
| Use MCP when | Use the REST API when |
|---|---|
| An AI model needs to choose tools dynamically | Your application follows a fixed request flow |
| Users connect their own artist.tools accounts | Your backend authenticates with an API key |
| The workflow involves interactive research or multiple steps | Your code needs a specific endpoint and response contract |
| You want new tools to become available through runtime discovery | You want direct control over each request |
You can use both interfaces in the same product. They have separate authentication methods, and access remains subject to your artist.tools plan and permissions.
What you need
Before connecting, you need:
- An artist.tools account with access to the tools you plan to use
- An MCP client that supports remote servers over Streamable HTTP
- Support for browser-based OAuth authorization
- The MCP server URL shown in artist.tools
MCP connections do not use API keys. Copy the server URL from Settings > Integrations or the Developer Console instead of constructing or hard-coding it yourself.
How a connection works
- The MCP client connects to the artist.tools server URL.
- The client starts the OAuth authorization flow.
- The user signs in to artist.tools and reviews the requested access.
- artist.tools authorizes the connection for that user and client.
- The client discovers the tools currently available to that connection.
- The client can call those tools within the user's plan, permissions, and rate limits.
The connection represents the artist.tools account that authorized it. A client must not treat one user's authorization as a shared credential for other users.
Connect an existing MCP client
Most compatible clients handle the protocol and OAuth flow automatically:
- Copy the MCP server URL from artist.tools.
- Add it to your client as a remote or HTTP MCP server.
- Complete the artist.tools sign-in and consent flow in your browser.
- Return to the client after authorization.
- Run a simple read-only request to confirm the connection works.
- Check Settings > Integrations to confirm that the client appears as connected.
For client-specific instructions, see Connect artist.tools to an MCP client.
Build a custom MCP client
A custom client should use an MCP SDK that supports Streamable HTTP and OAuth. Avoid implementing the protocol or token flow manually unless necessary.
Your client should:
- Connect to the server URL using Streamable HTTP.
- Follow the OAuth metadata published by the server.
- Open the authorization page in the user's browser.
- Complete the MCP initialization handshake.
- Discover the tools available to the connection.
- pass the current tool descriptions and input schemas to the model.
- Validate each tool call against its current input schema.
- Return tool results to the model using their MCP content types.
- Refresh authorization when supported, or ask the user to reconnect when required.
Do not hard-code OAuth endpoint paths, scopes, token lifetimes, tool counts, or the complete tool catalog. See MCP authentication and OAuth for the current authentication details.
Discover tools at runtime
The tools available to a connection can depend on the account, plan, permissions, and approved access. The catalog may also change as artist.tools adds or updates capabilities.
To keep your integration current:
- Discover tools when establishing or restoring a connection.
- Use each tool's current name, description, and input schema.
- Do not assume that every user has the same tools.
- Do not depend on a fixed tool count or category structure.
- Refresh the tool list when the server reports a change or after reconnecting.
- Handle a missing tool as an availability change, not as a fatal application error.
- Validate arguments against the schema returned by the server.
- Ignore response fields your integration does not understand.
- Prefer structured output when provided, with text content as a fallback.
The live catalog and current access requirements are available in the Developer Console and in MCP tools, access, and rate limits.
Design prompts around outcomes
Let the model choose from the current tool descriptions instead of naming a specific tool in every prompt.
Prefer requests such as:
- "Research this artist and summarize the most relevant signals."
- "Find playlists related to this search and explain the strongest matches."
- "Review this keyword and identify useful opportunities."
- "Save these results to my workspace."
Avoid prompts that encourage exhaustive collection, repeated scanning, or attempts to retrieve every available result. MCP access is intended for legitimate user requests, not bulk export or systematic ingestion.
Handle reads and writes safely
Some tools only retrieve information. Others may create, update, or delete data in the user's artist.tools workspace.
Your client should:
- Clearly distinguish read operations from write operations.
- Show the user what will change before performing a write.
- Require confirmation before destructive or difficult-to-reverse actions.
- Avoid retrying a write automatically unless the operation is known to be safe to repeat.
- Request only the access required for the integration.
- Treat administrator capabilities as separate from normal user access.
- Never infer elevated access from the tool name alone.
The current catalog identifies tools that write or delete data. Availability is still determined by the authorized account and connection.
Store credentials securely
OAuth tokens provide access to the authorizing user's artist.tools account.
- Encrypt tokens at rest and in transit.
- Keep tokens out of logs, prompts, analytics events, URLs, and client-side code.
- Associate each authorization with the correct user and MCP client.
- Do not share tokens between customers, organizations, or environments.
- Remove stored credentials when the user disconnects the integration.
- Reauthorize instead of asking users to copy or expose tokens manually.
Users can review and disconnect clients from Settings > Integrations. Disconnecting stops future access immediately.
Handle limits and failures
Rate limits apply to MCP calls. Your integration should expect calls to be rejected or delayed when limits are reached.
Recommended behavior:
- On
401, refresh authorization if supported. If refreshing fails, ask the user to reconnect. - On
403, explain that the account or connection does not have access. Do not retry automatically. - On
429, reduce request frequency and retry with backoff. - On invalid arguments, refresh the tool definition and correct the request.
- On temporary server failures, use limited exponential backoff.
- Do not repeatedly retry writes or destructive operations.
- Limit parallel calls and avoid launching unnecessary requests speculatively.
Do not hard-code published limits into your application. Check the current limits in the Developer Console or the tools and rate limits guide.
Consider where returned data goes
An MCP client may send artist.tools data to the AI provider that powers the client. Before connecting or building an integration, review that provider's retention, privacy, and model-training settings.
Only request the data needed for the user's task. Do not retain, redistribute, train on, or monetize artist.tools data outside the rights provided by your plan or agreement.
Disconnecting a client prevents future access, but it cannot remove copies already stored by another application or AI provider.
See API Terms & Rules for the current usage requirements.
Verify your integration
Before releasing an integration:
- Complete authorization with a test account.
- Confirm the connection appears under Settings > Integrations.
- Discover the available tools instead of using a saved catalog.
- Complete a read-only request.
- Confirm unavailable tools and permission errors are explained clearly.
- Test expired authorization and reconnection.
- Test rate-limit handling without creating a retry loop.
- Confirm writes require appropriate user approval.
- Disconnect the client and verify that it can no longer access artist.tools.
Troubleshooting
The browser authorization flow does not open
Confirm that the client supports remote MCP servers and browser-based OAuth. Older clients may only support local MCP servers.
The connection succeeds but tools are unavailable
Tool access depends on the authorizing account, plan, and permissions. Check the Developer Console for the tools available to that account.
A previously available tool is missing
Refresh the tool list and current schemas. Do not continue using a cached tool definition after the server reports that it is unavailable.
A tool rejects its arguments
Compare the request with the latest input schema returned by the server. Tool parameters may differ from an older cached definition.
The client receives a 401
401Refresh the authorization if the client supports it. Otherwise, disconnect and authorize the client again.
The client receives a 429
429Reduce concurrency and request frequency, then retry with backoff. Avoid immediately repeating the same group of calls.
A write or administrator action is unavailable
Confirm that the account has the required permission and that the connection was authorized for that access. Normal authorization does not automatically include administrator capabilities.