Docs

MCP: an AI assistant in the tracker

Starting with version 0.9.5.0 you can connect an AI assistant (Claude Desktop and other MCP clients) to Orbitra through the MCP server โ€” it lives in the mcp/ folder. Once connected, the tracker can be driven in plain language:

"How did my campaigns do over the last 7 days?"
"Create 10 campaigns for offer #4 โ€” one per GEO: US, CA, GB, DE, FR."
"Add the domain track.example.com and put campaign 12 on its root."

The server talks to your tracker over HTTPS using a personal API key. It stores nothing on its own side, and read-only keys physically cannot modify data.

How it works

Claude Desktop  โ”€โ”€stdioโ”€โ”€โ–บ  mcp/src/index.js  โ”€โ”€HTTPS + API keyโ”€โ”€โ–บ  ะฒะฐัˆ Orbitra (api.php)

The MCP server is a thin client over the tracker's regular API (api.php). It simply wraps API actions into tools an AI can understand and adds a safeguard (read keys cannot write).

Step 1. Get an API key

In the panel: โš™ โ†’ AI / MCP or โš™ โ†’ Users โ†’ API keys (keys are created by an admin).

The key is shown once โ€” copy it.

Step 2. Install dependencies

When installed via install.sh, MCP dependencies are installed automatically. Manually:

cd mcp
npm install

Self-check (starts the server and prints the tool list; no live tracker needed):

npm run smoke

Checking against a live tracker:

ORBITRA_URL=https://tracker.example.com ORBITRA_API_KEY=your_key npm run smoke -- --ping

Step 3. Connect Claude Desktop

The Claude Desktop config file:

Option A. Remote connection by URL (since version 0.9.6.2)

The fastest option, and the only one that works in the browser version of Claude: the tracker itself serves MCP over HTTP through mcp.php.

  1. โš™ โ†’ Users โ†’ API keys, create a key (Read โ€” analytics only, Write โ€” plus management).
  2. Click the link button next to the key โ€” a ready-made URL is copied to the clipboard:
https://ะฒะฐัˆ-ั‚ั€ะตะบะตั€.example.com/mcp.php?k=ะ’ะะจ_ะšะ›ะฎะง
  1. In Claude: Settings โ†’ Connectors โ†’ Add custom connector, paste the URL, set a name, "Add".

Nothing to install โ€” neither Node nor the repository on your machine.

๐Ÿ”‘ The key travels right inside the URL, because the connector dialog has no field for a key and only supports OAuth. Treat such a URL as a password: do not publish it, and to cut off access delete the key in โš™ โ†’ Users โ†’ API keys โ€” the URL stops working immediately. A read key physically cannot change anything.

How it works. mcp.php implements sessionless MCP Streamable HTTP: every POST is a self-contained JSON-RPC exchange. It takes the tool list from mcp/tools.json, which is generated from the Node server (node mcp/src/manifest.js), so both connection types show exactly the same set of 41 tools. A tool call runs as a short CLI process cli/api_invoke.php โ€” the tracker does not call itself over HTTP, which on a VPS with two PHP-FPM workers could otherwise block the whole site.

Requirements: PHP CLI (already needed for cron) and proc_open allowed. If proc_open is disabled in php.ini, the endpoint will tell you so in plain text โ€” use option B in that case. The PHP path can be set manually via the mcp_php_binary setting.

Option B. Local server for Claude Desktop

โš ๏ธ This is not the "Add custom connector" dialog. The Connectors section in Claude only accepts remote MCP servers over HTTPS and authorizes them via OAuth โ€” that is why there is no API key field there. The Orbitra server runs over stdio: it starts locally next to the assistant and is registered in the config file below. A tracker URL pasted into the connector dialog will not work.

You can open the file right from the app: Settings โ†’ Developer โ†’ Edit Config.

Add an orbitra server (use the absolute path to mcp/src/index.js):

{
  "mcpServers": {
    "orbitra": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/Orbitra/mcp/src/index.js"],
      "env": {
        "ORBITRA_URL": "https://tracker.example.com",
        "ORBITRA_API_KEY": "ะฒะฐัˆ-api-ะบะปัŽั‡"
      }
    }
  }
}

Fully restart Claude Desktop (โŒ˜Q on macOS) โ€” the Orbitra tools will appear in the list. Closing the window is not enough; the config is read only at startup.

If the server does not appear:

Tools (41)

Read: orbitra_ping, orbitra_get_metrics, orbitra_get_chart, orbitra_list_campaigns, orbitra_campaigns_stats, orbitra_get_campaign, orbitra_campaign_report, orbitra_list_offers, orbitra_get_offer, orbitra_all_offers, orbitra_list_domains, orbitra_ssl_environment, orbitra_get_integration_code, orbitra_list_app_configs, orbitra_telegram_status, orbitra_integrations_status, orbitra_list_traffic_sources, orbitra_list_landings, orbitra_list_affiliate_networks, orbitra_list_conversions, orbitra_recent_clicks, orbitra_system_status.

