Agent Setup - AgentRef

AgentRef is agent-native. You can manage your affiliate program – creating programs, inviting affiliates, checking stats, processing payouts – through any AI assistant that supports tool use. This page covers all four integration methods. Pick the one that fits your stack.

MCP Server
Node.js SDK
Python SDK
REST API

The MCP (Model Context Protocol) server is the fastest way to connect AgentRef to AI assistants. For Claude Code, Claude App, Codex, Cursor, and OpenClaw (mcporter), the recommended flow is OAuth-first: add the server once, finish the browser sign-in, and let your client store tokens for future sessions.Merchant server URL: https://www.agentref.co/api/mcp/merchantAffiliate server URL: https://www.agentref.co/api/mcp/affiliateRecommended auth: MCP OAuth 2.1 with dynamic client registrationFallback auth for custom clients: Authorization: Bearer ak_live_your_key_here

Claude Code

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 complete the OAuth flow once.

Claude App

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

Codex

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

Cursor

In Settings -> Tools & MCP -> Add Custom MCP, save this mcp.json entry:

{
  "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.

OpenClaw (`mcporter`)

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 REST skill (fallback)

If you prefer OpenClaw without MCP, install the official skill from ClawHub:

openclaw skills install agentref

Then create the appropriate AgentRef API key and store it in ~/.openclaw/.env before restarting the gateway:

grep -v '^AGENTREF_API_KEY=' ~/.openclaw/.env 2>/dev/null > /tmp/oc_env && printf 'AGENTREF_API_KEY=%s\n' 'ak_live_your_key_here' >> /tmp/oc_env && mv /tmp/oc_env ~/.openclaw/.env && openclaw gateway restart

Other MCP clients

Any remote MCP client that supports OAuth for Streamable HTTP servers can use the same endpoint. Prefer OAuth when available. If your client only supports manual headers, use the same endpoint with Authorization: Bearer ak_live_your_key_here.

Try it out

After connecting, try these prompts with your AI assistant:

“Check my onboarding status and tell me what is still blocking launch”
“Show me my affiliate program stats for the last 30 days”
“List all my affiliates and their performance”
“Create a new affiliate program called ‘Partner Program’ with 25% recurring commission”
“Check if my tracking script is installed correctly”

The Node.js SDK provides a type-safe client for all AgentRef API operations.

Installation

npm install agentref

Configuration

import { AgentRef } from 'agentref';

const client = new AgentRef({
  apiKey: 'ak_live_your_key_here',
});

Store your API key in environment variables, not in source code. Use process.env.AGENTREF_API_KEY in production.

Create a program

const program = await client.programs.create({
  name: 'Partner Program',
  commissionType: 'recurring',
  commissionPercent: 25,
  cookieDuration: 30,
  payoutThreshold: 5000, // $50.00 in cents
  payoutFrequency: 'monthly',
  autoApproveAffiliates: true,
});

console.log(`Program created: ${program.id}`);

Invite an affiliate

const invite = await client.programs.createInvite(program.id, {
  email: 'partner@example.com',
});

console.log(`Invite sent: ${invite.id}`);

Check stats

const stats = await client.programs.stats(program.id, {
  period: '30d',
});

console.log(`Conversions: ${stats.total}`);
console.log(`Revenue: $${(stats.totalRevenue / 100).toFixed(2)}`);

List conversions

const conversions = await client.conversions.list({
  programId: program.id,
  status: 'pending',
  limit: 20,
});

for (const conversion of conversions.data) {
  console.log(`${conversion.id}: $${(conversion.amount / 100).toFixed(2)}`);
}

For the full SDK reference, see Node.js SDK.

The Python SDK provides a clean client for all AgentRef API operations.

Installation

pip install agentref

Configuration

from agentref import AgentRef

client = AgentRef(api_key='ak_live_your_key_here')

Store your API key in environment variables, not in source code. Use os.environ['AGENTREF_API_KEY'] in production.

Create a program

program = client.programs.create(
    name='Partner Program',
    commission_type='recurring',
    commission_percent=25,
    cookie_duration=30,
    payout_threshold=5000,  # $50.00 in cents
    payout_frequency='monthly',
    auto_approve_affiliates=True,
)

print(f"Program created: {program.id}")

Invite an affiliate

invite = client.programs.create_invite(
    program.id,
    email='partner@example.com',
)

print(f"Invite sent: {invite.id}")

Check stats

stats = client.programs.stats(
    program.id,
    period='30d',
)

print(f"Conversions: {stats.total}")
print(f"Revenue: ${stats.total_revenue / 100:.2f}")

List conversions

conversions = client.conversions.list(
    program_id=program.id,
    status='pending',
    limit=20,
)

for conversion in conversions.data:
    print(f"{conversion.id}: ${conversion.amount / 100:.2f}")

For the full SDK reference, see Python SDK.

If you’re not using an SDK or MCP, you can call the REST API directly.Base URL: https://www.agentref.co/api/v1Auth: Pass your API key as a Bearer token in the Authorization header.

List programs

curl -X GET https://www.agentref.co/api/v1/programs \
  -H "Authorization: Bearer ak_live_your_key_here"

const res = await fetch('https://www.agentref.co/api/v1/programs', {
  headers: { Authorization: 'Bearer ak_live_your_key_here' },
});
const data = await res.json();

import requests

res = requests.get(
    'https://www.agentref.co/api/v1/programs',
    headers={'Authorization': 'Bearer ak_live_your_key_here'},
)
data = res.json()

Create a program

curl -X POST https://www.agentref.co/api/v1/programs \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner Program",
    "commissionType": "recurring",
    "commissionPercent": 25,
    "cookieDuration": 30,
    "payoutThreshold": 5000,
    "payoutFrequency": "monthly",
    "autoApproveAffiliates": true
  }'

