Skip to Content
Skip to Content
Starcovery

Call a creator database over MCP

By Starcovery. Updated .

Connect a Streamable HTTP MCP client to Starcovery by bearer token or OAuth to search and enrich creators, reveal contacts, run campaigns, and read credits.

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 OAuth when your client supports it, or a Settings API key. See Authentication. initialize and tools/list work without a credential. search_creators, enrich_creators, thread_turn, send_feedback, and request_hand_pick also work without one, as search, threads, feedback, and hand-pick requests do on the web or REST without signing in. get_creator, list_published_searches, and get_published_search work without one too, as creator pages and published searches do on the web, and get_creator then shows the contact as locked. Other tools act on an organization or an account and 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.

Without a credential, each IP address gets 100 uses per UTC day, the same allowance that signed-out search and threads on the web and REST draw on, so everyone behind one IP address shares it. A search_creators call spends one use, and a thread_turn spends one use plus one for each new search and each exclusion it runs. A thread_turn without threadId opens a thread, and one IP address opens at most 100 threads per 24 hours. A thread opened without a credential lasts 30 days, and its result holds threadKey beside threadId. The next turn of that thread passes both, and any caller without a credential that holds both continues it, so keep the threadKey to yourself. A turn without a credential answers no question about campaigns, Lists, credits, or API keys. send_feedback and request_hand_pick share 5 calls per hour per IP address, and request_hand_pick without a credential takes email, the address the team replies to.

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.

An OAuth access token lasts one hour, and it stops working sooner when the browser session that approved it signs out or expires. A host that holds the Stay signed in permission (offline_access) gets a new access token from its refresh token, which survives the sign-out, and keeps working. A host without that permission stops working until you authorize it again.

An access token works only at the endpoint it was issued for. MCP hosts ask for https://www.starcovery.com/api/mcp, and a token issued for the REST API, https://www.starcovery.com/api/, gets the HTTP 401 challenge at the MCP endpoint.

A password change or reset removes no host you authorized. A reset signs you out of every browser, so each host's current access token stops working as described above, and a host with Stay signed in keeps working through its refresh token.

To end every host you approved, in every organization, open Settings > Account and choose Remove All Agents. Each host loses access within an hour and works again only after you authorize it again.

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 UTC day per user, then 1 prepaid credit from the organization credit ledger. The members of one organization share at most 200 daily uses between them, so a use past that also spends a prepaid credit. Each thread_turn also costs 1 use of its own before it runs, so a turn costs 1 plus each new search and each exclusion it runs. A turn that fails gets its use back, and so does a turn whose website read or brief draft times out, fails with a search or model error, finds no pages to read, or finds no description of a product or audience. A pasted Instagram or TikTok profile link reads no website and runs Creators like @<handle> on Instagram (or on TikTok), and so does a post, reel, or video link whose author the link itself or the Starcovery catalog names. A post link whose author neither names gets one reply asking for the creator's profile link and costs nothing.

A repeat of a brief and filters that the organization already searched spends nothing while that search stays in its search history.

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, and nothing when no creators are on screen. 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 Pay for API calls without a subscription.

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, read a creator's page, list and read published searches, run a search thread turn, intersect two creator lists, save, list, read, rename, and delete Lists, list, read, create, update, delete, and export campaigns, generate, add, and remove matches, list, upload, and delete campaign attachments, read a proposal send's reach, request a proposal send or campaign funding, cancel a send request, read the credit balance, start a credit pack checkout, open the billing portal, list the organization's handle claims, check whether it holds a verified handle, start a handle claim, request payout setup, list and answer the proposals sent to the organization's verified handles, list the campaigns that hired it, read the going rate, list the search history and remove an entry from it, send feedback, ask for hand-picked creators, read shoutout rewards, submit a shoutout post, pick the organization a reward credits, list and remove connected agents, and list, create, and revoke API keys. start_credit_checkout and open_billing_portal return a Stripe page for a person to open and finish in a browser. 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 offer the same features. REST runs any catalog tool with POST /api/tools/{name}, and the CLI with starcovery tools callTool --name <NAME>, beside their own endpoints and commands, as Every feature in every interface shows. An OAuth access token cannot manage API keys or connected agents.

