MCP documentation

Scope & release status

CreatorSponsors helps creators find brands already sponsoring other creators. The MCP connection researches saved sponsorship records, brand history, similar creators and possible sponsors. Past activity does not establish a current sponsorship budget, availability or willingness to accept a pitch.

The last verified production pilot supported YouTube research only. Instagram and TikTok research exists in unpublished local work and is upcoming; its platform selectors, social slugs and snapshot-specific outputs are not part of this live-release reference. Similar-creator and channel-based research remain YouTube-only.

This research connection does not expose contact details, contact enrichment, message sending, payments or persistence of lists to your account. “Build a list” returns research in the tool response; it does not save an account list. Protocol, security and quota state are still recorded.

Endpoint & transport

https://www.creatorsponsors.ai/mcp

Use Streamable HTTP with JSON-RPC POST requests. The verified implementation uses stateless JSON responses: no persistent MCP session ID, standalone SSE subscription or DELETE session endpoint. A browser GET is informational when the pilot is enabled; it does not execute research.

The pilot’s pinned MCP SDK (1.32.2) declares these supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07. These are implementation-supported versions, not proof that every host/version combination was tested. Negotiate through initialize, send notifications/initialized, and use the negotiated MCP-Protocol-Version on subsequent requests.

Send Content-Type: application/json, Accept: application/json, text/event-stream and Authorization: Bearer <access_token>. Use an MCP SDK to handle lifecycle messages. The last enabled pilot required account authentication; an informational GET or public example is not anonymous research access.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "example-research-client",
      "version": "1.0.0"
    }
  }
}

OAuth & account linking

1. When enabled, unauthenticated protocol requests receive a 401 challenge pointing to protected-resource metadata. Discover the issuer and authorization-server metadata from there.
2. Start authorization with response_type=code, scope mcp:read for explicitly read-only access (legacy mcp is also supported), resource https://www.creatorsponsors.ai/mcp, the exact registered redirect URI, state and a PKCE S256 challenge. Plain PKCE is not supported.
3. The user signs into CreatorSponsors and explicitly allows or denies research-only access on the consent page. Denial returns access_denied to the registered callback.
4. Exchange the one-use authorization code at the token endpoint with the same redirect URI, resource and PKCE verifier. The consent request lasts 10 minutes; the issued code lasts 2 minutes.
5. Access tokens last at most 1 hour. Refresh uses grant_type=refresh_token with the registered client’s authentication method. Both tokens rotate; store the new pair atomically and do not reuse the old refresh token. The grant has a fixed maximum 180-day lifetime from authorization; refreshing does not extend it.
6. Disconnect through Connected apps or the authenticated revocation endpoint. Disconnect invalidates the grant. Relinking replaces prior credentials for that account/client; it does not reset usage.

Token and revocation requests use application/x-www-form-urlencoded, not JSON. Client credentials belong on the integration’s server, never in browser code, documentation or a public repository. A revoked, expired or invalid refresh grant requires a fresh user authorization.

Integration setup

Provider onboarding is manual. Contact CreatorSponsors support with your integration name and the exact HTTPS OAuth callback URL generated by your provider. Each callback must be registered as a complete string, including scheme, hostname, path and any query string. No wildcard redirects, inferred callback paths or shared credentials.

Grok Bot and Cursor

The pinned public client ID is https://cursor.com/oauth/mcp-client.json. It does not require a client secret. It accepts only https://www.cursor.com/agents/mcp/oauth/callback, https://www.cursor.com/bot/mcp/oauth/callback and https://grok.com/connectors-oauth-exchange-code/. These HTTPS callbacks are published in Cursor’s client metadata. Request mcp:read; this client always receives read-only research grants. Read-only scope is enforced from the stored grant and preserved through refresh. Unknown metadata clients, dynamic registration and desktop loopback callbacks remain unsupported. Server compatibility checks do not establish a successful Grok Bot in-app connection.

After account linking, initialize the MCP connection and call tools/list. Use that authenticated catalogue as the final authority before enabling your integration. No provider registration is performed by reading or using this page.

Research tools

The last verified research connection exposes the four tools below. Inputs are strict objects: unknown fields are rejected. All fields are optional unless listed as required. Output is returned in structuredContent with a human-readable content text summary.

{
  "readOnlyHint": true,
  "destructiveHint": false,
  "openWorldHint": false
}

These annotations describe research behavior; calls still consume allowance and may update operational caches and quota counters. Audience size, subscriber/view ranges, creator-name filters and competitor-name filters are not supported. A channel ID is not a handle or a channel URL.

The schemas below document the supported YouTube contract confirmed by the pilot implementation and release review. Authenticated tools/list is the authoritative catalogue for the restored release. Do not import the newer local social schemas into a client.