const res = await fetch('https://www.agentref.co/api/v1/programs', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ak_live_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partner Program',
    commissionType: 'recurring',
    commissionPercent: 25,
    cookieDuration: 30,
    payoutThreshold: 5000,
    payoutFrequency: 'monthly',
    autoApproveAffiliates: true,
  }),
});
const program = await res.json();

import requests

res = requests.post(
    'https://www.agentref.co/api/v1/programs',
    headers={
        'Authorization': 'Bearer ak_live_your_key_here',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Partner Program',
        'commissionType': 'recurring',
        'commissionPercent': 25,
        'cookieDuration': 30,
        'payoutThreshold': 5000,
        'payoutFrequency': 'monthly',
        'autoApproveAffiliates': True,
    },
)
program = res.json()

Get stats

curl -X GET https://www.agentref.co/api/v1/programs/PROGRAM_ID/stats \
  -H "Authorization: Bearer ak_live_your_key_here"

const res = await fetch('https://www.agentref.co/api/v1/programs/PROGRAM_ID/stats', {
  headers: { Authorization: 'Bearer ak_live_your_key_here' },
});
const programStats = await res.json();

res = requests.get(
    'https://www.agentref.co/api/v1/programs/PROGRAM_ID/stats',
    headers={'Authorization': 'Bearer ak_live_your_key_here'},
)
program_stats = res.json()

For the complete API reference, see API Reference.

Copy for AI assistants

If your AI assistant does not support MCP, point it to https://www.agentref.co/docs/llms-full.txt first. That gives it the full published AgentRef documentation as plain Markdown.

Compact AgentRef context block for non-MCP chats

AgentRef docs: https://www.agentref.co/docs
Full docs for LLMs: https://www.agentref.co/docs/llms-full.txt
REST base URL: https://www.agentref.co/api/v1
MCP merchant endpoint: https://www.agentref.co/api/mcp/merchant
MCP affiliate endpoint: https://www.agentref.co/api/mcp/affiliate

Preferred MCP auth: OAuth 2.1 + dynamic client registration
Fallback MCP auth: Authorization: Bearer ak_live_* / ak_aff_*

Current MCP workflow groups:
- merchant_setup: get_onboarding_status, update_merchant_profile, create_program, list_programs, update_program, get_stripe_connect_url, complete_onboarding, get_tracking_snippet, verify_tracking
- merchant_growth: list_affiliates, list_applications, review_application, set_affiliate_status, list_invites, create_invite, revoke_invite, get_program_overview, list_conversions, list_flags, review_flag
- merchant_payouts: list_pending_payouts, list_payouts, list_upcoming_payouts, create_payout, update_payout_status, export_payouts_csv
- merchant_marketing_resources: list_marketing_resources, get_marketing_resource, create_marketing_collection, update_marketing_collection, publish_marketing_resource, unpublish_marketing_resource, archive_marketing_resource, create_marketing_social_post, update_marketing_social_post, create_marketing_social_post_media_upload_session, complete_marketing_social_post_media_upload, remove_marketing_social_post_media, update_marketing_social_post_media, reorder_marketing_social_post_media, replace_marketing_social_post_media, create_marketing_resource_download_url, create_marketing_external_link, create_marketing_upload_session, complete_marketing_upload_session, import_marketing_resource_from_url, notify_marketing_resource_affiliates
- affiliate_workspace: discover_programs, apply_to_program, get_affiliate_overview, list_my_programs, list_links, create_link, get_earnings, get_click_stats, list_my_payouts, update_my_payout_profile
- affiliate_marketing_resources: list_marketing_resources, get_marketing_resource, render_marketing_social_post, create_marketing_resource_download_url

