Documentation
Connect an AI assistant with MCP
Updated 17 Nov 2026
An admin creates a token in the Velotrak admin. The client sends Authorization: Bearer vtmcp_… to POST /mcp on the tracker origin. Edits and deletes return a diff and wait for the same call with diff_token. Free tokens are read-only.
Create a token
Only an admin can create MCP tokens (GET, POST, and DELETE /api/mcp-tokens). The plaintext token is shown once. It starts with vtmcp_. The server stores a SHA-256 hash, the scope JSON, the creator, and an expiry. If you omit days, expiry is 90 days. The maximum is 365. If you omit scopes, the token is {"reports":{"read":true}}.
The creator must stay an active admin. Disabling that user, or changing their role, makes the token fail authentication. The row can remain in the database. Free and Pro allow one unexpired token (counted for active admin creators). Team stores an unlimited cap. The pricing page describes Team as one token per teammate; the entitlement the app enforces is unlimited. See plans.
Point the client at POST https://<your host>/mcp. The path is the site root, not under /admin/. The header is Authorization: Bearer <token>. The protocol version the server announces is 2025-03-26.
Scopes and confirmation
Scopes are { "<domain>": { "read": true, "write": true } }. The admin groups domains as campaigns, offers, landers, flows, sources, networks, domains, reports, and logs; alerts, backups, migration, system, and admin; and the sensitive domains integrations, license, and lander files. A scope of * does not cover the sensitive domains, and it never grants tools marked explicit-only (branding changes, restore, and clearing demo data are in that set). A token without write on a domain sees redacted credentials.
Write tools require Pro or above (mcp_write). On Free they are rejected, except activate_license. A destructive call does not run on the first request. The response includes requires_confirmation, a diff_token, and expires_in_seconds of 600. Send the same tool and the same arguments again with that diff_token.
The tool list
The table below is generated at build time from Registry() in the tracker source. The pricing page and the homepage still say 90 tools. This table is the list the registry and the CI check keep in sync with the tools the server actually registers. One admin route has no tool: PATCH /api/integrations/{id} updates an integration, and the registry only has create, delete, list, and sync_costs.
MCP tools
| Feature | REST | Tool |
|---|---|---|
| Click log | GET /api/logs/clicks | get_click_log |
| Conversion log | GET /api/logs/conversions | get_conversion_log |
| Postback log | GET /api/logs/postbacks | get_postback_log |
| Outbound log | GET /api/logs/outbound | get_outbound_log |
| Report query | POST /api/reports/query | report_query |
| Dashboard summary | GET /api/dashboard | dashboard_summary |
| Export report csv | POST /api/reports/export | export_report_csv |
| List report views | GET /api/reports/views | list_report_views |
| Save report view | POST /api/reports/views | save_report_view |
| Delete report view | DELETE /api/reports/views/{id} | delete_report_view |
| Clone campaign | POST /api/campaigns/{id}/clone | clone_campaign |
| Clone offer | POST /api/offers/{id}/clone | clone_offer |
| Clone flow | POST /api/flows/{id}/clone | clone_flow |
| Campaigns: list | GET /api/campaigns | list_campaigns |
| get_campaign | GET /api/campaigns/{id} | get_campaign |
| create_campaign | POST /api/campaigns | create_campaign |
| update_campaign | PATCH /api/campaigns/{id} | update_campaign |
| delete_campaign | DELETE /api/campaigns/{id} | delete_campaign |
| Offers: list | GET /api/offers | list_offers |
| get_offer | GET /api/offers/{id} | get_offer |
| create_offer | POST /api/offers | create_offer |
| update_offer | PATCH /api/offers/{id} | update_offer |
| delete_offer | DELETE /api/offers/{id} | delete_offer |
| Landers: list | GET /api/landers | list_landers |
| get_lander | GET /api/landers/{id} | get_lander |
| create_lander | POST /api/landers | create_lander |
| update_lander | PATCH /api/landers/{id} | update_lander |
| delete_lander | DELETE /api/landers/{id} | delete_lander |
| Sources: list | GET /api/traffic-sources | list_traffic_sources |
| get_traffic_source | GET /api/traffic-sources/{id} | get_traffic_source |
| create_traffic_source | POST /api/traffic-sources | create_traffic_source |
| update_traffic_source | PATCH /api/traffic-sources/{id} | update_traffic_source |
| delete_traffic_source | DELETE /api/traffic-sources/{id} | delete_traffic_source |
| Networks: list | GET /api/networks | list_networks |
| get_network | GET /api/networks/{id} | get_network |
| create_network | POST /api/networks | create_network |
| update_network | PATCH /api/networks/{id} | update_network |
| delete_network | DELETE /api/networks/{id} | delete_network |
| rotate_network_key | POST /api/networks/{id}/rotate-key | rotate_network_key |
| Domains: list | GET /api/domains | list_domains |
| get_domain | GET /api/domains/{id} | get_domain |
| create_domain | POST /api/domains | create_domain |
| update_domain | PATCH /api/domains/{id} | update_domain |
| delete_domain | DELETE /api/domains/{id} | delete_domain |
| Flows: list | GET /api/flows | list_flows |
| get_flow | GET /api/flows/{id} | get_flow |
| create_flow | POST /api/flows | create_flow |
| update_flow | PATCH /api/flows/{id} | update_flow |
| delete_flow | DELETE /api/flows/{id} | delete_flow |
| Get flow doc | GET /api/flows/{id}/doc | get_flow_doc |
| Set flow doc | PUT /api/flows/{id}/doc | set_flow_doc |
| Simulate flow | POST /api/flows/{id}/simulate | simulate_flow |
| List lander files | GET /api/landers/{id}/files | list_lander_files |
| Read lander file | GET /api/landers/{id}/files/{path} | read_lander_file |
| Write lander file | PUT /api/landers/{id}/files/{path} | write_lander_file |
| Delete lander file | DELETE /api/landers/{id}/files/{path} | delete_lander_file |
| Lander preview link | POST /api/landers/{id}/preview-link | get_lander_preview_link |
| License status | GET /api/license | license_status |
| Activate license | POST /api/license/activate | activate_license |
| License heartbeat | POST /api/license/heartbeat | license_heartbeat |
| List integrations | GET /api/integrations | list_integrations |
| Create integration | POST /api/integrations | create_integration |
| Delete integration | DELETE /api/integrations/{id} | delete_integration |
| Sync costs | POST /api/integrations/{id}/sync | sync_costs |
| Enter manual campaign spend | POST /api/campaigns/{id}/cost | record_campaign_cost |
| List manual campaign spend | GET /api/campaigns/{id}/cost | list_campaign_cost |
| Check domain | POST /api/domains/{id}/check | check_domain |
| List alerts | GET /api/alerts | list_alerts |
| Create alert | POST /api/alerts | create_alert |
| Update alert | PUT /api/alerts/{id} | update_alert |
| Delete alert | DELETE /api/alerts/{id} | delete_alert |
| List alert events | GET /api/alerts/events | list_alert_events |
| List backups | GET /api/backups | list_backups |
| Create backup | POST /api/backups | create_backup |
| Restore backup | POST /api/backups/restore | restore_backup |
| System health | GET /healthz | system_health |
| List users | GET /api/users | list_users |
| Audit log | GET /api/audit | audit_log |
| Get branding | GET /api/bootstrap | get_branding |
| List bot rules | GET /api/bot-rules | list_bot_rules |
| Get custom metrics | GET /api/settings/custom-metrics | get_custom_metrics |
| Set custom metrics | PUT /api/settings/custom-metrics | set_custom_metrics |
| Get update status | GET /api/system/update | get_update_status |
| Check for update | POST /api/system/update/check | check_for_update |
| Download update | POST /api/system/update/download | download_update |
| Create bot rule | POST /api/bot-rules | create_bot_rule |
| Delete bot rule | DELETE /api/bot-rules/{id} | delete_bot_rule |
| Set branding | PUT /api/settings/branding | set_branding |
| Migration: export config | GET /api/export | export_config |
| Migration: import config | POST /api/import | import_config |
| Migration: list templates | GET /api/templates | list_templates |
| Migration: apply template | POST /api/templates/apply | apply_template |
| Migration: generate demo | POST /api/demo/generate | generate_demo |
| Migration: clear demo | POST /api/demo/clear | clear_demo |