search_sponsors

Find indexed brands by market and saved-history window. platform accepts only youtube; omitting it uses YouTube. Country is a two-character creator-channel country code, uppercased before the backend request, not the brand’s location. Niche and sub-niche are saved market terms.

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "sub_niche": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      },
      "maxItems": 1
    },
    "platform": {
      "type": "string",
      "enum": [
        "youtube"
      ]
    },
    "window_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Optional; effective pilot default and maximum are 5."
    }
  },
  "additionalProperties": false
}

window_days defaults to 0 (all saved history); positive values request that many days of recency. Page defaults to 1. Limit defaults to 5 and is clamped to 5 even though schema validation accepts 1–50. If niche is absent, only the single supplied keyword is used as the niche. Omitted market filters leave the search unfiltered.

There is no cursor or next-page flag in the tool output. Request page 2 or 3 using the same filters and limit; stop when no results remain or page 3 is reached. The index can change between requests, so this is not snapshot pagination.

Illustrative exchange

Static example, not a live query or production result. Replace example identifiers with values returned by your research. The response includes a placeholder text summary instead of the server’s generated wording.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_sponsors",
    "arguments": {
      "niche": "technology",
      "country": "US",
      "platform": "youtube",
      "window_days": 0,
      "page": 1,
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "total": 0,
      "fallback_applied": false,
      "fallback_reason": null,
      "sponsors": []
    },
    "content": [
      {
        "type": "text",
        "text": "Illustrative response only."
      }
    ]
  }
}

get_brand_sponsorship_history

Inspect a numeric brand_id returned by sponsor search. Do not substitute a social slug. There is no platform selector or pagination input in this pilot tool.

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Optional; effective pilot default and maximum are 5."
    }
  },
  "required": [
    "brand_id"
  ],
  "additionalProperties": false
}

Limit defaults to 5 and bounds creators, recent videos and related sponsor samples. Summary totals describe the indexed history and may exceed the sample sizes. Some optional or unavailable metadata is absent or null.

Illustrative exchange

Static example, not a live query or production result. Replace example identifiers with values returned by your research. The response includes a placeholder text summary instead of the server’s generated wording.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_brand_sponsorship_history",
    "arguments": {
      "brand_id": 123,
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "brand": {
        "id": 123,
        "name": "Example brand (fictional)",
        "website": null,
        "domain": null,
        "aliases": []
      },
      "summary": {
        "sponsored_videos": 0,
        "sponsored_channels": 0,
        "average_per_creator": 0,
        "active_last_30d": 0,
        "latest_seen_at": null,
        "average_confidence": 0
      },
      "creators": [],
      "recent_videos": [],
      "related_sponsors": [],
      "source_url": "https://www.creatorsponsors.ai/sponsors/123"
    },
    "content": [
      {
        "type": "text",
        "text": "Illustrative response only."
      }
    ]
  }
}

find_similar_creators

Return saved similar-creator research for a known YouTube channel ID. This does not launch fresh creator discovery and does not support Instagram or TikTok.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 128
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Optional; effective pilot default and maximum are 5."
    }
  },
  "required": [
    "channel_id"
  ],
  "additionalProperties": false
}

Output fields: target_channel_id, cached and creators[]. Each creator can include channel_id, name, subscriber_count, country, language, profile_image_url, overall_score, scores, matching_topics and discovery_query. Scores are saved similarity signals, not a guarantee of audience or sponsorship fit. Limit defaults to 5; no pagination is exposed.

Illustrative exchange

Static example, not a live query or production result. Replace example identifiers with values returned by your research. The response includes a placeholder text summary instead of the server’s generated wording.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "find_similar_creators",
    "arguments": {
      "channel_id": "UC_EXAMPLE_CHANNEL_ID",
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "target_channel_id": "UC_EXAMPLE_CHANNEL_ID",
      "cached": true,
      "creators": []
    },
    "content": [
      {
        "type": "text",
        "text": "Illustrative response only."
      }
    ]
  }
}

build_sponsor_prospect_list

Return possible sponsors from saved YouTube peer analysis or market search. A supplied channel ID gives saved peer-sponsor analysis priority over niche, sub-niche, keywords and country. If the peer backend reports 404 or 409 (no usable saved analysis), the tool falls back to market search. Other backend failures are errors, not permission to invent results.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 128
    },
    "niche": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "sub_niche": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      },
      "maxItems": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Optional; effective pilot default and maximum are 5."
    }
  },
  "additionalProperties": false
}

Without channel analysis, niche takes priority over the one keyword, country is uppercased, and the market query uses all saved history (window_days=0). No page, recency, audience-size or competitor filters are exposed. Limit defaults to 5.

