MCP Introduction
MCP lets you share Billy Grace data with your AI provider, like Claude. It can request performance metrics on demand. The data comes back structured, so it can actually interpret it.
How it works
Setting up MCP creates a connector between Billy Grace and your AI provider. Once it's connected, it uses Billy Grace data whenever it's needed to answer a question. Once your organisation accepts the MCP terms in the Billy Grace platform, any member can use the Billy Grace MCP with their own Billy Grace credentials.
Access and permissions
Your account type determines your access level when you accept the MCP terms. It will always be limited to clients you have access to in the Billy Grace dashboard. Agencies also need approval from the brand before their data can be queried through MCP.
Single account brands
Accepting the terms gives you access to your own data right away. You need to grant access separately if you want an agency to query your data through MCP. You can enable access using the access switch. You can manage your access in the settings page: https://app.billygrace.com/settings/mcp
Multi account brands
Accepting the terms gives you access to all the accounts under your company right away. You can manage your access in the settings page: https://app.billygrace.com/partner/settings/mcp
Agencies
Accepting the terms does not give you access to any brand data automatically. Each brand needs to grant you access from their MCP settings page. Contact them directly to gain access. You can manage your access in the settings page: https://app.billygrace.com/partner/settings/mcp
Security and privacy
Access: Every member of your organisation can use the Billy Grace MCP once enabled. Please manage permissions internally if relevant.
Authentication: Your login is secure. You sign in directly with your Billy Grace account, and your AI provider never sees or stores your password.
Authorization: Every request is checked against the Billy Grace clients your account can access. Requests for any other client are automatically rejected.
Data processing: Your AI provider (e.g. Claude, n8n) processes the data it receives in order to answer your question. Check your organisation's policies on using AI to analyse business data before connecting.
Aggregated data: The MCP returns aggregated rows. It does not expose raw events, raw user identifiers, or PII.
Installation
Below you find the setup steps for the AI providers we currently support. Contact support if you'd like us to add a platform that isn't listed here.
Claude
Billy Grace works as a remote MCP connector on the web app, Desktop, and Code versions of Claude. Custom MCP connectors are available on every Claude plan. Team and Enterprise members will need their Owner to add the connector first.
Claude Web Application & Claude Desktop
Go to Claude
Click Profile → Settings → Connectors.
Click Add custom connector.
Enter:
Name: Billy Grace
Remote MCP server URL: https://mcp.billygrace.com/mcp
Save. Claude opens your browser to complete the Billy Grace login.
In a new chat, enable the Billy Grace connector from the connectors menu so Claude can call its tools.
Claude Code (CLI)
Claude Code picks a random OAuth callback port by default, and Auth0 cannot whitelist a random port. Use --callback-port 10000 to pin it to the pre-registered value.
Run the following command:
claude mcp add --transport http --callback-port 10000 bg-mcp https://mcp.billygrace.com/mcp
The first time you start a Claude Code session, you'll be prompted to authenticate in the browser. Verify the connection with /mcp inside Claude Code.
Cursor
Open the Cursor app
Open Cursor settings:
Mac (Shortcut: Command + Shift + J): Cursor → Settings → Cursor Settings
Windows/Linux (Shortcut: Ctrl + Shift + J): Cursor → Settings → Cursor Settings
Go to Tools & MCPs → Add new MCP server.
Enter
Name: billy-grace
Save. Cursor opens your browser to complete the Billy Grace login.
Back in Cursor, the billy-grace server should show as connected and the tools should appear in the MCP panel.
You can also configure it via JSON. Add this entry to ~/.cursor/mcp.json:
{
"mcpServers": {
"billy-grace": {
"url": "https://mcp.billygrace.com/mcp"
}
}
}
Then restart Cursor, or toggle the server off and on in the MCP settings panel, to trigger the authentication flow.
n8n
Go to the n8n dashboard and open a workflow
Add an AI Agent node
Click the + under Tool on the AI Agent node
Select MCP servers from the tools list
Select MCP Client Tool
In the Parameters panel, enter:
Endpoint: https://mcp.billygrace.com/mcp
Server Transport: HTTP Streamable
Authentication: MCP OAuth2
Under Credential for MCP OAuth2 API:
Enter the name Billy Grace MCP
Click Create new credential
In the credential form, enter:
Server URL: https://mcp.billygrace.com/mcp
Click Connect and complete the Billy Grace login
Set Tools to Include to All or select specific tools
Close the setup window
Make
Go to the Make dashboard
Click AI Agents in the left sidebar
Click Create agent
Click the agent node and select Add MCP
In the MCP Tools panel, click Add next to Connection
In the Create a connection dialog, enter:
Connection name: Billy Grace
MCP server: Select New MCP server
API key / Access token: leave empty
Click Save and complete the Billy Grace login in the browser window that appears
Back in the MCP Tools panel, select the Billy Grace tools you want to make available to the agent, or select all
Click Save
Lovable
Go to the Lovable dashboard
Click Connectors in the left menu bar
Type custom in the search bar
Select the Custom MCP connector
Enter:
Server Name: Billy Grace
Server URL: https://mcp.billygrace.com/mcp
Keep OAuth (default) as the authentication option
Click Add & authorize and complete the Billy Grace login
What Data Is Shared
The MCP has access to multiple datasets each with exposing data structure.
Marketing performance
Aggregated performance data across all integrated marketing channels.
Category | Items |
Spend and Delivery Metrics | spend, impressions, clicks, sessions |
Conversion Metrics | number_of_events, event_value, new_customer, returning_customer, new_customer_revenue, returning_customer_revenue, pre_spend_profit |
Computed Metrics | roas, cpa, conversion_rate, cost_per_click |
Dimensions | date, is_integrated_channel, source, medium, campaign (status/id/name), ad set (status/id/name), ad (status/id/name) |
Attribution Model | LC, MTA, UMM |
Attribution Mode | session_date, event_date |
Attribution Window | 1-day, 7-day, 30-day, unlimited |
Shopping performance
Product level performance data for shopping campaigns.
Category | Items |
Spend and Delivery Metrics | spend, impressions, clicks, sessions |
Conversion Metrics | number_of_events, event_value, new_customer, returning_customer, pre_spend_profit |
Computed Metrics | roas, cpa, conversion_rate, cost_per_click |
Dimensions | date, source, campaign (id/name), product (id/name), feed_id |
Attribution Model | LC, MTA |
Attribution Mode | session_date, event_date |
Attribution Window | 1-day, 7-day, 30-day, unlimited |
Keyword performance
Search keyword level performance data.
Category | Items |
Spend and Delivery Metrics | spend, impressions, clicks, sessions |
Conversion Metrics | number_of_events, event_value, new_customers, returning_customers, pre_spend_profit |
Computed Metrics | roas, cpa, conversion_rate, cost_per_click |
Dimensions | date, source, campaign (id/name/status), ad_group (id/name), adset_status, keyword, keyword_id, keyword_match_type, keyword_status |
Attribution Model | LC, MTA |
Attribution Mode | session_date |
Attribution Window | 1-day, 7-day, 30-day, unlimited |
More datasets will be added over time. If you need a specific dataset that is not yet available please reach out to your Billy Grace point of contact.
Data format
Aggregated: no raw event rows or individual user profiles are returned, only SUM-aggregated rows over the dimensions you request.
Client scoped: every request is checked against your account's allowed client IDs. You cannot see another customer's data.
Recency: data is available through yesterday. The nightly pipeline processes the previous day's data.
Sample prompts
Once you're connected, try prompts like:
For client Acme Corp, what was my ROAS by source over the last 14 days?
Give me a daily breakdown of spend and purchases for the spring-sale-2026 campaign.
Compare last month vs the previous month on conversions and spend, broken down by channel.
Which Meta ads had the highest CPA in the last 7 days?
Show me how revenue attribution shifts between MTA and UMM for the same period.
Your AI provider will use the Billy Grace MCP tools to discover the right metrics, events, and dimensions, and then run an insights query against your data.
Troubleshooting
Below we’ll cover the most commonly asked questions. Please contact support or your Billy Grace contact if you have any other questions.
Client not available
You can only query clients through MCP that you already have access to in your Billy Grace account. Please review your MCP settings page to view access.
Your AI provider isn't supported
We currently provide MCP support for Cursor, Claude, Lovable, n8n, and Make. Please get in contact with the support team if yours isn't listed. We're adding more providers over time. If you try to connect with an unsupported provider, you'll be redirected to the error screen below.
Agency can't access a brand's data
Contact the brand directly and ask them to grant access. Billy Grace can't enable this on the agency's behalf.
Not sure which settings URL to use
Single-client brands and multi-client brands or agencies manage MCP at different URLs. Check the links in "Access and permissions" to find the right one for your account.
Consistent behaviour across every user
We see this as the responsibility of the AI platform you're connecting to, not the MCP layer. Claude, for example, lets Team and Enterprise Owners set organisation-wide instructions that apply to every conversation, and supports skills that can be provisioned at both individual and organisational level.