Skip to main content

Connect via MCP

The NativeAds MCP server exposes the headless platform as Model Context Protocol tools, so an AI agent can create brands, extract Brand DNA, and generate images and video on your behalf. It works with any MCP-capable client, including Claude, Cursor, VS Code, Windsurf, and ChatGPT.

Endpoint​

https://mcp.nativeads.ai/mcp

Use this one URL everywhere below. (https://staging-mcp.nativeads.ai/mcp and https://dev-mcp.nativeads.ai/mcp exist for non-production environments.)

Transport details:

  • Streamable HTTP, JSON-RPC 2.0, POST only. A GET returns 405 (there is no server-to-client SSE stream in this version).
  • Protocol version 2025-11-25 (also accepts 2025-06-18 and 2025-03-26).
  • Machine principals only. A key or OAuth token is required; ordinary user session tokens are rejected.

Authentication​

Two ways to authenticate. Both resolve to the same organization and role model described in the Quickstart.

For clients that implement the MCP authorization spec (Claude, ChatGPT custom connectors), add the server by URL only and complete the sign-in prompt. No key handling on your side: the client discovers the authorization server, registers itself, runs the standard authorization-code + PKCE flow, and you sign in and pick the organization to act on behalf of. Access is resolved live from your membership on every request, so role changes and offboarding take effect immediately.

Discovery details, if you're implementing a client: the resource metadata is at https://mcp.nativeads.ai/.well-known/oauth-protected-resource (RFC 9728); an unauthenticated request also returns a WWW-Authenticate: Bearer resource_metadata="…" challenge pointing there. The authorization server is Clerk; tokens are opaque and introspected on each call.

API key (for headless / CI, or clients without OAuth)​

Send your nak_ key as a bearer token in a headers block. Use this for scripts, CI, and any client that doesn't support OAuth sign-in.

Client setup​

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.

Any other client​

If your client lacks native remote-MCP support, bridge it with mcp-remote:

npx -y mcp-remote https://mcp.nativeads.ai/mcp

Verify the connection​

Ask the client to list tools. You should see 34 tools (see the Tool Catalog). In Claude Code, run /mcp. A quick end-to-end check: call list_brands, then get_feature_usage to confirm your organization and plan resolve correctly.

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​