MCP Server

AgentRef exposes Model Context Protocol servers for two personas: merchant workflows and affiliate workspace workflows. Use the merchant endpoint for program setup, growth, payouts, applications, and marketing resources. Use the affiliate endpoint for marketplace discovery, links, earnings, payout profile, and affiliate marketing resources. 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

Persona	Endpoint
Merchant	`https://www.agentref.co/api/mcp/merchant`
Affiliate	`https://www.agentref.co/api/mcp/affiliate`

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_* 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-merchant https://www.agentref.co/api/mcp/merchant

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/merchant 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-merchant --url https://www.agentref.co/api/mcp/merchant` 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-merchant

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

.cursor/mcp.json

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

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-merchant https://www.agentref.co/api/mcp/merchant --auth oauth
mcporter --config ~/.openclaw/workspace/config/mcporter.json auth --reset agentref-merchant

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 endpoint for the persona you need 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

MCP is the broadest automation surface. Some setup, payout, invite, tracking, and Marketing Resources tools call AgentRef services directly and do not have REST or SDK equivalents yet. Use the REST/SDK pages when you need only the public API v1 surface, and use MCP when an agent needs these expanded workflows.

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`.
`list_applications`	List marketplace and portal applications, or read one exact application.
`review_application`	Approve, decline, or block one pending application.
`set_affiliate_status`	Block or unblock an approved affiliate membership.
`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.

Merchant marketing resources tools

Tool	Purpose
`list_marketing_resources`	List merchant-owned collections, files, social posts, links, and draft assets.
`get_marketing_resource`	Read one marketing resource or collection.
`create_marketing_collection`	Create a campaign collection.
`update_marketing_collection`	Update collection metadata.
`publish_marketing_resource`	Publish a resource or collection for affiliates.
`unpublish_marketing_resource`	Move a resource or collection back to draft.
`archive_marketing_resource`	Archive a resource or collection.
`create_marketing_social_post`	Create affiliate-ready social post copy.
`update_marketing_social_post`	Update social post copy, platforms, instructions, or grouping.
`create_marketing_social_post_media_upload_session`	Create a signed upload session for social post media.
`complete_marketing_social_post_media_upload`	Attach uploaded media to a social post.
`remove_marketing_social_post_media`	Remove social post media.
`update_marketing_social_post_media`	Update media alt text.
`reorder_marketing_social_post_media`	Normalize social post media order.
`replace_marketing_social_post_media`	Replace a media file while preserving its media record.
`create_marketing_resource_download_url`	Create a short-lived merchant download URL.
`create_marketing_external_link`	Add an external resource link.
`create_marketing_upload_session`	Create a signed upload session for a file or ZIP import.
`complete_marketing_upload_session`	Complete an uploaded file or ZIP import.
`import_marketing_resource_from_url`	Import a remote file or ZIP into private storage.
`notify_marketing_resource_affiliates`	Queue affiliate notifications for a published resource.

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.
`get_affiliate_overview`	Return aggregate affiliate workspace KPIs across programs.
`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.

Affiliate marketing resources tools

Tool	Purpose
`list_marketing_resources`	List affiliate-visible resources for a program.
`get_marketing_resource`	Read one affiliate-visible resource or collection.
`render_marketing_social_post`	Render social post copy with affiliate placeholders and disclosure guidance.
`create_marketing_resource_download_url`	Create a short-lived affiliate download URL.

Resources

The servers also expose read-oriented resources for structured data access:

Persona	Resource URI	Description
Merchant	`merchant://me`	Authenticated merchant profile and baseline account configuration.
Merchant	`program://{id}`	Program configuration and ownership metadata.
Merchant	`stats://{programId}`	Program-level conversion and commission statistics.
Merchant	`marketing-resources://program/{program_id}`	Marketing resources for a program.
Merchant	`marketing-resource-collection://{collection_id}`	One marketing resource collection.
Merchant	`marketing-resource://{resource_id}`	One marketing resource item.
Affiliate	`affiliate://me/programs`	Authenticated affiliate program context and performance summary.
Affiliate	`marketplace://catalog`	Catalog of public marketplace programs.
Affiliate	`marketing-resources://program/{program_id}`	Affiliate-visible marketing resources for a program.
Affiliate	`marketing-resource-collection://{collection_id}`	Affiliate-visible collection details.
Affiliate	`marketing-resource://{resource_id}`	Affiliate-visible resource details.

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",
  destination_path: "/pricing",
  custom_slug: "acme-review",
  idempotency_key: "link-acme-pricing"
})

Merchant: Publish Campaign Assets

You: “Create a LinkedIn post for our launch kit and publish it for affiliates.”

create_marketing_social_post({
  program_id: "prog-uuid",
  title: "Launch announcement",
  body: "I am sharing {{program_name}} because it helps teams launch affiliate programs faster: {{affiliate_link}}",
  platforms: ["linkedin"],
  status: "draft",
  idempotency_key: "launch-post-001"
})

publish_marketing_resource({
  program_id: "prog-uuid",
  resource_id: "resource-uuid",
  idempotency_key: "publish-launch-post-001"
})

Affiliate: Render Campaign Copy

You: “Show me the latest social posts for this program and render one with my link.”

list_marketing_resources({
  program_id: "prog-uuid",
  kind: "social_posts"
})

render_marketing_social_post({
  program_id: "prog-uuid",
  resource_id: "resource-uuid",
  affiliate_link_id: "link-uuid"
})

Sessions and transport

The endpoints use Streamable HTTP at https://www.agentref.co/api/mcp/merchant and https://www.agentref.co/api/mcp/affiliate
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

Merchant marketing resources tools

Affiliate workspace tools

Affiliate marketing resources tools

Resources

Prompts

Idempotency

Workflow Examples

Set Up a New Program

Monitor Fraud Flags

Generate a Payout Report

Affiliate: Discover and Join Programs

Merchant: Publish Campaign Assets

Affiliate: Render Campaign Copy

Sessions and transport

Error Handling

​Endpoint

​Authentication

​Setup

​Custom clients

​Workflow groups

​Merchant setup tools

​Merchant growth tools

​Merchant payout tools

​Merchant marketing resources tools

​Affiliate workspace tools

​Affiliate marketing resources tools

​Resources

​Prompts

​Idempotency

​Workflow Examples

​Set Up a New Program

​Monitor Fraud Flags

​Generate a Payout Report

​Affiliate: Discover and Join Programs

​Merchant: Publish Campaign Assets

​Affiliate: Render Campaign Copy

​Sessions and transport

​Error Handling

Endpoint

Authentication

Setup

Custom clients

Workflow groups

Merchant setup tools

Merchant growth tools

Merchant payout tools

Merchant marketing resources tools

Affiliate workspace tools

Affiliate marketing resources tools

Resources

Prompts

Idempotency

Workflow Examples

Set Up a New Program

Monitor Fraud Flags

Generate a Payout Report

Affiliate: Discover and Join Programs

Merchant: Publish Campaign Assets

Affiliate: Render Campaign Copy

Sessions and transport

Error Handling