ReferralCodes MCP Connector

Connect AI assistants to ReferralCodes.com with the Model Context Protocol (MCP). Assistants can find member-shared referral offers, hand the user a referral link, show offers from people the user follows and add the user's own referral codes to their profile.

Endpoint Sign-in & scopes Tools Examples Limits Errors REST API Privacy

MCP endpoint

https://rewardcircle.com/mcp

To add ReferralCodes to an assistant that supports custom connectors, paste the endpoint URL above. The assistant will find the sign-in details automatically.

Sign-in & scopes

ReferralCodes uses OAuth 2.1 with PKCE (S256). Members sign in on ReferralCodes.com and approve what the assistant may do; the assistant never sees their password. Members can review and disconnect apps at any time from Profile → Connected apps.

ScopeWhat it allows
referrals:readSearch and view referral offers on your behalf
contacts:readSee referral offers shared by people you follow
referrals:writeAdd referral codes to your ReferralCodes profile (they are reviewed before going live)

Discovery documents:

Supported client registration methods:

Access tokens last 60 minutes and can be refreshed for up to 30 days. Always send the resource parameter (RFC 8707) with the MCP endpoint URL. When a tool needs sign-in or a scope the member has not granted, the server responds with HTTP 401/403 and a WWW-Authenticate header naming the required scope, so the client can ask the member to approve it (step-up).

Tools

ToolPurposeSign-inType
search_referrals Search offers by brand, category or a request such as "bank account UK". Returns ranked offers with an opaque referral_id and no raw codes or links. scope is public (default), contacts or all. Not needed for public; contacts:read otherwise Read only
get_referral Full details of one offer: rewards, eligible countries, who shared it. Not needed Read only
get_referral_link The link (and code, if any) for the offer the user picked. Returns a ReferralCodes.com redirect link valid for 30 days. Pass country to check availability. Not needed Read only
search_contacts_referrals Offers shared by people the member follows, optionally for one contact by name or username. contacts:read Read only
import_my_referrals Add up to 10 of the member's own codes or links per call. Each is checked like a website submission and reviewed before it goes live. Use dry_run to check without saving. referrals:write Write (not destructive)

Every tool publishes an input schema, an output schema and annotations (readOnlyHint, destructiveHint: false). Results are returned as structured content with a status field (for example ok, no_match, no_contacts, requires_review or error).

Recommended flow: call search_referrals, let the user choose, then call get_referral_link for that offer only. Rewards are as listed by the brand or stated by the member; never promise the user they are eligible.

Examples

Example prompts

Search (JSON-RPC)

POST https://rewardcircle.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_referrals",
    "arguments": { "query": "bank account", "country": "UK", "limit": 3 }
  }
}

Result (abridged)

{
  "status": "ok",
  "scope": "public",
  "public": [
    {
      "referral_id": "ref_3kTq9...",
      "brand": { "name": "Monzo", "slug": "monzo", "domain": "monzo.com" },
      "title": "Monzo referral",
      "type": "link",
      "countries": ["United Kingdom"],
      "rewards": { "member_stated": "£5 when you open an account", "verified": false },
      "relationship": "public",
      "shared_by": { "display_name": "Alex P." },
      "link_available": true
    }
  ]
}

Get the link for the chosen offer

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_referral_link",
    "arguments": { "referral_id": "ref_3kTq9...", "country": "UK" }
  }
}

Limits

WhoLimit
Signed-in member (all apps together)60 tool calls per minute, 600 per hour
Anonymous caller20 tool calls per minute, 200 per hour
Referral links60 per hour per caller
Adding referrals20 calls per hour, up to 10 referrals per call, plus the same daily allowance as the website's agent import page
Search resultsUp to 10 offers per group (default 5)
Request size64 KB per request

When a limit is reached the tool returns RATE_LIMIT_EXCEEDED with details.retry_after_seconds. The REST API also sends a Retry-After header.

Errors

Tool errors come back as a tool result with isError: true and status: "error", plus an error object holding code, message and, optionally, details. The REST API returns the same error object with the HTTP status shown below.

CodeHTTPMeaning
AUTHENTICATION_REQUIRED401The member needs to connect their ReferralCodes account to use this.
PERMISSION_DENIED403The connected account has not granted permission for this action.
REFERRAL_NOT_FOUND404No referral exists with that ID.
REFERRAL_UNAVAILABLE410That referral is no longer available.
CONTACT_NOT_FOUND404None of the people this member follows match that name.
AMBIGUOUS_CONTACT409More than one person this member follows matches that name. Ask the user which one they mean.
VALIDATION_FAILED422The request is invalid.
DUPLICATE_REFERRAL409This referral has already been submitted.
RATE_LIMIT_EXCEEDED429Too many requests. Try again later.
TEMPORARILY_UNAVAILABLE503ReferralCodes is temporarily unavailable. Try again shortly.
INTERNAL_ERROR500Something went wrong on the ReferralCodes side.

REST API

The same tools are available over REST with the same OAuth tokens (Authorization: Bearer ...):

OpenAPI 3.1 description: https://rewardcircle.com/api/agent/v1/openapi.json

Privacy

See our Terms and Privacy Policy. For support or to get a pre-registered client, contact partners@referralcodes.com. Looking for the browser-based import format? See Agent Import.