Getting started with Teads MCP
Connect AI assistants to Teads campaign and reporting tools over Model Context Protocol.
Teads provides a Model Context Protocol (MCP) server for Teads Ad Manager customers. It allows AI assistants to interact with Teads Ad Manager data and tools using natural language through agents or chatbots.
Any MCP-capable client that supports Streamable HTTP or SSE (Server-Sent Events) can connect. Supported clients include Microsoft Copilot Studio, Cursor, Claude, ChatGPT, Codex, Gemini Enterprise, MCP Inspector, and custom agents.
Why MCP
- Zero integration cost — point an MCP client at one URL; tools are discovered via
tools/list. - Natural-language workflows — list seats, inspect a campaign, or export a custom report from plain English.
- Scoped to your profile — the server only returns data the authenticated Teads Ad Manager profile can see.
Server capabilities
Tools
| Category | Tools |
|---|---|
| Seats & campaigns | list_my_seats, get_campaign_seat, campaign_read, list_taxonomy |
| Reporting | list_reporting_dimensions, list_reporting_metrics, reporting_create / _task, reporting_wait_for, get_running_reports |
| Insights & measurement | audience_insights, measurement_campaign_reach_dashboard_task |
| Media planning | planning_media_barometer_task |
Resources
| Category | Resources |
|---|---|
| Seats & campaigns | teads://my-seats |
| Reporting | teads://reporting/dimensions, teads://reporting/metrics |
| Taxonomy | teads://taxonomy/device-types, teads://taxonomy/audiences/{channel}, teads://taxonomy/contextual |
| Knowledge | teads://knowledge/index, teads://knowledge/playbooks/{name} |
Get started
Step 1 — Access
Teads MCP accepts a Bearer access token, issued under the OAuth 2.0 authorization framework, on every request. Teads issues that token in two ways:
| Mode | Who it is for | How you get a token |
|---|---|---|
| SSO | A person using Copilot Studio, Cursor, Claude, ChatGPT, Codex, Gemini Enterprise, MCP Inspector, or another interactive client | The client opens a browser and drives an OAuth 2.0 Authorization Code Flow with PKCE. You sign in to Teads; the client stores the token. |
| M2M | An agent, job, or service that cannot complete a browser login | You exchange a client id and secret for a token using the OAuth 2.0 Client Credentials grant. |
The access token is a JSON Web Token (JWT) — see jwt.io/introduction for background on the format. Data returned by the server is scoped to the authenticated Teads Ad Manager profile: the signed-in user for SSO, or the machine profile bound to the M2M client.
Step 2 — Connect your MCP client
The configuration of your MCP client depends on the authentication mode you chose in step 1.
Endpoint:
https://public-api.teads.tv/mcp/v1/agencyBoth authentication modes and all supported MCP clients connect to this single URL.
Choose a method
- SSO — typical MCP clients prompt you to authenticate in the browser. Use this when a person is at the keyboard.
- M2M — request an access token from the public API token route with client credentials, then call MCP with
Authorization: Bearer <access_token>. Use this for services, scheduled jobs, or automation that cannot complete a browser login.
Token required scope
Both flows must obtain a token that includes the MCP scope:
mcp:agencyA token scoped only for REST use (default scope, no MCP scope) is rejected on /mcp.
If you use a MCP client that follows the protocol standards with SSO method, it will automatically request the token with the required scope.
Step 3 — Test it
Start with natural-language prompts:
- "Which seats can I access?"
- "Show me campaign 123456 (replace with your campaign ID)."
- "Export impressions and clicks by day for the last 7 days as CSV."