# MCP tools, scopes and REST API

> Every InfluTo MCP tool, the permission scopes an agent can be granted, and the /api/agent REST endpoints behind them — with auth, limits and error codes.

This is the reference for agents connected to `https://influ.to/mcp`. The tools that read or change your account call the agent REST API under `/api/agent`, so you can use either — same authentication, same permissions, same organization boundaries. The discovery and scaffold tools answer from the SDK registry without touching your account.

The MCP resource `influto://tools` always lists the live set of tools, generated by the server. Two more resources carry reference material: `influto://contract` (the SDK wire contract) and `influto://sdk/{platform}` (each SDK's reference).

## Authentication

- **OAuth 2.1** (what MCP clients use): discovery, dynamic client registration and a PKCE browser consent where you choose the organization and permissions. Access tokens last up to an hour and refresh automatically.
- **Agent keys** `it_mcp_…`: created on **Connect AI Agent** in the dashboard, shown once, revocable. Send `Authorization: Bearer <key>`.

The app's SDK key (`it_…`) doesn't work here, and the dashboard's own API (`/api/apps/…` without `/agent/`) only accepts a signed-in browser session — an agent calling it gets `401` by design.

## Scopes

| Scope | Grants |
|---|---|
| `apps:read` | List and inspect your apps and their integration status |
| `apps:write` | Create and update apps (names, links, creator-code settings) |
| `campaigns:read` | View campaigns, milestones and settings |
| `campaigns:write` | Create and update campaigns, bonuses, and their status |
| `analytics:read` | Read clicks, installs, trials, conversions and revenue analytics |
| `creators:read` | List creators, invitations and access codes |
| `creators:write` | Invite creators and create free-access codes |
| `assets:read` | List marketing assets and content examples |
| `assets:write` | Feature/unfeature assets (uploads stay in the dashboard) |
| `billing:read` | See wallet balance and reserved funds (read-only) |
| `integration:verify` | Run integration checks and sandbox test events |

New keys and OAuth connections get all of these by default; you can untick any on the consent page.

Denied to every agent whatever it's granted: moving money (top-ups, transfers), payouts, raw credentials, deleting data, and admin. These go through dashboard links the human opens while signed in.

## Tools (58)

### Discovery (4)

Pure lookups — which SDK, which validation path, which invariant.

- `influto_list_sdks` — The five SDKs (React Native, iOS, Android, Flutter, Web) with package id, registry, repo and current version.
- `influto_recommend_sdk` — Free-text stack ('expo', 'swiftui', 'kotlin', …; platform/hostStack/framework/language/sdkId accepted as aliases) → the ONE SDK + peer deps.
- `influto_recommend_validation` — Pick the ONE validation path: RevenueCat webhook vs store-direct (never both).
- `influto_explain_contract` — Wire-contract invariants per topic: attribution, purchase, comp, dedup, rc-attributes.

### Scaffold (6)

Version-correct code snippets straight from the SDK registry.

- `influto_scaffold_install` — Install command(s) + peer dependencies for an SDK.
- `influto_scaffold_init` — The one-time initialize() snippet (THROWS on failure — surface it).
- `influto_scaffold_attribution` — The checkAttribution() launch snippet.
- `influto_scaffold_manual_code` — Optional manual referral-code entry / ReferralCodeInput snippet.
- `influto_scaffold_report_purchase` — Store-direct purchase-reporting snippet (skip on the RevenueCat path).
- `influto_scaffold_full` — One call → the exact ordered integration steps for a stack + validation path.

### Provision (7)

Stand up the account side: org → app (+ API key) → campaign.

- `influto_whoami` — The developer + organizations behind the connected agent.
- `influto_create_org` — Create an organization (only when whoami shows none).
- `influto_search_store` — Search the App Store + Google Play for an app's store identifiers.
- `influto_scrape_store` — Scrape store metadata incl. the numeric Apple app_store_id.
- `influto_check_slug` — Is an app slug free? (Slugs are globally unique — first segment of referral URLs.)
- `influto_provision` — Org → app (+ API key + webhook secret) → campaign → activate, in one idempotent call.
- `influto_regenerate_webhook_secret` — Rotate the RevenueCat webhook secret (returned once).

### Configure (7)

Wire the purchase-validation path; secrets go through a dashboard link the human opens.

- `influto_get_validation_status` — Per-platform validation config + what's missing (non-secret).
- `influto_setup_revenuecat` — Auto-wires the RevenueCat webhook inside the developer's RC project (autowire=true by default, using the stored v2 secret key); falls back to exact dashboard_steps.
- `influto_get_credential_upload_link` — Dashboard link the HUMAN opens (signed in) to upload credentials — secrets never transit the agent.
- `influto_set_apple_meta` — Non-secret Apple identifiers: Issuer ID, Key ID, environment, App Store ID.
- `influto_validate_store_credentials` — Run the live credential green-check (loop while retryable).
- `influto_activate_store_direct` — Flip a platform to store-direct once the green-check passed.
- `influto_recommend_validation_for_platforms` — Which path to wire and what it needs (configure-flow reminder).

### Verify (4)

The differentiator: prove a real ATTRIBUTED conversion happened.

- `influto_integration_status` — THE verify rollup: {live, checklist[], attributed_conversion_count, campaign health, …}.
- `influto_recent_events` — Recent SDK events + purchase webhooks with attribution flags (SANDBOX/PRODUCTION filter).
- `influto_test_integration` — Fire a SANDBOX INITIAL_PURCHASE through the real attribution pipeline.
- `influto_verify_user_conversions` — Did a specific app_user_id's purchases attribute?

### Operate (14)

Run the program: apps, campaigns (milestone bonuses + i18n), awards, analytics.

- `influto_list_apps` — Every app across the developer's orgs, with canonical click totals.
- `influto_get_app` — Full app detail incl. *_i18n maps, support_email and creator-code settings.
- `influto_update_app` — Update whitelisted app settings (name_i18n / description_i18n / tagline_i18n merge and mark those locales fresh; editing name/description marks translations stale; credentials excluded).
- `influto_list_campaigns` — Campaigns by app/status with canonical clicks + milestone counts.
- `influto_get_campaign` — Full campaign: commission, bonus_rules, i18n copy, stats.
- `influto_create_campaign` — Full-featured create incl. milestone bonus_rules + i18n (created as DRAFT).
- `influto_update_campaign` — Update a campaign — same surface as create (editing name/description marks existing translations stale).
- `influto_set_campaign_status` — Activate/pause; activation enforces the prepaid wallet minimum (402 → top-up link).
- `influto_list_bonus_awards` — Milestone awards with creator identity + live fraud-aware progress.
- `influto_review_bonus_award` — Approve or void an earned milestone award (pre-payout only).
- `influto_get_analytics_overview` — Per-app period rollup: canonical clicks (+ decomposition), installs, trials, conversions, revenue, commission.
- `influto_get_campaign_funnel` — Clicks → installs → trials → paid with step rates (find the leak).
- `influto_list_top_affiliates` — Top creators by period revenue for an app or campaign.
- `influto_get_daily_performance` — Zero-filled daily series for trend checks and charts.

### Grow (16)

Recruit and reward creators; read-only wallet visibility; the doctor.

- `influto_list_affiliates` — Every creator in a campaign: codes, canonical clicks, earnings, milestone progress, INFLU- code state.
- `influto_invite_creator` — Invite one creator by email (localized invitation + personal message; optional custom commission).
- `influto_invite_creators_batch` — Bulk-invite from a list/CSV — live capacity accounting, per-item results, partial success.
- `influto_withdraw_invitation` — Withdraw a PENDING invite (frees a marketplace capacity slot).
- `influto_get_join_link` — The shareable public join-page URL (?lang=xx, OG card) + readiness warnings.
- `influto_list_invitations` — Invitation states across campaigns (default: still pending).
- `influto_list_free_codes` — Free-access codes incl. platform-issued INFLU- creator codes + redemption state.
- `influto_create_free_code` — Mint a comp/free-access code (ambassadors, press, VIPs) — no purchase needed.
- `influto_list_assets` — Marketing assets creators use for content (filter by type/category).
- `influto_set_asset_featured` — Curate which assets show as join-page content examples.
- `influto_get_asset_upload_link` — Dashboard link the HUMAN opens (signed in) to upload asset files.
- `influto_get_wallet` — READ-ONLY wallet snapshot: balance, reserved, safe_available, can_activate_campaigns, and invite_capacity (marketplace slots + daily email budget) — read before inviting.
- `influto_get_wallet_topup_link` — Link to the billing page — the HUMAN, signed in, completes the Stripe checkout.
- `influto_localize_campaign` — Localize campaign copy, stale-aware: refreshes only missing/stale locales unless forced (server translator, or hands the copy back for the agent to translate + write back).
- `influto_localize_app` — Localize app name/description/tagline, stale-aware (server translator, or hands the copy back for the agent to translate + write back via influto_update_app).
- `influto_doctor` — Auth mode, principal, scopes, orgs, per-app freshness — call FIRST when anything misbehaves.

## REST endpoints

Base URL `https://influ.to`. Machine-readable spec: [influ.to/api/agent/openapi.json](https://influ.to/api/agent/openapi.json).

**Identity & provision**

```http
GET  /api/agent/whoami
GET  /api/agent/doctor
POST /api/agent/organizations
GET  /api/agent/store/search · GET /api/agent/store/scrape
GET  /api/agent/apps/check-slug/{slug}
POST /api/agent/provision
POST /api/agent/apps/{app_id}/regenerate-webhook-secret
```

**Configure validation**

```http
GET  /api/agent/apps/{app_id}/validation-status
POST /api/agent/apps/{app_id}/credential-setup-link
PATCH /api/agent/apps/{app_id}/apple-meta
POST /api/agent/apps/{app_id}/validate-store-credentials
POST /api/agent/apps/{app_id}/activate-store-direct
```

**Verify (the loop)**

```http
GET  /api/agent/apps/{app_id}/integration-status
GET  /api/agent/apps/{app_id}/events/recent
POST /api/agent/apps/{app_id}/test-integration
GET  /api/agent/apps/{app_id}/verify-user-conversions?app_user_id=…
```

**Operate (apps · campaigns · bonuses · analytics)**

```http
GET  /api/agent/apps · GET/PATCH /api/agent/apps/{app_id}
GET  /api/agent/campaigns · GET/PATCH /api/agent/campaigns/{campaign_id}
POST /api/agent/apps/{app_id}/campaigns
POST /api/agent/campaigns/{campaign_id}/status
GET  /api/agent/bonus-awards · POST /api/agent/bonus-awards/{award_id}/review
GET  /api/agent/apps/{app_id}/analytics/overview
GET  /api/agent/campaigns/{campaign_id}/funnel
GET  /api/agent/analytics/top-affiliates
GET  /api/agent/campaigns/{campaign_id}/daily-performance
```

**Grow (creators · codes · assets · wallet)**

```http
GET  /api/agent/campaigns/{campaign_id}/affiliates
POST /api/agent/campaigns/{campaign_id}/invite
GET  /api/agent/campaigns/{campaign_id}/join-link
GET  /api/agent/invitations
GET/POST /api/agent/apps/{app_id}/free-codes
GET  /api/agent/apps/{app_id}/assets · POST /api/agent/assets/{asset_id}/featured
POST /api/agent/apps/{app_id}/asset-upload-link
GET  /api/agent/wallet · POST /api/agent/wallet/topup-link
POST /api/agent/campaigns/{campaign_id}/localize
POST /api/agent/apps/{app_id}/localize
```

## Limits and errors

| Status | Meaning |
|---|---|
| `401` | Missing, expired or revoked token or key |
| `402` | Wallet balance too low for the action (activate a campaign, invite creators) — get a top-up link with `influto_get_wallet_topup_link` |
| `403` | The token lacks a scope; the error names it |
| `404` | Not found — also returned for IDs in organizations you didn't grant, so nothing leaks about other accounts |
| `429` | More than 240 tool calls per minute for one connection |

More limits across the platform: [Limits and errors](https://docs.influ.to/reference/limits-and-errors.md).