Connect an AI assistant (MCP)

Leadfox exposes a Model Context Protocol (MCP) server. Any MCP-compatible AI assistant (Claude, Cursor, Gemini, ChatGPT, agents you build) can connect to it and read your Leadfox data: contacts, lists, campaigns, emails, automations, landing pages, popups, forms, ads and their metrics.

Server URL	https://mcp.leadfox.co/mcp
Transport	Streamable HTTP
Authentication	OAuth 2.1 (authorization code + PKCE), dynamic client registration
Scopes	api:read, api:write

info

No API key is needed. You sign in with your regular Leadfox user and pick the accounts the assistant may access. The assistant never sees your Leadfox password.

Connect from your client

Add the server URL in your client, then complete the sign-in that opens in your browser.

Claude

In Claude (web or desktop app), open Settings → Connectors → Add custom connector.

Field	Value
Name	Leadfox
Remote MCP server URL	https://mcp.leadfox.co/mcp

Click Add, then Connect to start the sign-in. Once connected, enable the Leadfox connector in the chat's tools menu.

Claude Code

claude mcp add --transport http leadfox https://mcp.leadfox.co/mcp

Then, inside a session, run /mcp and select leadfox to start the sign-in.

Cursor

Add the server to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
    "mcpServers": {
        "leadfox": {
            "url": "https://mcp.leadfox.co/mcp"
        }
    }
}

Open Settings → MCP, then click Connect next to leadfox to start the sign-in.

Gemini CLI

Add the server to ~/.gemini/settings.json:

{
    "mcpServers": {
        "leadfox": {
            "httpUrl": "https://mcp.leadfox.co/mcp"
        }
    }
}

Then run /mcp auth leadfox inside Gemini CLI to start the sign-in.

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth works. Point it at https://mcp.leadfox.co/mcp.

The server advertises its authorization server through the standard discovery documents, so clients that implement the MCP authorization spec register themselves and open the sign-in automatically:

GET https://mcp.leadfox.co/.well-known/oauth-protected-resource/mcp
GET https://app.leadfox.co/.well-known/oauth-authorization-server

Authorize access

The sign-in opens in your browser and takes four steps:

1. Sign in with your Leadfox user. If you are already signed in at app.leadfox.co, this step is skipped.
2. Select accounts. Choose which of the Leadfox accounts you manage the assistant may access. All accounts also covers accounts added to you later; Selected accounts is a fixed list.
3. Review the requested permissions and the accounts, then click Authorize.
4. Return to your client. The browser confirms the connection; the assistant can now call the Leadfox tools.

note

The assistant acts on your behalf. It is limited by your own Role in each account, exactly as if you were using the application.

The connection stays active as long as the assistant keeps using it. A connection that is unused for 90 days expires and you will be asked to sign in again.

Work with accounts

Every tool is scoped to one Leadfox account and takes an account_id. An assistant should always start with search_accounts, which lists the accounts you authorized with their name, website and ID, and then pass the chosen ID to the other tools.

If you manage a single account, the assistant will simply use it. If you manage several, name the one you mean in your request ("in the Acme account, list the campaigns of the last 30 days").

Available tools

All tools are currently read-only and require the api:read scope. The api:write scope is reserved for upcoming tools that create or modify data; a token without it is refused by every write tool.

Entity	Tools
Accounts	search_accounts
Contacts	search_contacts, get_contact
Contact lists	search_contact_lists, get_contact_list, get_contact_list_members, count_contact_list_members
Contact properties	search_contact_properties, get_contact_property
Campaigns	search_campaigns, get_campaign, get_campaign_metrics
Email broadcasts	search_emails, get_email, get_email_variant, get_email_metrics, get_email_variant_metrics
Automations	search_automations, get_automation
Automation emails	search_autoemails, get_autoemail, get_autoemail_variant, get_autoemail_metrics, get_autoemail_variant_metrics
Landing pages	search_pages, get_page, get_page_variant, get_page_metrics, get_page_variant_metrics
Popups	search_popups, get_popup, get_popup_variant, get_popup_metrics, get_popup_variant_metrics
Forms	search_forms, get_form, get_form_variant, get_form_metrics, get_form_variant_metrics
Facebook ads	search_facebook_ads, get_facebook_ad, get_facebook_ad_metrics
Domains	search_domains, get_domain, get_root_domain, search_subdomains, search_active_domains, get_active_domain_by_name, search_email_sending_domains, get_email_sending_domain, get_selected_email_tracking_domain

search_* tools paginate with skip and limit, and most accept a sort option using the same syntax as the REST API (see API basics). Contacts are searched by free text; list members additionally accept filters.

Your client lists the full description and input schema of each tool once connected.

Limits

Each Leadfox user is limited to 120 requests per minute, shared across all the assistants they connected. Above that, calls fail with a 429 Too Many Requests error until the window resets.

Revoke access

Open Edit my profile > Connected apps and click Disconnect next to the assistant. Its tokens are invalidated immediately; the assistant will have to go through the sign-in again to reconnect.

Troubleshooting

Symptom	What to do
The client reports 401 Unauthorized or keeps asking to sign in	The connection expired or was revoked. Remove the server from the client and add it again to restart the sign-in.
A tool answers ... requires the api:write scope	The tool modifies data and your connection is read-only. Write tools are not available yet.
A tool answers that account_id is missing or unknown	Ask the assistant to call search_accounts first, or name the account in your request. The account must be one you selected during authorization.
429 Too Many Requests	Wait a minute and retry. Ask the assistant to narrow its searches and keep limit small instead of fetching everything.
A Leadfox account is missing from the assistant's list	You authorized a fixed list of accounts. Revoke the connection and authorize again choosing All accounts or adding the missing one.