MCP

MCP server

Connect ChatGPT, Claude or Claude Code by signing in to overads, or Cursor, VS Code, Codex, n8n, Zapier and other MCP clients with an API key.

The overads MCP server is the same publishing, workflow and analytics surface as the REST API, spoken as tools. Server URL https://api.overads.io/public/v1/mcp, transport Streamable HTTP. There are two ways in: sign in to overads from ChatGPT, Claude or Claude Code and approve the connection, or send an API key from any other client. Either way, the assistant sees only the tools its permissions allow.

Setting up one assistant? overads.io/agents has two-minute pages for Claude, ChatGPT, Cursor, Codex, Windsurf, VS Code and any other client, with a section written for the agent itself.

Connect by signing in#

ChatGPT, Claude and Claude Code connect without a key. You add the server URL in the app, sign in to overads in the window that opens, pick one workspace, choose what the app may do, and approve. Nobody copies or pastes a secret.

ChatGPT#

Settings > Plugins > Add > Add custom MCP server
Name: overads
MCP server URL: https://api.overads.io/public/v1/mcp
Authentication: OAuth
Save, then sign in to overads, pick a workspace and approve.

OpenAI decides which ChatGPT plans can add a custom MCP server and which of them can run write actions such as creating a post.

Claude (claude.ai, desktop and mobile)#

Customize > Connectors > Add > Add custom connector
Name: overads
Remote MCP server URL: https://api.overads.io/public/v1/mcp
Leave OAuth Client ID and OAuth Client Secret empty
Add, then Connect. Sign in to overads, pick a workspace and approve.

Once added on claude.ai the connector also works in the Claude desktop and mobile apps signed in to the same Claude account. On Team and Enterprise plans an Owner adds it first under Organization settings > Connectors, then members Connect it under Customize > Connectors.

Claude Code#

claude mcp add --transport http overads https://api.overads.io/public/v1/mcp

Then run /mcp inside Claude Code, pick overads and choose Authenticate. Your browser opens the overads approval page. Because Claude Code runs on your computer, the page warns that it sends you back to a local program; approve only if you just started the sign-in yourself.

What the approval screen shows#

• The app asking to connect. ChatGPT and Claude are named because overads checks where the approval returns to; an app overads cannot confirm carries a caution, and so does Claude Code, because it returns to a program on your computer rather than a website.
• The overads account you are signed in as, with a Switch account link.
• Your workspaces. Only workspaces where you are an owner or admin, on the Pro or Scale plan, can be picked; the others are shown dimmed. A connection works in the one workspace you pick. To use another workspace, connect again.
• What the app will be able to do: the permissions it asked for, one checkbox each, ticked to start with. Untick anything it should not do.
• Approve and Deny. overads never approves on its own and never remembers an approval: every new connection shows this screen.

A signed-in connection reaches the MCP server only, never the REST API, and it cannot manage webhooks or workspaces. The workspace's approval rule still applies: when posts need approval, a post the app creates waits for a member to approve it in overads.

Disconnect an app#

• In overads, open Settings > API keys and MCP. Connected apps lists every app that signed in to the workspace, who connected it, what it may do and when it was last used. Owners and admins can press Disconnect; the app stops working on its next call.
• Changing or resetting your overads password, or signing out everywhere, disconnects every app you connected.
• Leaving a workspace, or being removed from it, ends the connections you made there.
• A connection that goes unused for 90 days ends on its own.
• If the workspace is paused because its trial or subscription ended, calls are refused until it is on Pro or Scale again.

Removing overads inside ChatGPT or Claude removes it from that app. To be sure the connection is ended on the overads side too, disconnect it in Connected apps.

Connect with an API key#

Every other client sends an API key in the Authorization header. This is also the way to connect from automation tools and from your own code.

Create the key in Settings > API (the API keys and MCP page). For an assistant that only reads, give it connections:read, posts:read and analytics:read; add posts:write and media:write when it should schedule, and workflows:run when it should run automations. Revoke a key on the same page.

Claude Desktop (config file)#

{
  "mcpServers": {
    "overads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.overads.io/public/v1/mcp",
        "--header",
        "Authorization:Bearer sk_live_YOUR_KEY"
      ]
    }
  }
}

Claude Desktop reaches remote servers through mcp-remote. Settings > Developer > Edit Config, paste, then restart Claude Desktop. To skip the key, add overads as a Claude connector instead (see Connect by signing in).

Claude Code (API key)#

