> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Setup

> Connect AgentRef to AI assistants via MCP server, Node.js SDK, Python SDK, or REST API – manage your affiliate program through natural language.

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.

<Tabs>
  <Tab title="MCP Server">
    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/merchant`

    **Affiliate server URL:** `https://www.agentref.co/api/mcp/affiliate`

    **Recommended auth:** MCP OAuth 2.1 with dynamic client registration

    **Fallback auth for custom clients:** `Authorization: Bearer ak_live_your_key_here`

    ### Claude Code

    ```bash theme={null}
    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

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

    ### Codex

    Copy this prompt into Codex:

    ```text theme={null}
    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:

    ```bash theme={null}
    codex mcp login agentref-merchant
    ```

    ### Cursor

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

    ```json theme={null}
    {
      "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:

    ```bash theme={null}
    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:

    ```bash theme={null}
    openclaw skills install agentref
    ```

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

    ```bash theme={null}
    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"
  </Tab>

  <Tab title="Node.js SDK">
    The Node.js SDK provides a type-safe client for all AgentRef API operations.

    ### Installation

    ```bash theme={null}
    npm install agentref
    ```

    ### Configuration

    ```typescript theme={null}
    import { AgentRef } from 'agentref';

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

    <Warning>
      Store your API key in environment variables, not in source code. Use `process.env.AGENTREF_API_KEY` in production.
    </Warning>

    ### Create a program

    ```typescript theme={null}
    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

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

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

    ### Check stats

    ```typescript theme={null}
    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

    ```typescript theme={null}
    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](/agent-integration/node-sdk).
  </Tab>

  <Tab title="Python SDK">
    The Python SDK provides a clean client for all AgentRef API operations.

    ### Installation

    ```bash theme={null}
    pip install agentref
    ```

    ### Configuration

    ```python theme={null}
    from agentref import AgentRef

    client = AgentRef(api_key='ak_live_your_key_here')
    ```

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

    ### Create a program

    ```python theme={null}
    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

    ```python theme={null}
    invite = client.programs.create_invite(
        program.id,
        email='partner@example.com',
    )

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

    ### Check stats

    ```python theme={null}
    stats = client.programs.stats(
        program.id,
        period='30d',
    )

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

    ### List conversions

    ```python theme={null}
    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](/agent-integration/python-sdk).
  </Tab>

  <Tab title="REST API">
    If you're not using an SDK or MCP, you can call the REST API directly.

    **Base URL:** `https://www.agentref.co/api/v1`

    **Auth:** Pass your API key as a Bearer token in the `Authorization` header.

    ### List programs

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET https://www.agentref.co/api/v1/programs \
        -H "Authorization: Bearer ak_live_your_key_here"
      ```

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

      ```python requests theme={null}
      import requests

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

    ### Create a program

    <CodeGroup>
      ```bash cURL theme={null}
      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
        }'
      ```

      ```javascript fetch theme={null}
      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();
      ```

      ```python requests theme={null}
      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()
      ```
    </CodeGroup>

    ### Get stats

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET https://www.agentref.co/api/v1/programs/PROGRAM_ID/stats \
        -H "Authorization: Bearer ak_live_your_key_here"
      ```

      ```javascript fetch theme={null}
      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();
      ```

      ```python requests theme={null}
      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()
      ```
    </CodeGroup>

    For the complete API reference, see [API Reference](/api-reference/authentication).
  </Tab>
</Tabs>

## 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.

<Accordion title="Compact AgentRef context block for non-MCP chats">
  ```text theme={null}
  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
  ```
</Accordion>

## 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](/agent-integration/mcp-server) for the full tool, resource, prompt, and setup reference.

## What's next

<CardGroup cols={3}>
  <Card title="MCP Server Deep Dive" icon="robot" href="/agent-integration/mcp-server">
    Advanced MCP configuration, scopes, and resource access.
  </Card>

  <Card title="Node.js SDK" icon="js" href="/agent-integration/node-sdk">
    Full SDK reference with all methods and types.
  </Card>

  <Card title="Python SDK" icon="python" href="/agent-integration/python-sdk">
    Full SDK reference for Python integrations.
  </Card>
</CardGroup>