MCP Server

AgentRef exposes a full Model Context Protocol server at a single endpoint. The current release surface is organized around four workflow groups: merchant_setup, merchant_growth, merchant_payouts, and affiliate_workspace. Claude Code, Claude App, Codex, Cursor, and OpenClaw (mcporter) can all use the production MCP endpoint directly. For these clients, the recommended path is OAuth-first: add the server, approve the browser sign-in once, and let the client store refreshable credentials for future sessions.

Endpoint

https://www.agentref.co/api/mcp

Authentication

The MCP release contract uses snake_case inputs and outputs. Mutation tools accept idempotency_key when you need retry-safe execution.

Preferred auth: OAuth 2.1 with dynamic client registration
Supported OAuth-first clients: Claude Code, Claude App, Codex, Cursor, OpenClaw (mcporter)
Fallback auth for custom/manual clients: Authorization: Bearer ak_live_*, ak_onb_*, or ak_aff_*

If your MCP client supports remote OAuth for Streamable HTTP servers, use that path. If it only supports static headers, create the appropriate API key in Settings -> API Keys and attach it manually.

Setup

Claude Code
Claude App
Codex
Cursor
OpenClaw

claude mcp add --scope user --transport http agentref https://www.agentref.co/api/mcp

Then open /mcp in Claude Code, select agentref, and authenticate once in the browser.

Open Customize -> Connectors -> + -> Add custom connector
Enter agentref as the name
Enter https://www.agentref.co/api/mcp as the remote MCP server URL
Start a new conversation and send please make a test call to the agentref mcp
Confirm the tool request, then click Reconnect on the AgentRef connector card to authorize access

Copy this prompt into Codex:

Please run `codex mcp add agentref --url https://www.agentref.co/api/mcp` in your shell.

Codex runs the command for you. Allow command execution once, then complete OAuth in the browser.If AgentRef is already configured and you only need to re-authenticate:

codex mcp login agentref

In Settings -> Tools & MCP -> Add Custom MCP, save:

.cursor/mcp.json

{
  "mcpServers": {
    "agentref": {
      "url": "https://www.agentref.co/api/mcp"
    }
  }
}

Then restart Cursor once, open the MCP settings again, and click Connect on the AgentRef server card.

Install or enable the mcporter skill in OpenClaw, then run:

mcporter --config ~/.openclaw/workspace/config/mcporter.json config add agentref https://www.agentref.co/api/mcp --auth oauth
mcporter --config ~/.openclaw/workspace/config/mcporter.json auth --reset agentref

Approve the browser prompt. On success, the callback page says Authorization successful. You can return to the CLI.

OpenClaw also has a non-MCP fallback: openclaw skills install agentref plus AGENTREF_API_KEY in ~/.openclaw/.env.

Custom clients

If your MCP client supports remote OAuth, use the same endpoint and complete the browser sign-in flow. If your client only supports manual headers, attach an AgentRef API key:

Authorization: Bearer ak_live_your_api_key_here

Workflow groups

Merchant setup tools

Tool	Purpose
`get_onboarding_status`	Read the current merchant onboarding state, blockers, and next steps.
`update_merchant_profile`	Update company, billing, timezone, and tracking defaults.
`create_program`	Create a new affiliate program.
`list_programs`	List programs or read one exact program by `program_id`.
`update_program`	Update one program’s settings, branding, marketplace state, or lifecycle.
`get_stripe_connect_url`	Generate the Stripe Connect authorization URL for one program.
`complete_onboarding`	Finalize merchant onboarding when the setup anchors are ready.
`get_tracking_snippet`	Return the JavaScript snippet and install instructions for one program.
`verify_tracking`	Check tracking health and return warnings plus next steps.

Merchant growth tools

Tool	Purpose
`list_affiliates`	List affiliates for one merchant, or read one exact affiliate by `affiliate_id`.
`set_affiliate_status`	Approve, block, or unblock an affiliate.
`list_invites`	List invite links for one program.
`create_invite`	Create a public or targeted invite link.
`revoke_invite`	Revoke one invite so it cannot be claimed again.
`get_program_overview`	Load key KPIs, status counts, and warnings for one program.
`list_conversions`	List merchant conversions with filters.
`list_flags`	List fraud and review flags, or load one exact flag.
`review_flag`	Resolve one fraud flag as reviewed, dismissed, or confirmed.

Merchant payout tools

Tool	Purpose
`list_pending_payouts`	List payout-ready affiliates who already meet the threshold.
`list_payouts`	List manual payout records with filters.
`list_upcoming_payouts`	List affiliates with released unpaid commissions plus next payout date.
`create_payout`	Create one manual payout record for an affiliate-program pair.
`update_payout_status`	Advance a payout to `processing`, `completed`, or `failed`.
`export_payouts_csv`	Export open manual payouts for PayPal, Wise, SEPA, or generic workflows.

Affiliate workspace tools

Tool	Purpose
`discover_programs`	Search public marketplace programs with filters.
`apply_to_program`	Apply the current affiliate account to a marketplace program.
`list_my_programs`	List the current affiliate account and linked program context.
`list_links`	List existing tracking links for the current affiliate account.
`create_link`	Create one affiliate tracking link for the current program.
`get_earnings`	Return a compact earnings summary for the current affiliate account.
`get_click_stats`	Return daily click and unique click totals for the current affiliate account.
`list_my_payouts`	List payout history for the current affiliate account.
`update_my_payout_profile`	Update payout destination and billing fields for the current affiliate account.