claude mcp add --transport http overads https://api.overads.io/public/v1/mcp --header "Authorization: Bearer sk_live_YOUR_KEY"

Run once in a terminal. Check with claude mcp list; the tools appear in every session.

Cursor#

{
  "mcpServers": {
    "overads": {
      "url": "https://api.overads.io/public/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Project-level in .cursor/mcp.json, or global in ~/.cursor/mcp.json. Cursor > Settings > MCP shows the connection.

VS Code#

{
  "servers": {
    "overads": {
      "type": "http",
      "url": "https://api.overads.io/public/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

For GitHub Copilot agent mode. Open the file and press Start above the server entry.

Codex#

[mcp_servers.overads]
url = "https://api.overads.io/public/v1/mcp"
http_headers = { Authorization = "Bearer sk_live_YOUR_KEY" }

OpenAI Codex CLI reads MCP servers from config.toml. Restart Codex after editing.

Windsurf#

{
  "mcpServers": {
    "overads": {
      "serverUrl": "https://api.overads.io/public/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY"
      }
    }
  }
}

Windsurf > Settings > Cascade > MCP servers, or edit the file directly and refresh.

n8n#

Node: MCP Client Tool
Endpoint: https://api.overads.io/public/v1/mcp
Server transport: HTTP Streamable
Authentication: Bearer auth
Token: sk_live_YOUR_KEY

Attach the node to an AI Agent; every tool the key is scoped for is offered to the agent.

Zapier#

Zapier Agents > Tools > Add MCP server
Server URL: https://api.overads.io/public/v1/mcp
Authentication: Custom header
Header: Authorization
Value: Bearer sk_live_YOUR_KEY

Available on Zapier plans that allow custom MCP servers. The agent sees the same tool list as any other client.

Other MCP clients#

curl -sS https://api.overads.io/public/v1/mcp \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

A client that speaks Streamable HTTP and can send a custom Authorization header can connect this way. POST initialize, keep the Mcp-Session-Id response header, send it on every later request, DELETE to end the session.

Ask for a recap or a draft#

Four tools answer a whole question in one call, so the assistant does not have to chain a dozen reads. Ask in plain words; the assistant picks the tool.

• A draft is only a draft. draft_on_brand_post never schedules and never publishes; a member schedules it in the app, and in a workspace that requires approval it then waits for a yes as well.
• Drafts are text only and go to connections on Instagram, Facebook, LinkedIn, X, Bluesky, Mastodon and Pinterest. A Pinterest pin still needs an image before it can be scheduled.
• Ad-by-ad sections (top and bottom ads, the ads that beat their account) appear only where the deployment enables platform-derived data. Otherwise the recap carries account-level totals and names the missing sections in notIncluded; that is not a reading of zero.

What the server tells the model#

The initialize response carries instructions every client should surface. Three rules matter for anyone building on top:

• Approvals. When the workspace requires approval for scheduled posts, create_post and update_post still succeed, but the post lands with approvalStatus: "pending" and the result carries a warning with code APPROVAL_REQUIRED. The post will not publish until a member approves it in the app. The model should say so, not retry, and not call publish now to get around it (it is refused with the same code).
• Idempotency. Every write tool (create_post, update_post, delete_post, get_upload_url, complete_media, delete_media, run_workflow, draft_on_brand_post) accepts an optional idempotencyKey. A fresh one per intended write, reused on retry: same key and arguments replays the first result, different arguments is IDEMPOTENCY_KEY_CONFLICT, still running is IDEMPOTENCY_IN_FLIGHT. Keys live 24 hours.
• Null is not zero. A counter that is null was not measured. Analytics results carry data and provenance; the model must read provenance before stating a conclusion from data.

Sessions and errors#

• A session belongs to the workspace whose key or sign-in opened it. A valid credential for another workspace with a session id it did not mint gets 404, the same answer as an unknown session.
• An expired session (30 minutes idle) answers 404 with a message saying to send initialize again.
• A tool that is not in the key's or connection's scopes, is gated off on this deployment, or does not exist all answer the same way: Unknown tool. This is deliberate; the error does not enumerate what the deployment holds.
• Tool errors come back as MCP tool results with isError: true and the same code strings as the REST catalogue.

Legacy single-POST clients#

A POST with no Mcp-Session-Id header and no Accept: text/event-stream is treated as a first-generation single-request JSON-RPC call and answered with plain JSON: initialize, ping, tools/list and tools/call only. This path is kept for one release. New integrations should use the Streamable HTTP transport.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_connections","arguments":{}}}