Resources:
merchant://me
program://{id}
stats://{programId}
affiliate://me/programs
marketplace://catalog
marketing-resources://program/{program_id}
marketing-resource-collection://{collection_id}
marketing-resource://{resource_id}

Prompts:
onboard_program
review_payout_run
debug_tracking_installation
triage_fraud_flags

MCP workflow groups

AgentRef’s MCP release surface is organized into workflow groups with snake_case inputs and outputs. Mutation tools accept idempotency_key when retries need to be safe. MCP includes some workflows that are broader than REST/SDK, especially onboarding status, tracking snippet/verify, invite revoke, payout exports/status updates, and advanced Marketing Resources operations.

`merchant_setup`

get_onboarding_status
update_merchant_profile
create_program
list_programs
update_program
get_stripe_connect_url
complete_onboarding
get_tracking_snippet
verify_tracking

`merchant_growth`

list_affiliates
list_applications
review_application
set_affiliate_status
list_invites
create_invite
revoke_invite
get_program_overview
list_conversions
list_flags
review_flag

`merchant_payouts`

list_pending_payouts
list_payouts
list_upcoming_payouts
create_payout
update_payout_status
export_payouts_csv

`merchant_marketing_resources`

list_marketing_resources
get_marketing_resource
create_marketing_collection
update_marketing_collection
publish_marketing_resource
unpublish_marketing_resource
archive_marketing_resource
create_marketing_social_post
update_marketing_social_post
create_marketing_social_post_media_upload_session
complete_marketing_social_post_media_upload
remove_marketing_social_post_media
update_marketing_social_post_media
reorder_marketing_social_post_media
replace_marketing_social_post_media
create_marketing_resource_download_url
create_marketing_external_link
create_marketing_upload_session
complete_marketing_upload_session
import_marketing_resource_from_url
notify_marketing_resource_affiliates

`affiliate_workspace`

discover_programs
apply_to_program
get_affiliate_overview
list_my_programs
list_links
create_link
get_earnings
get_click_stats
list_my_payouts
update_my_payout_profile

`affiliate_marketing_resources`

list_marketing_resources
get_marketing_resource
render_marketing_social_post
create_marketing_resource_download_url

See MCP Server Deep Dive for the full tool, resource, prompt, and setup reference.

What’s next

MCP Server Deep Dive

Advanced MCP configuration, scopes, and resource access.

Node.js SDK

Full SDK reference with all methods and types.

Python SDK

Full SDK reference for Python integrations.

​Claude Code

​Claude App

​Codex

​Cursor

​OpenClaw (mcporter)

​OpenClaw REST skill (fallback)

​Other MCP clients

​Try it out

​Installation

​Configuration

​Create a program

​Invite an affiliate

​Check stats

​List conversions

​Installation

​Configuration

​Create a program

​Invite an affiliate

​Check stats

​List conversions

​List programs

​Create a program

​Get stats

​Copy for AI assistants

​MCP workflow groups

​merchant_setup

​merchant_growth

​merchant_payouts

​merchant_marketing_resources

​affiliate_workspace

​affiliate_marketing_resources

​What’s next

MCP Server Deep Dive

Node.js SDK

Python SDK

Claude Code

Claude App

Codex

Cursor

OpenClaw (`mcporter`)

OpenClaw REST skill (fallback)

Other MCP clients

Try it out

Installation

Configuration

Create a program

Invite an affiliate

Check stats

List conversions

Installation

Configuration

Create a program

Invite an affiliate

Check stats

List conversions

List programs

Create a program

Get stats

Copy for AI assistants

MCP workflow groups

`merchant_setup`

`merchant_growth`

`merchant_payouts`

`merchant_marketing_resources`

`affiliate_workspace`

`affiliate_marketing_resources`

What’s next