Connect Dub to Claude: Oversee Partner Programs and Commissions

If your team uses ChatGPT, check out our guide on connecting Dub to ChatGPT or explore our broader architectural overview on connecting Dub to AI Agents.

Managing partner programs, affiliate links, and commission payouts across a sprawling B2B ecosystem requires constant vigilance. Link infrastructure platforms like Dub provide powerful REST APIs to handle these operations programmatically. However, giving a Large Language Model (LLM) like Claude read and write access to your Dub workspace is an entirely different engineering challenge.

You cannot just hand an LLM an API key and expect it to manage thousands of short links and financial commissions reliably. You need a translation layer. This is where the Model Context Protocol (MCP) comes in. An MCP server acts as the intermediary between Claude's tool calling capabilities and Dub's specific API architecture.

You have two choices: spend weeks building, hosting, and updating a custom MCP server to handle OAuth, pagination, and schema mapping, or use a managed infrastructure layer. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Dub, connect it natively to Claude, and execute complex partner program workflows using natural language.

The Engineering Reality of the Dub API

A custom MCP server is a self-hosted integration layer. While Anthropic's MCP provides a standardized way for models to discover tools, implementing it against specific vendor APIs exposes the harsh realities of those underlying systems.

If you decide to build a custom MCP server for Dub, you own the entire integration lifecycle. You are not just building a wrapper; you are building an operational system that must handle Dub's specific architectural quirks. Here are the specific challenges you will face when connecting AI agents to Dub:

Mutating Analytics Schemas Dub's analytics API is incredibly powerful, but its response schema mutates entirely based on your query parameters. If you call the analytics endpoint grouped by country, the JSON response is shaped one way. If you group by timeseries, the structure changes completely, introducing different nested objects and data types. LLMs struggle with mutating return schemas. If you expose this raw endpoint to Claude, the model will frequently hallucinate data paths or fail to parse the response. Your MCP server must dynamically map these responses into predictable, standardized tool schemas so Claude knows exactly what data it is receiving.

Silent Failures on Bulk Operations Dub provides highly efficient bulk operations, such as dub_links_bulk_create and dub_links_bulk_update, allowing you to modify up to 100 links per request. However, there is a massive operational gotcha: these bulk endpoints explicitly bypass Dub's webhook system. If your AI agent uses a bulk tool to migrate an entire marketing campaign, your downstream CRM or data warehouse will not receive any webhook notifications. If you build this yourself, you have to write explicit compensation logic within your MCP server to manually trigger downstream syncs after bulk operations.

Destructive Domain Cascades Domain management in Dub is strict. If an agent calls the endpoint to delete a domain, it is an irreversible action that permanently destroys every single short link associated with that domain. Handing this level of raw, destructive access to an autonomous agent is a recipe for catastrophic data loss without strict method filtering and role-based access control built directly into the MCP layer.

Rate Limits and 429 Errors Dub enforces strict rate limits on its API. It is critical to understand how Truto handles this: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Dub API returns an HTTP 429 Too Many Requests error, Truto passes that error directly to the caller. What Truto does do is normalize the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - in this case, the Claude client or your multi-agent framework - is entirely responsible for detecting the 429 error, reading the reset header, and executing the retry and backoff logic. Do not assume your MCP layer will magically absorb rate limit errors for you.

How to Generate a Dub MCP Server with Truto

Instead of building schema mappers and authentication middleware from scratch, Truto dynamically generates an MCP server directly from your connected Dub account. This server exposes Dub's endpoints as strongly typed tools that Claude can consume immediately.

Every Truto MCP server is scoped to a single integrated account (a specific tenant's connection to Dub) and secured by a cryptographically hashed token.

You can create this server using either the Truto UI or the REST API.

Method 1: Via the Truto UI

For ad-hoc agent testing or internal operations, the visual dashboard is the fastest route:

1. Log into your Truto account and navigate to the Integrated Accounts page.
2. Select your active Dub connection.
3. Click the MCP Servers tab.
4. Click the Create MCP Server button.
5. Configure your access controls. You can restrict the server to specific tags (like commissions or analytics), limit it to read methods only, and set an expiration date.
6. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz...).

Method 2: Via the Truto API

