MCP

Use Affluent from an MCP client (Cursor, Claude Desktop, and other MCP-compatible agents).

The MCP server is not the Agency REST API. Tools, resources, and prompts are the contract. Discover them with tools/list, resources/list, and prompts/list. For REST request bodies, use the Agency API reference or the search_api_docs / get_api_endpoint tools.

Base URL

https://{agency}.affluent.io/api/mcp

Replace {agency} with the subdomain you use to log in. If you log in at https://acme.affluent.io, the MCP URL is https://acme.affluent.io/api/mcp.

This is the dashboard host, not {agency}-api.affluent.io. The REST API stays on the -api host.

GET /api/mcp returns 405. Clients must POST.

Authentication

1. In Affluent, create an MCP token (in the Affluent dashboard). The full token is shown once. Store it like a password.
2. Send it on every request:

Authorization: Bearer <mcp_token>

Do not put MCP tokens in git, screenshots, or shared chats. Revoke a token if it leaks.

Advertiser Client and Support roles cannot connect. Use an agency user that can already use the dashboard.

Connect a client

Cursor

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

{
  "mcpServers": {
    "affluent": {
      "url": "https://YOUR_AGENCY.affluent.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Restart Cursor (or reload MCP servers), then confirm tools from affluent appear.

Claude Desktop and other HTTP clients

Use the same URL and Bearer header. If the client only supports stdio, use an HTTP-to-stdio bridge, for example:

{
  "mcpServers": {
    "affluent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_AGENCY.affluent.io/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_MCP_TOKEN"
      ]
    }
  }
}

Replace the URL and token. Do not commit this file if it contains a real token.

What you can do

Ask the agent in natural language. Typical jobs:

• How-to (product UI): “How do I create a dashboard with a pie chart?”
• API shape: “What query params does GET /v1/actions/ take?”
• Performance data: “Top publishers by revenue last 30 days for brand X.”

For how-to questions, the agent should search Learn, read the article body, and cite the Learn URL. For API questions, it should look up the endpoint schema and not invent field names.

Tools

Help tools only return Agencies & Advertisers content. Publisher Learn articles are not included.

get_api_endpoint returns documentation. It does not call the live Agency API. There is no tool that executes arbitrary REST requests.

run_custom_report_query

This tool hits the reporting warehouse. Prefer resources to discover valid metric and category names before querying.

Resources

JSON at these URIs (pass a search term where {query} is shown):

Prompts

Optional starting prompts in the client:

Limits

• MCP: 100 requests per minute per Bearer token.
• run_custom_report_query: limit ≤ 200 rows per call.
• Agency REST date windows (when you use the REST API, not MCP): custom-report-style ranges are capped (Agency API: 62 days). Page large extracts; do not use MCP as a bulk dump.

If the client loops (retry storms), revoke the token.

When to use MCP vs the Agency API

Do not map every REST endpoint 1:1 to an MCP tool. MCP is a small agent surface. REST remains the integration API.

Errors

Agent instructions (optional)

If you maintain llms.txt or a system prompt, this is enough:

Affluent MCP: https://{agency}.affluent.io/api/mcp
Auth: Authorization: Bearer <mcp_token>
For product how-tos: search_help_center then fetch_help_article; cite learn.affluent.io URLs.
For REST fields: search_api_docs then get_api_endpoint; do not invent property names.
For performance numbers: discover metrics/categories via affluent://schema/* then run_custom_report_query.
Do not use MCP for bulk actions backfill; use the Agency REST API.

See also

• Agency API reference — OpenAPI for REST payloads
• Affluent Learn — Agencies & Advertisers how-tos