Connect Agent Planners to Claude, Codex, Grok and Muse

Before you start#

The server URL is the same for every assistant: https://www.agentplanners.com/api/mcp (MCP over Streamable HTTP). There are two ways to sign in, and both reach the same tools, approvals and audit trail:

• OAuth sign-in — for assistants that support MCP authorization. You add the URL, the assistant opens the Agent Planners consent page, you sign in, pick the workspace and choose what it may do. Nothing to copy. Details: OAuth sign-in.
• An API key — for assistants that only send a fixed header, and for scripts. A workspace admin creates it on API & MCP (New key). It looks like ap_live_ followed by 32 hexadecimal characters and is sent as Authorization: Bearer <key>. Keep it in an environment variable (the snippets use AGENTPLANNERS_API_KEY), never in a file you commit.
• Agent mode or tools mode. Agent mode (any plan) lets the assistant hand Agent Planners a goal and follow the task. Tools mode (a paid plan, granted by a workspace admin) lets it call the platform tools directly — reports, settings, changes. describe_permissions tells the assistant which one it has.
• Your accounts stay connected in Agent Planners. The assistant never receives a Google, Meta or store credential; it gets results.
• Cloud assistants reach the server over the internet. claude.ai, grok.com, the xAI API and Grok Bot call the server from their own cloud, which is why it is a public https URL. A server on localhost or a private network cannot be added to them.

Claude: claude.ai, Claude Desktop and the mobile apps#

Verified on 2026-10-11 against the official documentation: support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp. Claude connects from Anthropic's cloud, and Claude Desktop and the mobile apps use the connectors of the claude.ai account they are signed in to.

1. 1On Pro or Max, open Customize → Connectors, select + Add and choose Add custom connector. On a Team or Enterprise plan an Owner adds it first under Organization settings → Connectors; each member then connects with their own account. The Free plan allows one custom connector.
2. 2Name it Agent Planners and enter the server URL https://www.agentplanners.com/api/mcp. Select Continue.
3. 3Claude shows the sign-in it detected. Under Authentication choose Sign in now (or Sign in when needed), leave OAuth client on Use Claude's published identity (Recommended) and select Add — the consent page will show Sends you back to Claude.
4. 4Connect: the Agent Planners consent page opens. Sign in, pick the workspace, review what Claude may do and select Allow access.
5. 5In a chat, turn it on from + → Connectors and ask, for example, “Call describe_permissions and list my connected ad accounts.”

Claude Code#

Verified and tested on 2026-10-11 against the official documentation: code.claude.com/docs/en/mcp. Tested with Claude Code 2.1.258: both commands below write the server to the chosen scope and claude mcp get agent-planners shows it.

Run one of these in a terminal. With OAuth, start Claude Code and run /mcp, choose agent-planners and sign in (or run claude mcp login agent-planners): the browser opens the consent page and Claude Code stores and refreshes the tokens. Add --scope user to use it in every project, or --scope project to share it through the repository's .mcp.json — a project server shows as Pending approval until you approve it when Claude Code starts.

In a shared .mcp.json, write the header as Bearer ${AGENTPLANNERS_API_KEY} so the key stays in each person's environment. In Windows PowerShell or cmd, put the key command on one line without the backslash.

# Sign in with OAuth (then /mcp in Claude Code)
claude mcp add --transport http agent-planners https://www.agentplanners.com/api/mcp

# Or with an API key
claude mcp add --transport http agent-planners https://www.agentplanners.com/api/mcp \
  --header "Authorization: Bearer ap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Codex: sign in with OAuth#

Verified and tested on 2026-10-11 against the official documentation: developers.openai.com/codex/mcp. Tested with codex-cli 0.128.0 in an empty CODEX_HOME.

The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share one MCP configuration (~/.codex/config.toml). codex mcp add detects that Agent Planners supports OAuth and starts the sign-in at once: open the URL it prints, sign in, pick the workspace and select Allow access. Run codex mcp login later whenever the tokens are missing or the connection ended. codex mcp list shows the server, and /mcp in the Codex terminal UI lists its tools.

codex mcp add agent-planners --url https://www.agentplanners.com/api/mcp
codex mcp login agent-planners