If you are provisioning AI workspaces programmatically, you should generate the MCP server via the Truto API. This creates a secure token stored in Cloudflare KV, returning a ready-to-use endpoint.

Send an authenticated POST request to the Truto API:

// POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp
 
const response = await fetch(
  'https://api.truto.one/integrated-account/ia_dub_789/mcp',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TRUTO_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Claude Partner Operations Agent",
      config: {
        methods: ["read", "write"], 
        tags: ["commissions", "analytics", "links"]
      },
      expires_at: "2026-12-31T23:59:59Z"
    })
  }
);
 
const mcpServer = await response.json();
console.log(mcpServer.url); 
// Yields: https://api.truto.one/mcp/your_secure_token_here

How to Connect the Dub MCP Server to Claude

Once you have your Truto MCP server URL, connecting it to Claude requires zero additional coding. The URL encapsulates the authentication, tenant routing, and tool definitions.

Method 1: Via the Claude Desktop UI

If you are using the Claude Desktop application for local agent workflows:

1. Open Claude Desktop.
2. Navigate to Settings -> Integrations -> Add MCP Server.
3. Paste the Truto MCP URL into the Server URL field.
4. Click Add.

Claude will immediately ping the /initialize endpoint, perform the JSON-RPC handshake, and load all permitted Dub tools into its context window.

Method 2: Via Manual Configuration File

If you are running Claude Desktop in a customized environment or using a headless MCP client, you can connect via the standard configuration file (claude_desktop_config.json).

Because Truto exposes MCP over HTTP using Server-Sent Events (SSE), you need to use the official @modelcontextprotocol/server-sse transport adapter.

Add this block to your configuration file:

{
  "mcpServers": {
    "dub_partner_ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/your_secure_token_here"
      ]
    }
  }
}

Restart Claude Desktop. The agent will read the config, launch the SSE transport proxy, and establish a connection to your Dub workspace.

Hero Tools for Dub Partner Operations

Truto automatically derives tool descriptions and JSON schemas from Dub's API documentation. Here are the most powerful tools available for overseeing partner programs and analyzing link performance.

List All Dub Commissions

This tool retrieves the full ledger of partner commissions. It returns structured data containing the id, amount, earnings, status, partner, and associated customer for each commission. You can filter the results by specific partners, payout IDs, or date ranges.

Contextual Usage: Use this tool to audit pending payouts before the end of the financial month, or to identify anomalies in affiliate earnings.

"Fetch all pending commissions for partner ID prt_98765 generated in the last 30 days. Summarize the total pending earnings."

Update a Dub Commission By ID

Paid commissions are immutable, but pending commissions can be updated. This tool allows the agent to modify a commission's status or details based on downstream events, such as processing partial refunds or rejecting fraudulent sales.

Contextual Usage: Essential for automated fraud mitigation workflows. If your billing system detects a chargeback, the agent can immediately mark the corresponding affiliate commission as rejected to prevent revenue leakage.

"The customer associated with commission ID comm_44556 just issued a chargeback. Update this commission status to rejected and leave a note regarding the fraudulent sale."

Create a Dub Partner

This tool handles partner upserts. If you pass an email address that already belongs to a partner, it updates their program enrollment. If they do not exist, it creates a new partner profile and generates their unique tenantId and referral links.

Contextual Usage: Use this to automate affiliate onboarding. When a user fills out a partner application form, Claude can provision their Dub account automatically.

"We have a new approved affiliate. Upsert a partner record for alex@example.com and return their new partner link."

List All Dub Analytics

This is the most complex data retrieval tool. It pulls analytics for a specific link, domain, or the entire workspace. It accepts parameters like event (clicks, leads, sales) and groupBy (countries, devices, timeseries) to shape the return data.

Contextual Usage: Perfect for generating weekly campaign reports. Claude can pull timeseries data, analyze traffic spikes, and summarize the top performing geographic regions for specific affiliate links.

"Retrieve the click analytics for the domain 'promo.ourbrand.com' over the last 7 days, grouped by country. Tell me which three countries drove the most traffic."

Dub Links Bulk Create

This tool allows the agent to generate up to 100 short links in a single POST request. It returns an array of the created link objects, including their respective id and shortLink URLs.

