MCP integration guide
The artist.tools MCP server lets compatible AI clients work with an artist.tools account through the Model Context Protocol. It is designed for interactive research and workspace tasks where an AI client selects tools 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 to discover new tools at runtime | You want direct control over each request |
These are separate interfaces with separate authentication and limits. MCP access follows the connected user's artist.tools plan. The REST API requires Developer Access and an API key.
What you need
Before connecting, you need:
- An artist.tools account
- An MCP client that supports remote servers over Streamable HTTP
- Support for browser-based OAuth authorization
- The MCP server URL shown in artist.tools
Any account can connect an MCP client, although the tools it can run depend on its plan. MCP connections do not use API keys. Copy the server URL from Settings > Integrations instead of constructing or hard-coding it yourself. It is also shown in the Developer Console for accounts with access to that page.
How a connection works
- The MCP client connects to the artist.tools server URL.
- The client follows the server's OAuth discovery information and opens the 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 tool catalog.
- Each tool call is checked against the user's current 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. Changing plans does not require reconnecting: access is checked again on the next tool call.
Connect an existing MCP client
Most compatible clients handle the protocol and OAuth flow automatically:
- Copy the MCP server URL from Settings > Integrations.
- 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.
- Ask it to run
who_am_ito confirm the connected account and plan. This works on every plan. - Check Settings > Integrations to confirm that the client appears as connected.
For setup guidance, see Connect artist.tools to an MCP client.
Build a custom MCP client
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. Do not assume dynamic client registration is the only supported way to identify a client.
- Open the authorization page in the user's browser.
- Complete the MCP initialization handshake.
- Discover the current tool catalog.
- Pass the current tool descriptions and input schemas to the model.
- Validate tool arguments against the schemas returned by the server.
- 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, token lifetimes, tool counts, or the complete tool catalog. See MCP authentication and OAuth for authentication details.
Understand tool access
All authenticated accounts can discover the ordinary tool catalog. A listed tool is not necessarily executable on the connected account's plan. Each tool description states its minimum plan, and the server checks the account's current plan when the tool is called.
In broad terms:
- Free: Account context, documentation search, and access to the user's saved dashboard entities, entity folders, and notes. Free users can make permitted changes within existing folders.
- Artist Access: Adds entity resolution and detail, playlist search, track credits, artist discography, playlist Discovered On, and entity-folder creation.
- Industry Access: Adds the remaining ordinary research, keyword, SEO, Press Mentions, rankings, activity, and keyword-workspace tools.
- Developer Access: Has the same ordinary tools as Industry Access, with higher MCP rate limits.
Administrator tools are separate: their names are not advertised to ordinary connections. They require a current administrator account and an MCP connection explicitly approved for administrator access.
For the current tool-by-tool requirements and limits, see MCP tools, access, and rate limits.
Discover tools at runtime
The catalog can change as artist.tools adds or updates capabilities. Plan-restricted ordinary tools remain discoverable so an agent can explain what is available with an upgrade; do not interpret their presence in tools/list as permission to execute them.
To keep your integration current:
- Discover tools when establishing or restoring a connection.
- Use each tool's current name, description, annotations, and input schema.
- Do not depend on a fixed tool count or category structure.
- Use
who_am_iwhen you need to confirm the connected account, current plan, and callable tools. - Handle
plan_requiredas an access decision, not a failed OAuth connection. Its response identifies the required plan and provides an upgrade URL; do not retry it automatically. - Refresh the tool list when reconnecting or when the server reports a catalog change.
- Validate arguments against the schema returned by the server.
- Prefer structured output when provided, with the JSON text content as a fallback.
The current catalog is also available from the artist.tools integration UI.
Design prompts around outcomes
Let the model choose from the current tool descriptions instead of naming a specific tool in every prompt.
Examples:
- "Show me the artists and playlists saved in my dashboard folders."
- "Find playlists related to this search and explain the strongest matches."
- "Research this artist and summarize the most relevant signals."
- "Review this keyword and identify useful opportunities."
- "Save these results to my workspace."
The first example works with a Free account's saved data. Other requests require the appropriate plan. If a requested tool is restricted, explain the required plan rather than repeatedly calling it.
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 retrieve information. Others can create, update, or delete data in the user's artist.tools workspace.
Your client should:
- Clearly distinguish reads from writes using the current tool descriptions and annotations.
- Show the user what will change before performing a write.
- Require user confirmation before destructive or difficult-to-reverse actions.
- Avoid automatically retrying writes unless the operation is known to be safe to repeat.
- Treat administrator capabilities as separate from ordinary account access.
- Never infer elevated access from a tool name alone.
The server still enforces plan access and workspace ownership. Client-side confirmation is an additional user-experience safeguard, not a replacement for those checks.
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 where possible.
- 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 prevents future access, including refresh-token use.
Handle limits and failures
MCP limits are keyed to the artist.tools account, not to an individual OAuth connection. Opening another connection does not provide a separate allowance. Limits vary by plan and tool; Developer Access has higher MCP limits, not additional ordinary tools.
For a tool call, inspect the MCP result's isError flag and structured error content. Do not rely solely on the HTTP status of the Streamable HTTP request:
plan_required: Tell the user which plan the tool requires. The OAuth connection remains active; do not retry until the plan changes.rate_limit_exceededorconcurrency_limit_exceeded: HonorretryAfterSeconds, reduce request frequency or concurrency, and retry with exponential backoff and jitter.invalid_arguments: Correct the indicated fields using the current input schema.admin_requiredoradmin_connection_required: Do not retry as an ordinary connection. Administrator access requires the appropriate account and approval.- Temporary tool failures: Use limited backoff. Do not repeatedly retry writes or destructive operations.
An HTTP 401 during transport or OAuth indicates an authentication problem: refresh authorization if supported, or ask the user to reconnect. HTTP 429 can also occur before a tool call is handled, such as for OAuth or transport abuse; back off rather than immediately repeating the request.
Do not hard-code published rate values into your application. Respect the retry information returned with a failure and limit unnecessary parallel calls. See MCP tools, access, and rate limits for the current policy.
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. The separate Developer API Terms & Rules describe REST API use; do not assume that an API key or REST API permission is part of an MCP connection.
Verify your integration
Before releasing an integration:
- Complete authorization with a test account and confirm the connection under Settings > Integrations.
- Run
who_am_iand verify the expected account and plan. - Discover the catalog rather than using a saved list.
- Verify that a permitted read succeeds and a plan-restricted call returns
plan_requiredwithout disconnecting the client. - Test an upgrade or downgrade without reconnecting.
- Test expired authorization and refresh or reconnection.
- Test tool-level 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 over Streamable HTTP and browser-based OAuth. Older clients may only support local MCP servers.
The connection succeeds, but a tool says a plan is required
The connection is working. Ordinary tools remain visible even when the account's plan cannot run them. Read the plan_required response for the specific required plan. An upgrade takes effect on a later call without reconnecting.
The client is connected to the wrong artist.tools account
Run who_am_i to confirm the account. If it is wrong, disconnect that client under Settings > Integrations and authorize it again while signed in to the intended account.
A previously available tool is missing
Refresh the tool list and current schemas. Administrator tools are only listed on connections approved for administrator access; ordinary plan restrictions do not hide tool names.
A tool rejects its arguments
Compare the request with the latest input schema returned by the server. Correct the listed fields rather than repeating the same call.
The client receives an HTTP 401
401Refresh authorization if supported. If that fails, disconnect and authorize the client again.
A tool reports a rate or concurrency limit
Read retryAfterSeconds, wait at least that long, reduce parallel calls, and retry with backoff and jitter. Do not immediately repeat the same group of requests.
A write or administrator action is unavailable
Check the tool's minimum plan and the user's workspace permissions. Administrator actions also require a current administrator account and explicit approval on that MCP connection.