Codex: with an API key#

Verified and tested on 2026-10-11 against the official documentation: developers.openai.com/codex/mcp. Tested with codex-cli 0.128.0: the add command writes exactly the config.toml entry below, and codex mcp list reports Bearer token.

Codex reads the key from an environment variable, so the key never sits in a config file. Set the variable (on Windows, under System → Environment Variables or with setx, then open a new terminal), then add the server — with the command or by editing ~/.codex/config.toml.

export AGENTPLANNERS_API_KEY=ap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

codex mcp add agent-planners --url https://www.agentplanners.com/api/mcp --bearer-token-env-var AGENTPLANNERS_API_KEY

# …which writes this to ~/.codex/config.toml:
[mcp_servers.agent-planners]
url = "https://www.agentplanners.com/api/mcp"
bearer_token_env_var = "AGENTPLANNERS_API_KEY"

Grok on grok.com: a custom connector#

Verified on 2026-10-11 against the official documentation: docs.x.ai/grok/connectors, docs.x.ai/grok/connector-management, docs.x.ai/grok/connectors/custom-mcp-tunneling. xAI's page says connectors are available to all Grok users and does not name a plan for custom connectors; third-party guides say custom connectors need a paid plan — unverified.

1. 1Go to grok.com/connectors, select New Connector, then Custom.
2. 2Enter the server URL https://www.agentplanners.com/api/mcp and complete the authentication it asks for: the Agent Planners consent page opens — sign in, pick the workspace and select Allow access.
3. 3Grok discovers the tools and offers them in conversations. Ask, for example, “Use Agent Planners: call describe_permissions and list my ad accounts.”
4. 4On Grok Business or Enterprise, a team admin first adds it in the xAI console (console.x.ai → the team → Grok Business → Connectors → + Add Connector → Other → the server URL); members then connect their own accounts at grok.com/connectors.

Grok Build: xAI's terminal agent#

Verified on 2026-10-11 against the official documentation: docs.x.ai/build/features/mcp-servers. Not tested here: the grok CLI is not installed on our test machine.

grok mcp add writes the server to ~/.grok/config.toml (or .grok/config.toml with --scope project). An OAuth server opens a browser sign-in on first use; grok mcp doctor agent-planners checks the configuration and the connection. Grok Build also reads servers from ~/.claude.json, .cursor/mcp.json and a project .mcp.json, so a server you already added for Claude Code or Cursor may already be there — grok inspect shows where each one came from.

# Sign in with OAuth on first use
grok mcp add --transport http agent-planners https://www.agentplanners.com/api/mcp

# Or with an API key (Grok expands ${VAR} in headers)
grok mcp add --transport http agent-planners https://www.agentplanners.com/api/mcp --header "Authorization: Bearer ${AGENTPLANNERS_API_KEY}"

Grok through the xAI API: Remote MCP Tools#

Verified on 2026-10-11 against the official documentation: docs.x.ai/developers/tools/remote-mcp. Not tested end to end here (it needs an xAI API key).

