Skip to main content

MCP Guide

The NativeAds MCP server exposes the headless platform as Model Context Protocol tools — create brands, extract Brand DNA, upload assets, and generate images and video. The NativeAds MCP server can be connected in two ways, depending on your setup:

  • Standard MCP clients — for existing AI tools that support MCP, such as Claude, ChatGPT, Cursor, or VS Code.
  • Custom integrations — for partners building NativeAds into their own product with a custom MCP client.

Standard MCP clients​

Pick your client. The URL is the same in every snippet.

Claude Code​

OAuth (recommended):

claude mcp add --transport http nativeads https://mcp.nativeads.ai/mcp
# then, inside Claude Code, run /mcp and authenticate in the browser

API key instead of OAuth:

claude mcp add --transport http nativeads https://mcp.nativeads.ai/mcp \
  --header "Authorization: Bearer nak_production_<keyId>.<secret>"

Claude Desktop / claude.ai (web)​

Settings → Connectors → Add custom connector → paste https://mcp.nativeads.ai/mcp → Connect → sign in. (Enable the connector per conversation with the + menu.)

Cursor​

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "nativeads": {
      "url": "https://mcp.nativeads.ai/mcp"
    }
  }
}

To use an API key instead of OAuth, add a headers block:

{
  "mcpServers": {
    "nativeads": {
      "url": "https://mcp.nativeads.ai/mcp",
      "headers": { "Authorization": "Bearer nak_production_<keyId>.<secret>" }
    }
  }
}

VS Code (GitHub Copilot)​

Add to .vscode/mcp.json:

{
  "servers": {
    "nativeads": {
      "type": "http",
      "url": "https://mcp.nativeads.ai/mcp"
    }
  }
}

Windsurf​

Windsurf uses serverUrl (not url). In Settings → MCP:

{
  "mcpServers": {
    "nativeads": {
      "serverUrl": "https://mcp.nativeads.ai/mcp"
    }
  }
}

ChatGPT​

Settings → Connectors → add a connector by URL → paste https://mcp.nativeads.ai/mcp → sign in (OAuth). Requires a plan tier that supports custom connectors.

Custom integrations​

Follow these steps to connect your platform to NativeAds over MCP. Once connected, your integration can call any tool in the MCP Tool Catalog.

Step 1 — Create an API key​

An API key is like a password that lets your agent act as you in NativeAds. Create one in the NativeAds app:

  1. Sign in at https://app.nativeads.ai.
  2. Open Settings → Account → API Keys.
  3. Click Create, give the key a name (optional expiry), and confirm.
  4. Copy the full token immediately and store it somewhere safe (for example your company's secret manager). It is shown once and cannot be retrieved again.

The key looks like this:

nak_production_<keyId>.<secret>

Treat it like a password. Anyone who has it can act as you.

About the key

  • It acts as you inside your organization — same permissions as your user account.
  • It stays valid until you delete it or it expires.
  • To rotate it, regenerate the key (same name); the old token stops working immediately.

Step 2 — Point your agent at NativeAds​

In your agent's MCP / connector settings, set:

  1. Server URL: https://mcp.nativeads.ai/mcp
  2. Authentication header — tell your agent to send this on every request to NativeAds:
Authorization: Bearer nak_production_<keyId>.<secret>

Replace nak_production_<keyId>.<secret> with the key you copied in Step 1.
Keep the word Bearer and the space before the key.

Example config shape many agents use:

{
  "url": "https://mcp.nativeads.ai/mcp",
  "headers": {
    "Authorization": "Bearer nak_production_<keyId>.<secret>"
  }
}

Exact field names (url, serverUrl, headers) depend on your agent platform — use whatever your platform docs call “MCP server URL” and “request headers.”

Step 3 — Check that it works​

  1. Ask your agent to list tools from NativeAds. You should see 34 tools.
  2. Ask it to call list_brands, then get_feature_usage.

If those succeed, your agent is connected. For what each tool does and the recommended workflow, see the MCP Tool Catalog.

Generation tools return a task id first; your agent should poll get_task until the job finishes.

Technical notes​

  • Transport: Streamable HTTP, JSON-RPC 2.0, POST only (GET returns 405).
  • Protocol version 2025-11-25 (also accepts 2025-06-18 and 2025-03-26).
  • Only machine credentials (API key) are accepted here — normal website session cookies will not work.

Notes​

  • Tool results are structured objects. List tools return { data, total } (never a bare array).
  • Generation tools are asynchronous: they return a task id, and you poll get_task until the task completes. See the catalog for which tools are async.
  • The urls input on create_brand_dna_version and rerun_brand_dna_version accepts only public http/https addresses; internal, loopback, and cloud-metadata addresses are rejected.

Next steps​