Resources

The server also exposes five read-oriented resources for structured data access:

Resource URI	Description
`merchant://me`	Authenticated merchant profile and baseline account configuration.
`program://{id}`	Program configuration and ownership metadata.
`stats://{programId}`	Program-level conversion and commission statistics.
`affiliate://me/programs`	Authenticated affiliate program context and performance summary.
`marketplace://catalog`	Catalog of public marketplace programs.

Prompts

The MCP server also registers four reusable prompts for guided workflows:

Prompt	Purpose
`onboard_program`	Guide an agent through program creation, Stripe connect, tracking verification, and onboarding completion.
`review_payout_run`	Guide a manual payout run from candidate discovery to final payout status updates.
`debug_tracking_installation`	Diagnose an incomplete or broken tracking installation for one program.
`triage_fraud_flags`	Review open fraud flags, prioritize them, and resolve them safely.

Idempotency

Mutation tools accept an optional idempotency_key. When provided, the server guarantees at-most-once execution for the logical operation — safe for agent retries.

idempotency_key: "setup-acme-program-2026-04"

Always pass an idempotency key when your agent might retry a tool call. This prevents duplicate programs, double payouts, or repeated approvals.

Workflow Examples

Set Up a New Program

A natural conversation with your AI agent might look like:

You: “Create a SaaS affiliate program called ‘Acme Pro Referrals’ with 25% recurring commission and a 60-day cookie.”

The agent calls:

get_onboarding_status({})

create_program({
  name: "Acme Pro Referrals",
  commission_percent: 25,
  commission_type: "recurring",
  cookie_duration: 60,
  idempotency_key: "create-acme-pro-referrals"
})

Then it follows up with get_stripe_connect_url, get_tracking_snippet, verify_tracking, and complete_onboarding.

Monitor Fraud Flags

You: “Check if there are any suspicious conversions this week and resolve them.”

The agent can start with list_flags, then resolve specific items with review_flag:

list_flags({
  status: "open",
  limit: 20
})

review_flag({
  flag_id: "flag-uuid-here",
  resolution: "dismissed",
  note: "Verified legitimate traffic from blog post",
  idempotency_key: "resolve-flag-abc123"
})

Generate a Payout Report

You: “Show me who’s ready for payout, create the payout records, and export a CSV for PayPal.”

list_pending_payouts({ program_id: "prog-uuid" })

create_payout({
  affiliate_id: "aff-uuid",
  program_id: "prog-uuid",
  idempotency_key: "payout-acme-april"
})

export_payouts_csv({ format: "paypal", program_id: "prog-uuid" })

Affiliate: Discover and Join Programs

You: “Find affiliate programs with at least 20% commission and apply to the best one.”

discover_programs({ min_commission: 20, sort_by: "commission" })

apply_to_program({
  program_id: "prog-uuid",
  message: "I run a SaaS review blog with 50k monthly readers.",
  idempotency_key: "apply-prog-xyz"
})

create_link({
  program_id: "prog-uuid",
  target_url: "https://acme.com/pricing",
  idempotency_key: "link-acme-pricing"
})

Sessions and transport

The endpoint uses Streamable HTTP at https://www.agentref.co/api/mcp
Sessions are created during the MCP initialize flow and handled automatically by clients
If a client holds an expired or invalid session id, it should reconnect and initialize again

Error Handling

Tool errors are returned as structured MCP results with an error code, message, and HTTP status. Common scenarios:

Error	Cause
`UNAUTHORIZED`	OAuth not completed yet, or invalid fallback API key
`FORBIDDEN`	Key lacks required scope
`NOT_FOUND`	Program, affiliate, or flag does not exist
`VALIDATION_ERROR`	Invalid input parameters
`RATE_LIMITED`	Too many requests — retry after delay

All errors include a requestId for debugging. Reference it when contacting support.

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Endpoint

Authentication

Setup

Custom clients

Workflow groups

Merchant setup tools

Merchant growth tools

Merchant payout tools

Affiliate workspace tools

Resources

Prompts

Idempotency

Workflow Examples

Set Up a New Program

Monitor Fraud Flags

Generate a Payout Report

Affiliate: Discover and Join Programs

Sessions and transport

Error Handling

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

​Endpoint

​Authentication

​Setup

​Custom clients

​Workflow groups

​Merchant setup tools

​Merchant growth tools

​Merchant payout tools

​Affiliate workspace tools

​Resources

​Prompts

​Idempotency

​Workflow Examples

​Set Up a New Program

​Monitor Fraud Flags

​Generate a Payout Report

​Affiliate: Discover and Join Programs

​Sessions and transport

​Error Handling

Endpoint

Authentication

Setup

Custom clients

Workflow groups

Merchant setup tools

Merchant growth tools

Merchant payout tools

Affiliate workspace tools

Resources

Prompts

Idempotency

Workflow Examples

Set Up a New Program

Monitor Fraud Flags

Generate a Payout Report

Affiliate: Discover and Join Programs

Sessions and transport

Error Handling