Every feature in every interface

Each interface offers each feature, so a task started in one can finish in any other.

FeatureWebsiteREST APICLIMCP
Inspect the identity and credit sourceYesYesYesYes
Search creators from a briefYesYesYesYes
Enrich a shortlistYesYesYesYes
Reveal a contact addressYesYesYesYes
Read a creator's page, and list and read published searchesYesYesYesYes
Run a search thread turnYesYesYesYes
Save, list, read, rename, and delete ListsYesYesYesYes
Intersect two creator listsYes, as an assistant stepYesYesYes
Combine two creator lists by union or differenceYes, as an assistant stepYes, through get_list and save_listYes, through get_list and save_listYes, through get_list and save_list
List, read, create, update, delete, and export campaignsYesYesYesYes
Generate, add, and remove matchesYesYesYesYes
List the organization's files, and list, upload, and delete campaign attachmentsYesYesYesYes
Read a proposal send's reach and a campaign's funding quote, request a proposal send or campaign funding, and cancel a send requestYesYesYesYes
Read the credit balance, buy a credit pack, and open the billing portalYesYesYesYes
List handle claims and check for a verified handleYesYesYesYes
Start a handle claim, request payout setup, read the payout account, and list payoutsYesYesYesYes
List and answer the proposals sent to verified handles, list the campaigns that hired the organization, and read the going rateYesYesYesYes
Read the usage statement and usage analytics, list the search history, and remove an entryYesYesYesYes
Send feedback and ask for hand-picked creatorsYesYesYesYes
Read shoutout rewards, submit a shoutout post, and pick the organization a reward creditsYesYesYesYes
List and remove connected agentsYesYesYesYes
List, create, and revoke API keysYesYesYesYes
Read organizations, members, and invitationsYesYesYesYes
List the organization's activityYesYesYesYes
Change an organization or an accountYesYes, as its pageYes, as its pageYes, as its page

The assistant in the web app combines creator sets by intersection, union, and difference as steps of a thread. The other interfaces intersect two Lists with intersect_lists, and build a union or a difference by reading both Lists with get_list and saving the result with save_list.

Search threads and Lists

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 shortlistId for enrich_creators. creatorCount counts the whole set, and creators holds at most the 50 best fit of them, fewer when the result would pass 140,000 characters, so it fits an AI client's tool result limit. A first brief or a pasted website address that has no other reply runs its search in the turn and replies with the results line the web app shows: Found <n> creators for this brief., or No creators matched this brief. The reply, statement, and error are cut to 4,000 characters, and operations lists at most the first 20. Omit threadId to open a thread; the threadId in the result is the durable handle to pass back on the next turn, with threadKey when the call had no credential. When a limit, such as the per-minute limit, refuses the turn of a call that opened its thread, the tool error is JSON with the refusal in error beside threadId and any threadKey, so retry that thread instead of opening another. 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. With a credential, 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 with a credential 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 shortlistId, its threadId and any threadKey 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_match, add_campaign_matches, create_campaign, and save_list take each creator as a pick of profileId and fitScore only, the same body POST /api/campaigns/{campaignId}/matches takes. The catalog profile supplies the platform, handle, name, picture, and follower count, so a pick carries nothing else: a creator with any other key, such as the platform or username that search_creators and get_list return, fails the call with a validation error naming the key. 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.

Pick profileId (the creator id) and fitScore from each creator of a search_creators or get_list result before you call these tools. intersect_lists is the exception: it echoes the creators it is given and stores nothing, so it takes and returns the full saved creator shape that get_list returns. To pass a search_creators result to intersect_lists, map each creator first: profileId is the creator id, and fitScore, followerCount, name, platform, profileImageUrl, and username carry over.

Organization and account

get_organization reads the organization of the credential with its members, open invitations, and the caller's role. list_organizations lists every organization the caller belongs to, and list_received_invitations lists the open invitations to the caller's email.

