MCP Server

@affitor/mcp is a Model Context Protocol stdio server for Affitor. It exposes Affitor's affiliate-tracking capabilities as MCP tools, so an AI agent — Claude Desktop, Cursor, or any MCP client — can report clicks, leads, sales and refunds, fetch a per-stack integration plan, and prove attribution works, all as native tool calls.

Under the hood it wraps the consolidated server client @affitor/sdk/server (the Affitor class). Authentication is your program API key, supplied via the AFFITOR_API_KEY environment variable.

Install as a pluginCopy Anchor Link

In Claude Code and Gemini CLI, the plugin is the quickest way to install. It bundles the MCP server with Affitor's integration guide (a skill in Claude Code, a context file in Gemini CLI). Claude Code asks for your program API key when you enable the plugin; Gemini CLI asks during installation.

/plugin marketplace add Affitor/claude-plugins
/plugin install affitor@affitor

Run the Claude Code commands inside a Claude Code session. Claude Code keeps the key in secure storage, and Gemini CLI keeps it in the system keychain. Source: github.com/Affitor/claude-plugins.

The server is also listed in the Official MCP Registry as com.affitor/mcp, so clients that browse the registry can find it there.

Add it to your MCP clientCopy Anchor Link

For any other client, or to configure it yourself, pick your client below. Every option runs the same local server with npx -y @affitor/mcp and passes your program API key as AFFITOR_API_KEY. Replace your_program_key with your key.

claude mcp add affitor --env AFFITOR_API_KEY=your_program_key -- npx -y @affitor/mcp

Where each JSON goes:

• Claude Desktop: claude_desktop_config.json, in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows.
• Cursor: .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project.
• VS Code: .vscode/mcp.json in your project. VS Code asks for the key once and stores it securely.
• Other clients (Windsurf, Cline and most others): the client's MCP config file, in the same mcpServers shape.

Restart your client (or reload its MCP servers) and the affitor_* tools become available to the agent. To let the agent report sales and refunds, also add "AFFITOR_MCP_WRITE": "1" to env (see below).

Environment variablesCopy Anchor Link

If AFFITOR_API_KEY is not set, the server prints a clear message to stderr and exits.

ToolsCopy Anchor Link

The server registers five tools by default, and seven with AFFITOR_MCP_WRITE=1. Each returns the Affitor API's JSON payload as text content; a failed request (a thrown error or an { ok: false } envelope) returns an MCP error result with the message.

Tracking tool inputsCopy Anchor Link

affitor_track_lead — one of customerExternalId / clickId is required:

• customerExternalId?: string — your own user id; binds this customer to the click.
• clickId?: string — Affitor click id (from the affitor_click_id cookie).
• email?: string — the lead's email address.
• testMode?: boolean: record a test lead (flagged is_test) instead of a real one.

affitor_track_sale — one of customerExternalId / clickId is required:

• customerExternalId?: string — your own user id; resolves attribution (no clickId needed once bound at lead time).
• clickId?: string — Affitor click id.
• amount: number — sale amount in integer cents (e.g. 4999 = $49.99).
• invoiceId: string — idempotency key; dedups retries (your invoice / transaction id).
• currency?: string — USD, EUR, or VND; other codes are not supported. Defaults to USD. Amounts are not converted between currencies: commissions and platform fees are calculated on the amount as sent, and invoices are issued in USD.
• saleType?: "payment" | "subscription" — one-off payment or subscription.
• isRecurring?: boolean — whether this sale recurs (subscription renewal).
• subscriptionId?: string — provider subscription id, if applicable.
• subscriptionInterval?: "monthly" | "quarterly" | "annual" — billing interval for a subscription sale.
• testMode?: boolean: record a test sale (flagged is_test) that creates no commission. Leave it off for a real sale.

affitor_track_refund:

• invoiceId: string — the sale's idempotency key (the invoiceId you passed to affitor_track_sale).
• refundAmountCents?: number — integer cents, this refund's own amount (not a running total). Omit (or 0) = refund everything not yet refunded → commission reversed; otherwise added to earlier refunds → refunded until the total reaches the sale amount.
• refundReason?: string — optional human-readable refund reason.
• testMode?: boolean: a dry run that returns the refund that would be sent and calls nothing. The API has no test mode for refunds.

affitor_track_click — all optional:

• affiliateUrl?: string — the affiliate/referral URL that was clicked.
• pageUrl?: string — the landing page URL the click arrived on.
• referrerUrl?: string — the HTTP referrer URL, if any.
• existingClickId?: string — reuse an existing Affitor click id instead of minting a new one.

affitor_get_integration_planCopy Anchor Link

A pure tool: it reads the canonical recipe registry (@affitor/recipes) and returns the deterministic integration plan for a given stack. It never touches the network or the client — so the agent follows a fixed contract instead of guessing one.

The plan it returns includes:

1. install — what to add (npm i @affitor/sdk).
2. metadata — the checkout-session attribution snippet to plant at checkout creation (always required for Stripe).
3. sale — the trackSale snippet and exactly where to inject it. For mode: "stripe_connect" this is null — Stripe Connect records the sale server-side, so the agent injects metadata only and must not also call trackSale (the double-count guard).
4. renewals — for Stripe s2s, a separate case 'invoice.paid' handler so subscription renewals are not silently missed.
5. verify — the self-verify step (synthetic chain → readiness gate).

affitor_run_verificationCopy Anchor Link

The agent's proof step. It fires Affitor's synthetic click → lead → sale chain through the real attribution pipeline, writing isolated is_test rows that never create real commissions. Run it, then poll affitor_readiness until integration_verified: true.

The recommended agent loop:

1. Call affitor_run_verification to fire the chain.
2. Call affitor_readiness and check integration_verified.
3. If not yet verified, read the blocker and its gate's next_action, self-correct, and repeat.

RelatedCopy Anchor Link

• Agent Integration — how AI agents auto-install tracking from generated AGENTS.md instruction files.
• CLI Command Reference — npx affitor onboard, the one-shot equivalent of the MCP flow.
• SDK Reference — the @affitor/sdk package the MCP server wraps.
• Track Sale — the full API contract behind affitor_track_sale.