For your own app on the xAI Responses API (https://api.x.ai/v1/responses, the OpenAI-compatible endpoint, or xAI's SDK): add Agent Planners as a tool of type mcp with server_url and server_label. xAI's servers call it, over Streamable HTTP or SSE only. There is no sign-in flow here, so send an Agent Planners API key — in headers as below (xAI also accepts an authorization field, a token for the Authorization header; headers says the Bearer prefix explicitly). In xAI's SDK the fields are allowed_tool_names and extra_headers.

xAI does not support require_approval: the model calls the tools without asking. Use a key that can only read, or a key whose writes wait for approval in Agent Planners (a write then answers with a requestId and changes nothing until a person approves it). allowed_tools limits what is offered, but with on-demand listing the platform tools sit behind search_tools / call_tool — narrow the key's platforms and scopes in Agent Planners instead.

POST https://api.x.ai/v1/responses
Authorization: Bearer $XAI_API_KEY
Content-Type: application/json

{
  "model": "grok-4.7",
  "input": [
    {
      "role": "user",
      "content": "Call describe_permissions, then list my connected ad accounts."
    }
  ],
  "tools": [
    {
      "type": "mcp",
      "server_url": "https://www.agentplanners.com/api/mcp",
      "server_label": "agent-planners",
      "server_description": "Agent Planners: this workspace's ad, analytics and store accounts",
      "headers": {
        "Authorization": "Bearer ap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  ]
}

Grok Bot: xAI's agent on your Cursor account#

Partly verified on 2026-10-11 against the official documentation: docs.x.ai/grok-bot/computer-and-apps, docs.x.ai/grok-bot/teams-and-enterprises, cursor.com/help/grok-bot/connect-plugins, cursor.com/docs/mcp, cursor.com/help/grok-bot/secrets. Grok Bot adds services as plugins from its Plugins (Connect apps) marketplace; its documentation shows no field where a person pastes an MCP server URL.

• On a Cursor team (documented by Cursor and xAI; not tested with Grok Bot): a Cursor team admin adds Agent Planners as a Team MCP server under Cursor's Dashboard → Plugins & MCPs (server URL above) and, under Team MCP Servers, selects Add to Team Marketplace. xAI's docs say Grok Bot inherits the team's Cursor connector policy and shows connectors as plugins; a member then adds it from Plugins and selects Authorize to sign in. An Enterprise MCP allowlist must include the URL, or the plugin shows Disabled by team admin.
• Asking the bot in chat to add the server: third-party guides say Grok Bot can register an MCP server that way — unverified; xAI's documentation does not describe it.
• The REST API (works without a plugin): Grok Bot has its own computer with a shell. Save an Agent Planners API key on the Bot under Secrets (Add secret, with an environment variable name such as AGENTPLANNERS_API_KEY) — never paste it into chat — and ask the Bot to call https://www.agentplanners.com/api/v1: GET /me first, then GET /tools?q= to find a tool and POST /tools/{name} to run it. The REST API guide lists every endpoint; writes wait for a person unless the key applies them at once.

Meta Muse: the app#

Partly verified on 2026-10-11 against the official documentation: www.meta.com/help/artificial-intelligence/1687253048996149/. Meta's help center describes custom connectors you build by asking Muse in chat (it may retrieve the service's API information and keeps keys in its Secure Credentials Store) and does not mention MCP. Meta does not review custom connectors.

• The documented route: ask Muse to create a custom connector for Agent Planners' REST API — base URL https://www.agentplanners.com/api/v1, OpenAPI description https://www.agentplanners.com/api/v1/openapi.json, an Agent Planners API key sent as Authorization: Bearer. Not tested with Muse. A read-only key, or one whose writes wait for approval, is the safe start.
• Adding the MCP server by URL: some third-party guides say Settings → Connectors → Add custom connector takes an MCP server URL, or that Muse adds one when you describe it in chat; another says the app has no custom MCP setting. Meta's documentation confirms none of these — unverified. If your app shows such a field, the server URL and the OAuth sign-in above are what it needs.
• For MCP today, use Muse Code (next section): Meta documents remote MCP servers with OAuth sign-in there.

Muse Code: Meta's terminal coding agent#

Verified on 2026-10-11 against the official documentation: dev.meta.ai/docs/muse-code/extending, dev.meta.ai/docs/muse-code/configuration. Not tested here: Muse Code is not installed on our test machine.

Add the server to the mcp_servers block of ~/.config/muse/settings.json — keep the keys already in the file; the file must contain "schema_version": 1 or every command fails. Servers load when a session starts, so start a new one. Then sign in with muse mcp login agent-planners (OAuth 2.1; Muse Code keeps and refreshes the tokens, and a 401 tells you the command to run). /mcp in a session lists the connected servers and their tools.

With an API key instead, add "headers": { "Authorization": "Bearer ${AGENTPLANNERS_API_KEY}" } to the entry — Muse Code expands ${VAR}. "mode": "optional" lets Muse Code start with a warning when the server cannot be reached; without it a server is required and the run stops. MCP tools run outside Muse Code's sandbox, and Agent Planners' approvals still hold its writes.

{
  "schema_version": 1,
  "mcp_servers": {
    "agent-planners": {
      "transport": "streamable_http",
      "url": "https://www.agentplanners.com/api/mcp",
      "mode": "optional"
    }
  }
}

How the assistant finds and calls the tools#

• describe_permissions first. It says the connection's mode (agent or tools), scopes, platforms, how writes are handled and how tools are listed.
• Agent mode: list_accounts, create_task with a concrete goal, then get_task until the task completes. The task's changes wait for approval in Agent Planners unless the task was started with auto-approve.
• Tools mode, up to 100 platform tools: the assistant sees every platform tool it may call, named family__tool (for example google_ads__get_account_health).
• Tools mode, more than 100 platform tools (or 64 KB of descriptions): the list is loaded on demand — search_tools finds a tool by what you want to do, describe_tool returns its arguments and whether this connection may call it, and call_tool runs it. Every tool stays callable directly by name. This keeps a fully connected workspace's roughly a thousand tools out of the assistant's context and inside tool-count limits.
• The connection's platforms: a key or connection can expose every connected platform (including ones connected later) or only the ones ticked. A platform left out is the key's choice — its tools answer that they are not exposed, not that nothing is connected.
• Writes: depending on the connection, a write applies at once inside the workspace's guardrails or waits on API & MCP → Write approvals. A waiting write returns a requestId; raw_request_status tells the assistant the decision. Deletes and other changes a platform marks as a person's decision always wait for a person.
• Credits: every call that runs is billed in the workspace's credits; a result may end with a “Low credits” line the assistant should pass on.

A first prompt to paste#

Paste this into the assistant once the server is connected (it is the same prompt the API & MCP page copies for a sign-in connection):

You are connected to Agent Planners over MCP. It holds my workspace's ad, analytics and store connections and runs every call under the workspace's permissions, guardrails and audit trail.

How to work with it:
1. Call describe_permissions first and tell me in two lines what this connection may do: mode, scopes, platforms and how writes are handled.
2. If describe_permissions shows no platform tools (agent mode), work through list_accounts, create_task with a concrete goal, and get_task (poll it until the task is completed) instead.
3. Never guess a tool name: when search_tools is available, call it with what you want to do; otherwise pick from the family__tool tools you were given. describe_tool shows a tool's arguments and whether this connection may call it.
4. Call list_accounts and pass the accountId of the account I mean. If more than one account could match, ask me which.
5. Read before you write: check the current state first, then show me the exact change (account, object, current value → new value) and wait for my yes before you call any write tool.
6. Depending on this connection's settings a write applies at once inside the workspace's guardrails or waits for approval in Agent Planners — describe_permissions says which. A write that waits says it is queued and gives a requestId: tell me, and check raw_request_status with it before you call the change done.
7. Every call spends this workspace's credits. If a result ends with a "Low credits" line, pass it on to me.

Start with one of these:
- Which of my campaigns spent the most in the last 7 days, and what did each pay per conversion?
- Check every connected ad account's health: suspensions, disapproved ads, verification requests and billing holds.
- Find Google Ads search terms that spent money with no conversions in the last 30 days and list the negatives you would add — don't add them yet.

Troubleshooting#

Frequently asked questions#

Do I need an API key to connect Claude, Codex, Grok or Muse Code?

No, when the assistant supports MCP sign-in: claude.ai, Claude Code, Codex, grok.com, Grok Build and Muse Code open the Agent Planners consent page and you approve the connection there. The xAI API has no sign-in flow, so it needs a key, and so does a script.

Which URL do I add?

https://www.agentplanners.com/api/mcp — the same for every assistant and every workspace. You choose the workspace on the consent page, or by which workspace the API key belongs to.

Can Grok Bot or the Muse app use Agent Planners?

Neither documents a field for an MCP server URL today. Grok Bot can get it from a Cursor team admin's Team MCP server, or call the REST API with a key saved as a Bot secret; the Muse app can call the REST API through a custom connector you ask Muse to build. Muse Code supports the MCP server directly.

Will the assistant change my campaigns without asking?

Not unless the connection allows it. With the default setting each change waits for an admin or editor on API & MCP → Write approvals; deletes and other person-class changes always wait, and the workspace's guardrails apply either way.