Contextual Usage: High-leverage marketing operations. Remember that bulk endpoints bypass webhooks in Dub, so use this when you need pure speed and do not rely on event-driven downstream architectures.

"I have a list of 50 new blog post URLs. Bulk create short links for all of them under our primary workspace domain, and apply the tag 'q4-content' to every link."

Create a Dub Track Sale

This tool associates a financial conversion with a previously tracked short link click. It requires the customerExternalId and the amount of the sale. It returns the event metadata and payment processor details.

Contextual Usage: Closing the loop on revenue attribution. When your payment gateway clears a transaction, Claude can push that sale data directly into Dub to ensure accurate partner commission calculations.

"Log a new sale event for customer ID ext_505. The sale amount is $150 USD processed via Stripe. Track this so the referring partner gets credited."

For the complete inventory of Dub tools, including folder management, custom domain configuration, and granular link tag controls, visit the Dub integration page.

Workflows in Action

Giving Claude access to these tools transforms it from a chatbot into a competent partner operations manager. Here is how specific personas can use this architecture to execute multi-step workflows.

Workflow 1: The End-of-Month Affiliate Audit

Persona: Affiliate Manager / Revenue Operations

Affiliate payouts are notoriously prone to margin erosion due to refunded sales that slip through the cracks. Revenue operations teams spend hours manually cross-referencing billing platforms with partner ledgers.

"Audit all pending commissions for our Q3 Partner Program. Cross-reference them against the recent refund list I just pasted. If any commission is tied to a refunded customer, update that commission to rejected."

Execution Steps:

1. Claude calls list_all_dub_commissions filtered by status: pending.
2. The model analyzes the returned array, comparing the customerId fields against the provided refund list.
3. For every match, Claude executes a loop, calling update_a_dub_commission_by_id to change the status to rejected, ensuring the company does not pay out commissions on refunded revenue.
4. Claude returns a text summary of the rejected commissions and the total amount of capital saved.

Workflow 2: Rapid Campaign Expansion

Persona: Growth Marketer

When a new feature launches, growth teams need dozens of tracked links generated instantly for different distribution channels (Twitter, LinkedIn, newsletters, partner emails), all properly tagged and attributed.

"We are launching the 'Auto-Sync' feature tomorrow. Take this list of 40 tracking URLs for our various social channels and affiliates. Bulk create Dub links for all of them, tag them with 'launch-day', and then pull the current baseline analytics for our main domain so we can compare traffic tomorrow."

Execution Steps:

1. Claude parses the list of 40 URLs.
2. Claude calls dub_links_bulk_create, passing the array of URLs and the tags: ['launch-day'] parameter.
3. Claude receives the response containing the 40 new shortLink URLs.
4. Claude then calls list_all_dub_analytics on the primary workspace domain, grouped by timeseries for the last 24 hours, to establish the baseline traffic.
5. Claude outputs a formatted markdown table containing the new short links alongside a summary of the baseline traffic data.

Security and Access Control

Exposing your affiliate ledger and core link infrastructure to an LLM requires strict security boundaries. Truto MCP servers enforce governance at the infrastructure level, preventing prompt injection attacks from executing unauthorized operations.

• Method Filtering: You can configure the MCP server to only allow read methods. This ensures the AI agent can audit commissions and pull analytics, but cannot update payouts or create links, acting as a strict safety net for junior teams.
• Tag Filtering: By restricting the server to specific tool tags (e.g., analytics), you isolate the agent's blast radius. If the agent gets confused, it physically does not possess the tools to interact with partner ledgers or domains.
• Require API Token Auth: By setting require_api_token_auth: true during server creation, you force the client to pass a valid Truto API token in the Authorization header. This means possessing the MCP URL alone is useless; the caller must be explicitly authenticated in your system.
• Ephemeral Servers (Expires At): You can set an expires_at datetime when generating the server. Once the timestamp passes, Truto's Durable Object alarms automatically purge the token from Cloudflare KV and the database, instantly revoking Claude's access to Dub.

Building partner program automation shouldn't require maintaining endless boilerplate for JSON schema mapping and pagination logic. By utilizing a managed MCP server, your engineering team can focus on designing complex, revenue-saving workflows while the infrastructure handles the messy reality of vendor APIs.