Management (requires a write key): orbitra_create_campaign, orbitra_update_campaign, orbitra_bulk_create_campaigns, orbitra_bulk_set_campaign_domain, orbitra_delete_campaign, orbitra_copy_campaign, orbitra_create_offer, orbitra_update_offer, orbitra_delete_offer, orbitra_create_domain, orbitra_delete_domain, orbitra_check_domain_dns, orbitra_reissue_ssl, orbitra_run_ssl_worker, orbitra_save_app_config, orbitra_create_traffic_source, orbitra_list_traffic_source_templates, orbitra_create_landing.

Advanced: orbitra_api_request โ€” call any api.php action directly (the fallback option).

Large accounts. orbitra_list_campaigns and orbitra_list_domains return compact lists (id, name, alias, domain, link) with ID-range and domain filters and pagination โ€” the response stays small even with thousands of campaigns. Stats for all campaigns come from orbitra_campaigns_stats (a heavy response), for a single one โ€” orbitra_campaign_report. To change the domain of many campaigns at once โ€” orbitra_bulk_set_campaign_domain: only the domain changes, streams and postbacks are untouched, and the response carries each campaign's old and new link. orbitra_update_campaign preserves stream IDs, their names, filter logic, offer selection and Bot Challenge.

A full parameter reference lives in mcp/README.md.

Security

when management is needed.

Updates

MCP ships with the project, so the regular update (โš™ โ†’ Update or git pull) pulls the new files automatically. After an update that changed dependencies, run cd mcp && npm install. If the tool list changed in the new version, reconnect the connector in the client so it re-reads the tools.

โ† Previous
Telegram bot
All guides โ†’
Orbitra Wiki
View source on GitHub: github.com/fenjo26/Orbitra.link/wiki
All guides
Docs

Quick start: your first campaign

The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.

Read guide โ†’
Docs

Installation and updates

Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.

Read guide โ†’
Docs

Migrating from Keitaro

Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click โ€” what transfers and what to check.

Read guide โ†’
Docs

Migrating from Binom

Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.

Read guide โ†’
Docs

Feature overview

Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.

Read guide โ†’
Docs

Campaigns and streams

The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.

Read guide โ†’
Docs

Cloaking

Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.

Read guide โ†’
Docs

Browser check

How the JS check catches bots, VMs and emulators through contradictions in the browser environment.

Read guide โ†’
Docs

Landing pages

Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings โ€” the complete reference.

Read guide โ†’
Docs

PWA and Web Push

Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.

Read guide โ†’
Docs

PWA Funnel

A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.

Read guide โ†’
Docs

Conversion popups

Show real conversion events as on-page popups: setup, triggers and placement.

Read guide โ†’
Docs

Session recordings and heatmaps

Replay real visits and see click and scroll maps. Storage limits and privacy notes.

Read guide โ†’
Docs

Content gallery

Central storage for icons, screenshots and creatives used across PWAs and landings.

Read guide โ†’
Docs

Creatives library

Store creatives with subid tracking and test them across campaigns.

Read guide โ†’
Docs

External PWA and Telegram channels

Publish PWAs to external domains and run Telegram channels as a traffic source.

Read guide โ†’
Docs

Postbacks and conversions

Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.

Read guide โ†’
Docs

Costs

Import spend from Facebook, TikTok and Google Ads, or update it via API and cron โ€” and how the revenue aggregator works.

Read guide โ†’
Docs

Push and pop networks

Working with push and pop traffic sources: feeds, zone optimization and the zone killer.

Read guide โ†’
Docs

Facebook / Meta

Cost import from Meta Ads and the Conversions API: server-side events with deduplication.

Read guide โ†’
Docs

Dolphin / Fbtool

Receive Facebook costs through the Dolphin (Fbtool) API in real time.

Read guide โ†’
Docs

FB comment cleaner

Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.

Read guide โ†’
Docs

Traffic sources and affiliate networks

Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.

Read guide โ†’
Docs

Reports, logs and metrics

The report builder, saved reports, click logs and every metric explained.

Read guide โ†’
Docs

Domains and SSL

Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.

Read guide โ†’
Docs

Cloudflare

How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.

Read guide โ†’
Docs

Administration

Users, roles and permissions, security settings, geo databases, updates and system health.

Read guide โ†’
Docs

Telegram bot

Manage the tracker from Telegram: stats, conversions and alerts in chat.

Read guide โ†’
Docs

MCP: an AI assistant in the tracker

Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.

Read guide โ†’