Connect over MCP

This page covers connecting a Model Context Protocol (MCP) client to Starcovery, the credentials it accepts, and how its tools spend credits. Starcovery exposes a Streamable HTTP MCP endpoint:

https://www.starcovery.com/api/mcp

Use an agent access token from agent signup, a Settings API key, or OAuth when your client supports it. initialize and tools/list work without a credential. search_creators and enrich_creators also work without one. Other tools need a credential. A tools/call of another tool without a credential answers HTTP 401 with a WWW-Authenticate header whose resource_metadata points at https://www.starcovery.com/.well-known/oauth-protected-resource/api/mcp, the document an OAuth host reads to start sign-in.

An unsigned search_creators call spends one use of the unsigned grant of 100 uses per rolling 24 hours per IP. Unsigned REST search spends the same grant.

Every credential resolves to one organization for the length of the request. That organization's prepaid credits fund any credit spend. MCP OAuth access tokens and the /api/auth/oauth2/userinfo response include an organization_id claim.

Authorization embeds the organization that is active at consent time, or the caller's first organization when none is active. An issued token stays bound to that organization. Changing the session's active organization does not move an existing token.

To bind a different organization, authorize again and replace the token. When you authorize, pick the organization under Give access to on the consent screen, or switch the active organization from the Organizations menu in the app sidebar first.

With a credential, each new search that search_creators, generate_campaign_matches, or a thread_turn runs spends one use of the identified grant of 200 uses per rolling 24 hours per user, then 1 prepaid credit from the organization credit ledger. Each thread_turn also costs 1 use of its own before it runs, so a turn costs 1 plus each search it runs; a turn that fails gets its use back. A pre-claim agent token skips the daily grant and spends prepaid credits only.

A repeat of a brief and filters that the organization already searched spends nothing while that search stays in its search history. A repeat spends like a new search when the brief contains exclude, excluding, except, or without, or asks for real people, indie creators, or individual creators.

A thread_turn that leaves a kind of creator out of the creators on screen runs the exclusion judge over them and spends like a new search every time. Narrowing them on followers, average views, engagement, platform, country, or verified status spends nothing.

When a search needs a credit and the organization has no prepaid credits left, each tool reports it:

• search_creators and generate_campaign_matches return an out of credits error.
• thread_turn reports the condition in exhausted, with empty creators, when no search or exclusion in the turn has succeeded or when the first search for a new brief's creators needs a credit.
• thread_turn answers with the brief, filters, reply, and creators built from the steps that succeeded when a search or exclusion in the turn already succeeded, and exhausted is null.

See Credits and payments.

Over MCP you can inspect the current identity and credit source, search creators from a brief, enrich the shortlist (niche, celebrity, evidence, signal), reveal a contact address, run a search thread turn, intersect two creator lists, save, list, read, and delete Lists, list, read, create, update, delete, and export campaigns, generate, add, and remove matches, list and delete campaign attachments, request a proposal send or campaign funding, read the credit balance, and list, create, and revoke API keys. Search, generate, enrich, and thread turns hold the call open until the result, and the api ends a request at 800 seconds.

The web, REST, and the CLI run the same operations, except Lists, which only the web and MCP have, and campaign attachments, which the CLI does not have. An agent access token or an OAuth access token cannot manage API keys.

Search threads and ListsCopy Anchor Link

thread_turn runs one turn of a search thread and answers the settled brief, its filters, the operations the turn ran, the reply, and the creators of the thread result set in creators, with a shortlist ticket. Omit threadId to open a thread; the threadId in the result is the durable handle to pass back on the next turn. A pasted website address is read into a brief; anything else refines the creators on screen: a message that narrows returns a subset of them, a message that asks for more combines a new search with them, and only a message that replaces the search starts over. A question about the organization's campaigns, Lists, credits, or API keys is answered from read tools, and the turn changes none of them.

A refinement returns the set it built; the first brief runs one search for its creators, billed like search_creators. The thread stores the set, so GET /api/threads/{threadId}/results reads it again for free. When the read of the thread's creators fails after the turn ran, thread_turn answers a tool error with two texts: internal, then the turn without creators and ticket, its threadId included. MCP cannot stream a tool result, so the call is blocking and sends notifications/progress when the host passes a progressToken.

intersect_lists keeps the creators that appear in both lists, in the order of the left list, and stores nothing. save_list saves a set of creators as a List for the organization, with the brief and filters of the search that produced it. list_lists lists the organization's Lists, get_list reads one List with its saved creators, and delete_list deletes one List; campaigns keep the creators added from it. These tools need a credential.