The tools that change an organization or an account answer a link instead of making the change: rename_organization, create_organization, switch_organization, invite_member, resend_invitation, revoke_invitation, change_member_role, remove_member, leave_organization, delete_organization, answer_invitation, rename_account, sign_out_other_sessions, and delete_account. Each answers next, which says what the person confirms, and url, which opens the web app at the dialog that makes the change, filled in with the call's values. Opening the link changes nothing. The person signed in to Starcovery in a browser confirms the change there, so an API key or an OAuth access token alone can never remove a member, delete an organization, or delete an account. When the browser's active organization is not the organization of the credential, the page asks to switch first, and a person outside that organization sees that the link is for another organization.

The assistant in the web app runs the same tools on a card in its thread, and the change happens when the person presses the card's button. Leaving or deleting the organization and deleting the account open their dialog in Settings, which makes the change only once the person confirms there.

Get a credential

An MCP host that supports OAuth signs in when prompted. Otherwise, have an organization owner mint a Settings API key in Settings > API Keys.

To install the host skill for Cursor, Claude Code, and Codex:

npx -y skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex

With bun on PATH, bunx skills runs the same installer.

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 Code

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 and Claude Desktop

Claude on the web and Claude Desktop connect to Starcovery as a custom connector. On a Free, Pro, or Max plan, open Customize > Connectors, select Add custom connector, and enter these values:

  • Name: Starcovery
  • Remote MCP server URL: https://www.starcovery.com/api/mcp
  • Authentication: Sign in now
  • OAuth client: Register automatically

If the dialog shows only a name, a URL, and Advanced settings, leave the OAuth client ID and secret empty. Sign in to Starcovery when Claude opens the sign-in page, and pick the organization under Give access to.

Register automatically registers Claude's OAuth client through dynamic client registration. Starcovery does not advertise client ID metadata documents, which Use Claude's published identity needs. Sign in now makes every tool call run as your organization, search_creators included.

The Free plan holds one custom connector. On a Team or Enterprise plan, an Owner adds the connector under Organization settings > Connectors (Add, then Custom, then Web) with the same values, and each member selects Connect on it under Customize > Connectors.

To use a Settings API key instead of OAuth, choose No sign-in under Authentication and add a request header named authorization with the value Bearer <api_key>. Claude shows Request headers only to the organizations in its beta.

Cursor

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.

Codex

codex mcp add starcovery --url https://www.starcovery.com/api/mcp

Codex detects OAuth on the endpoint, registers its own client, and opens browser sign-in. Sign in to Starcovery and pick the organization under Give access to. To sign in again later, run codex mcp login starcovery.

To use a Settings API key instead, store it in an environment variable of the shell that runs Codex, and pass the variable's name to --bearer-token-env-var:

export STARCOVERY_TOKEN=<api_key>
codex mcp add starcovery --url https://www.starcovery.com/api/mcp --bearer-token-env-var STARCOVERY_TOKEN

Codex sends the variable's value as Authorization: Bearer <api_key> and skips OAuth. Both commands write a [mcp_servers.starcovery] entry to ~/.codex/config.toml.

Other HTTP MCP hosts

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.

Some hosts only accept a query parameter: https://www.starcovery.com/api/mcp?api_key=<access_token>. This is a last resort. Keys in URLs can leak through server logs, browser history, and the Referer header. Prefer Bearer or OAuth.

Example prompt

Ask your agent to read these docs, install the host skill if needed, sign in 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 questions

Do I need the web?

No. MCP, REST, and the CLI run the same catalog tools: GET /api/tools and starcovery tools listTools list them, and POST /api/tools/{name} and starcovery tools callTool run any of them with the same input and result as tools/call. API key management needs a browser session or a Settings API key; an OAuth access token gets 403.

Humans confirm organization and account changes in the web app, through the link those tools answer, and pay for a credit pack on the Stripe page that start_credit_checkout returns. Search, generate, enrich, and thread turns hold the connection open until the result is ready.

Where is the API described?

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.