Output fields are prospects[] and basis[]. Market prospects contain brand_id, brand_name, domain, website, description, score_signals (creators_sponsored, sponsored_videos, latest_sponsorship_at, average_confidence), recent_sponsored_creators and source_url. Peer-based prospects pass through saved peer-analysis brand records; that flexible record is not the same schema as a market prospect. Inspect basis and handle missing fields.

This tool does not return the search fallback flags. Its market path can inherit the backend’s broader-market fallback; do not describe every returned brand as an exact country or niche match.

Illustrative exchange

Static example, not a live query or production result. Replace example identifiers with values returned by your research. The response includes a placeholder text summary instead of the server’s generated wording.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "build_sponsor_prospect_list",
    "arguments": {
      "niche": "technology",
      "country": "US",
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "prospects": [],
      "basis": [
        "market sponsor search",
        "unique creators sponsored",
        "sponsored videos",
        "latest detected sponsorship"
      ]
    },
    "content": [
      {
        "type": "text",
        "text": "Illustrative response only."
      }
    ]
  }
}

Account access & limits

These are the last verified November 1 pilot limits, not currently available capacity. MCP calls are separate from contact-unlock credits. Plan entitlement is resolved server-side from the linked account, never chosen by client input.

These are ceilings, not guaranteed daily capacity: all accounts also share 100 admitted tool calls per UTC day, including at most 25 Free calls. Paid traffic can use remaining shared capacity but cannot bypass the 100-call ceiling. For example, Pro’s 150/day allowance does not override the service’s 100/day pilot cap.

The last YouTube-only pilot uses account tiers for tool budgets; do not infer that an Instagram/TikTok Starter subscription enables unpublished social MCP tools. Platform-specific MCP access is part of the upcoming local work. Paid allowance boundaries were tested locally with shared quota storage; the paid production OAuth-to-entitlement-to-search path was not verified.

Admitted tool calls consume allowance even on cache hits or when a later tool validation/backend operation fails. Admission denials do not spend another tool call, though protocol request budgets still apply. Initialize, tools/list and other protocol POSTs use the protocol budget. Minimize repeated listing, polling and automatic retries.

Tool counters use fixed UTC minute, day and calendar-month buckets, not the subscription billing anniversary. Account, service and free-pool daily budgets reset at 00:00 UTC; monthly budgets reset at the start of the next UTC month. Reconnecting, rotating tokens or keys, and changing plans do not erase existing usage. Entitlement caching can delay plan recognition by up to 30 seconds.

Errors & retry behavior

Check HTTP status first, then JSON-RPC error and tool-result isError. A 200 transport response can still contain a tool error. Do not treat an error, a missing field or a source-link failure as evidence of no sponsorships.

OAuth errors include invalid_client, invalid_scope, invalid_target, invalid_request, invalid_grant, expired_request and access_denied. Correct registration/scope/resource errors before retrying. invalid_grant after rotation, expiry or revocation needs a valid current refresh token or a new authorization. slow_down is 429; temporarily_unavailable and account_linking_unavailable are 503. Do not assume OAuth errors include the MCP Retry-After header.

Saved data, freshness & sources

Results come from saved indexed records and cached analysis, not a live YouTube crawl. Coverage is incomplete, varies by market and creator, and has no guaranteed refresh interval or completeness SLA. Similar-creator results require saved peer research; no new paid discovery or enrichment is launched through this connection.

The YouTube search backend can broaden sparse filters: first dropping country, then using the broader indexed market when fewer than five matches are found. Read fallback_applied and fallback_reason before claiming an exact match. A positive recency window filters saved evidence dates; it does not guarantee the data was refreshed recently.

source_url usually links to a CreatorSponsors brand record. Video evidence uses its saved evidence URL, falling back to its YouTube URL. A record page is not necessarily the original sponsorship disclosure. Source posts may be removed, region-restricted or require a platform login; links are not guaranteed to remain available. Inspect dates and original evidence before relying on a result. Null metadata and empty arrays are valid; never fill them with invented facts.

Instagram/TikTok snapshots and their distinct freshness/country-provenance caveats belong to the unpublished local implementation. They will need a separate published reference and verification before clients can rely on them.

Support & policies

For integration onboarding, missing data or service issues, use Contact support or hello@outreach.creatorsponsors.ai. Include the tool name, HTTP status and approximate UTC time. Do not send access tokens, refresh tokens or client secrets.

Privacy Policy · Terms of Service · Account plans

Verification note: November 1 pilot release inventory and lifecycle/limit tests, followed by read-only public endpoint checks on November 2. This reference targets the restored YouTube pilot release. Runtime flags control service availability. Authenticated catalogue verification and provider-specific setup remain required before a new production integration.