list_campaigns and get_campaign return nextStep on each campaign of the organization: the step the web app shows next, with its id, its label, the actor who takes it (you for the organization, starcovery, creators, or one creator by name), and the line that says what it waits on. It is null once no step is left and on a campaign another organization owns. get_campaign also returns currentSteps, every step under way in campaign order, in the same shape, because a step before nextStep can still wait, such as proposals Starcovery has not sent yet.

add_campaign_matches adds several creators to a campaign in one call and answers how many it added and how many were already on the campaign. create_campaign takes the same optional creators and adds them as matches of the new campaign. The creators that get_list returns carry the saved creator shape these tools take.

Map a search_creators result to the saved creator shape before you call save_list: profileId is the creator id, and fitScore, followerCount, name, platform, profileImageUrl, and username keep their names and values.

Get a credentialCopy Anchor Link

npx starcovery auth register

That runs the auth.md signup protocol and saves an agent access token as apiKey in ~/.config/starcovery/config.json. The CLI prints the config path and the claim endpoint, never the raw token. It then installs the host skill with bunx skills when bun is on PATH, otherwise npx -y skills, for Cursor, Claude Code, and Codex.

An agent access token lasts 24 hours. When it expires, the CLI exchanges the saved assertion for a new token, which retires the old one, so a copy pasted into an MCP host stops working within a day. For a long-lived MCP host, use OAuth, or have a human mint a Settings API key in Settings > API Keys.

Claude Desktop does not load filesystem skills. Download skill.zip and upload it at Customize > Skills with code execution on. MCP is a separate connector below.

Claude CodeCopy Anchor Link

claude mcp add --transport http starcovery https://www.starcovery.com/api/mcp

Open /mcp in Claude Code and complete browser sign-in. To use a Settings API key instead:

claude mcp add --transport http starcovery https://www.starcovery.com/api/mcp --header "Authorization: Bearer <api_key>"

Claude DesktopCopy Anchor Link

OAuth is preferred when the host can open a browser. Open Settings > Connectors > Add custom connector and enter these fields:

• Name: Starcovery
• URL: https://www.starcovery.com/api/mcp
• Auth: OAuth, then sign in when prompted

To use a bearer token instead, open Settings > Connectors > Add custom connector and enter these fields:

• Name: Starcovery
• URL: https://www.starcovery.com/api/mcp
• Header: Authorization: Bearer <access_token>

CursorCopy Anchor Link

Cursor connects with a Settings API key in a header. Add Starcovery to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "starcovery": {
      "url": "https://www.starcovery.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

Cursor's OAuth sign-in does not connect to Starcovery. Cursor's client registration includes the callback cursor://anysphere.cursor-mcp/oauth/callback, and the registration endpoint refuses that callback with 400 invalid_redirect_uri before sign-in starts.

Other HTTP MCP hostsCopy Anchor Link

Add a custom MCP server:

• URL: https://www.starcovery.com/api/mcp
• Auth: Bearer <access_token>, or OAuth when the host offers it

A host that registers its own OAuth client posts to the registration_endpoint in /.well-known/oauth-authorization-server. A host whose callback is a loopback address, such as http://127.0.0.1:<port>/callback or http://localhost:<port>/callback, registers with "application_type": "native". A registration without application_type is a web client, which needs an https callback on a host that is not loopback; any other callback answers 400 invalid_redirect_uri.

Example promptCopy Anchor Link

Ask your agent to read these docs, install the host skill if needed, register if needed, then search:

Find 15 nano creators who film quiet morning coffee at home on Instagram or TikTok. Reveal a contact only when you need to write them. Save the shortlist to a campaign named Coffee.

Web app and API reference questionsCopy Anchor Link

Do I need the web?Copy Anchor Link

No. MCP, REST, and the CLI cover search, thread turns, shortlist enrichment, contact reveal, campaigns, and credits. MCP also intersects, saves, reads, and deletes Lists. API key management needs a browser session or a Settings API key; an agent access token or an OAuth access token gets 403.

Humans use the web for account settings and credit packs. Search, generate, enrich, and thread turns hold the connection open until the result is ready.

Where is the API described?Copy Anchor Link

openapi.json documents the REST surface, and the API reference renders it with a playground. MCP describes itself: call tools/list on the endpoint, or read the server card.