An MCP server with no second execution path.
- tools, each a thin wrapper over exactly one REST endpoint
- 76
- groups, from extracting a persona to reconciling a statement
- 7
- tenant boundary, wallet gate, approval record and audit trail, shared with the browser
- 1
- consequential operations with no agent tool at all
- 11
One execution path, and the operations that are not on it
The MCP server is not a chat wrapper on a dashboard. Each of its 76 tools is a thin wrapper over exactly one REST endpoint — the same endpoint the browser calls — so the agent path and the human path share one tenant boundary, one wallet gate, one approval record and one audit trail. There is no second execution path with weaker rules, because there is no second execution path at all. The corollary is the more important half: 11 consequential operations are deliberately absent from the tool surface entirely. An agent prepares and proposes. A named human authorises money.
If that is the guarantee your risk team needs in writing, the session is where we walk them through it.
Talk it throughThere is no hosted AdBuyMCP connector to add.
read before the setup instructions below
MCP access today is a private, single-tenant, self-hosted deployment behind a bearer token or your own tunnel. There is no public connector to add and no multi-tenant sign-in. Establishing real OAuth 2.1 for public multi-tenant MCP is an open launch gate: the server publishes protected-resource metadata and scope challenges and refuses to mix OAuth with static tokens, but it does not embed an authorisation server, and a static bearer token is suitable only for a single-tenant deployment.
That is the whole of it. The instructions further down are for a server you run, on infrastructure you control, against an API you point it at, which is a different thing from a connector in a settings menu and worth knowing before you spend an afternoon on it. The buying rails underneath it are graded on the same standard, and built is not the same word as live.
11 operations with no tool at all
Not a permission that is switched off. There is no tool to call. These are human-only signed actions, and an agent that tries to authorise its own work is refused rather than throttled.
- Resolving an approval
- Resolving a campaign provider attempt
- Acknowledging a booking-workflow step
- Resolving an asset job
- Replacing a mandate
- Revoking a mandate
- Closing a mission
- Saving a supplier dossier
- Verifying a supplier dossier
- Issuing a live execution grant
- Revoking a live execution grant
and the rules underneath them
- Agents cannot replace or revoke authority.
- Agents cannot close missions.
- Agents cannot resolve human approvals.
- A human credential paired with the reserved MCP marker is rejected rather than silently taking the browser path.
- Approval records evidence; it cannot enable spend. Enabling spend is a separately granted action.
The last one is the one people miss. Approval and spend are two separately granted actions on purpose, because treating them as one is the most common way a platform spends money nobody meant to spend.
If your objection to agentic buying is this list, that is the right objection, and it is worth half an hour.
Talk it through76 tools, in 7 groups
Grouped by the job rather than by the route, because the useful question is not how many tools there are, it is whether the loop you run is covered end to end. Open a group to read the names.
Missions and authority
The control plane an agent works inside: a durable mission, a bounded mandate, ordered steps, and an exception that stops the run rather than being retried.
19 tools
- list_agent_actions
- prepare_agent_action
- create_agent_mission
- list_agent_missions
- get_agent_mission
- start_agent_run
- list_agent_runs
- get_agent_run
- add_agent_step
- complete_agent_step
- request_agent_approval
- advance_agent_run
- raise_agent_exception
- list_agent_exceptions
- resolve_agent_exception
- resume_agent_run
- record_agent_decision
- record_agent_evidence
- finish_agent_run
Audience and planning
Turn a sentence into a persona, compile it to seven channels, and produce a funded plan — or pick the inventory by hand.
13 tools
- list_personas
- extract_persona
- compile_persona
- browse_inventory
- generate_plan
- create_manual_plan
- list_plans
- get_plan
- update_plan_allocations
- approve_plan
- suggest_search_keywords
- get_plan_search_keywords
- set_plan_search_keywords
Creative
Generate channel-correct creative, precheck it against the format and clearance rules, revise it in your own words, and submit it.
8 tools
- generate_creative
- precheck_creative
- revise_creative
- set_campaign_creatives
- submit_creative
- get_asset_pricing
- produce_asset
- get_asset_status
Launch and lifecycle
Fund, launch, pause and resume, with readiness and the provider-attempt ledger visible rather than inferred.
9 tools
- launch_campaign
- pause_campaign
- resume_campaign
- list_campaigns
- get_campaign
- get_campaign_readiness
- list_live_execution_grants
- list_campaign_attempts
- get_campaign_dead_letters
Delivery and measurement
The four verbs, the journey view, the audience sync, and the one button that refuses to run an underpowered test.
13 tools
- get_delivery
- get_measurement
- get_campaign_tracking
- set_campaign_tracking
- import_outcomes
- get_outcome_health
- get_campaign_report
- prove_it
- get_campaign_insights
- get_journeys
- sync_audience
- mmm_readiness
- run_micro_mmm
Optimisation
Explainable proposals that wait for a human. An optimiser that moves budget on its own is a different product with a different risk profile.
4 tools
- generate_optimizations
- list_optimizations
- approve_optimization
- reject_optimization
Money, connections and audit
The wallet, the fee statement, the supplier dossiers, and the trail that says who did what.
10 tools
- get_workspace_overview
- get_brand_analytics
- list_connections
- get_supplier_dossier
- set_connection
- get_billing_summary
- get_billing_statement
- get_topup_status
- top_up_wallet
- get_audit
// the list is not maintained by hand. It is read off the server’s own source of truth, and a test asserts that registration, output schemas and safety annotations all match it, so the surface published here cannot drift from the surface the server exposes.
Protocol and transport
Two eras of the protocol, both pinned by tests rather than assumed, and a boundary that refuses rather than guesses.
Modern MCP, 2026-07-28
Served over both streamable HTTP and stdio. Modern clients negotiate with server/discover, and every later request carries the negotiated version plus client identity and capabilities in its metadata envelope.
Legacy clients still work, and it is tested
Pre-2026 clients may use the legacy initialize handshake over stdio or stateless HTTP. Legacy HTTP returns JSON with no session id and is not silently routed through the modern handler's SSE fallback. The suite pins modern negotiation, the latest legacy negotiation, a 2025-03-26 HTTP round trip, exact tool registration, wire metadata and cancellation in both eras.
Stateless HTTP
The HTTP transport needs no session affinity, so it works behind tunnels and load balancers without sticky routing.
The boundary is fail-closed
Production must set exact allowed hosts and allowed browser origins — none for a deployment with no browser clients. Local execution binds to loopback unless a container deployment opts into 0.0.0.0 explicitly. Verifier time, request concurrency and JSON body size are all bounded, and a modern HTTP request that omits its protocol version header is rejected before dispatch, preserving the JSON-RPC id and making no downstream call.
Why your Claude session is not an agent credential
The most consequential design decision in this server is a refusal. A human's ordinary web session cannot be forwarded as an agent's API credential, and the attempt fails with a 401 rather than quietly working.
Every request carries a verified actor class that cannot be changed by adding or removing headers. Ordinary human sessions are deliberately classified as human and web; the MCP client's fixed source marker makes that pairing fail rather than silently taking the browser path. An agent credential must be either a configured service token or a verified delegated token carrying a signed agent actor claim and a non-empty verified client id. The API also refuses to let an agent credential resolve a human approval, and it persists actor, source and client attribution on every action. It matters because the alternative — an agent inheriting whatever a logged-in human can do — is how an agent ends up authorising its own spend.
the three modes, and which one exists
Local development
Run the API with auth disabled and the MCP server needs no environment variables at all. This mode is explicitly not an authentication boundary — it grants its single dev identity every human permission implicitly — and it is labelled that way in the code rather than only in the docs.
Private single-tenant
A service token plus an advertiser id on the API, and the matching token on MCP. Use a distinct random token per tenant-scoped deployment. Suitable for one organisation, never as public multi-user auth.
Public OAuth
open launch gateNot shipped. A trusted runtime module would supply the integration, and startup already fails if OAuth is mixed with static tokens, but the package deliberately does not invent or embed an authorisation server. Choosing the issuer, client registration, callback allowlist, consent and tenant claim — and a broker or separately reviewed verifier for a non-Clerk issuer — is an open launch gate rather than a configuration step.
Your CISO will want the rest of it, and the security page is where the encryption, retention and identity boundaries are written down.
Pointing a client at a deployment you run
Any MCP-compatible client can drive this server. The three below are named because they are the clients most people already have, not because the server knows the difference.
MCP access today is a private, single-tenant, self-hosted deployment behind a bearer token or your own tunnel.
Everything below assumes you are running the server yourself. The full position is above.
Claude Code
stdioclaude mcp add adbuymcp -- node /path/to/adbuymcp/apps/mcp/dist/stdio.jsThe recommended local path. Point it elsewhere with --env ADBUY_API_URL=...
Claude Code
HTTPclaude mcp add --transport http adbuymcp http://localhost:4200/mcpStart the server first. Add --header "Authorization: Bearer <token>" if a bearer secret is set.
Claude Desktop
stdio{ "mcpServers": { "adbuymcp": { "command": "node", "args": ["/path/to/apps/mcp/dist/stdio.js"] } } }Goes in claude_desktop_config.json. Restart Desktop and the tools appear under the hammer icon.
claude.ai
Remote HTTPSettings → Connectors → Add custom connector → https://<your-host>/mcpFor a deployment you host and control. Expose the HTTP transport over HTTPS with a bearer secret set, and add the exact hostname to the allowed-hosts list before accepting traffic. There is no hosted AdBuyMCP connector to add, and the unauthenticated server must never be exposed.
// GET /healthz returns service status and the API URL, with no authentication required.
Discovery hints, and what they are not
These are discovery hints that help a client decide what to surface and what to confirm. They are not the security boundary. The boundary is the API's fail-closed execution hook, which rejects any consequential call that does not match a registered action and an approval granted for those exact bytes.
- 38 of 76
- Read-only
- 27 of 76
- Destructive
- 17 of 76
- Idempotent
- 14 of 76
- Open-world
// the four sets overlap. They add to more than 76, because one tool can carry more than one hint.
Do not read these as a permission model
A hint tells a client what to surface and what to confirm before it calls. It does not decide whether the call is allowed, and a client that ignored every one of them would not get further than a client that read them all. The refusal happens at the API, where a consequential call is rejected unless it matches a registered action and an approval granted for those exact bytes, which is the same gate the browser passes through.
What buyers ask about the MCP server
The hosted-connector question first, because it is the one that changes what you do next.
Can I connect to a hosted AdBuyMCP server today?
No. What exists is a server you deploy yourself, single-tenant, behind a bearer token or your own tunnel. Public multi-tenant MCP needs an OAuth 2.1 authorisation server issuing per-user, per-organisation, audience-bound tokens, and the package deliberately does not embed one — that is an open gate rather than a setting. The setup instructions below are for a deployment you control.
Is MCP the product, or a feature of it?
A feature, and the site is named after it because it is the feature that changes how the product is used rather than the one that makes it defensible. MCP is an integration surface — Amazon and other advertising platforms already expose one — so an MCP server alone is not a moat. What is unusual here is that the agent transport and the browser are the same execution path, so pointing an agent at a media budget does not mean accepting a weaker set of rules than a person would get.
Can Claude spend my money without asking?
No, and the block is structural rather than a permission you remember to switch off. Consequential calls fail closed unless the incoming request matches an approval a human granted for those exact bytes, spend runs against a mandate with an explicit money ceiling and expiry, and enabling spend on a live line is a separately granted action that approval alone cannot perform. Agents cannot revoke or replace authority, close missions, or resolve human approvals.
What happens when a supplier returns something ambiguous?
The run stops. An ambiguous outcome raises an exception that requires an explicit human resolution before the run resumes, and it is never blindly retried. That is the specific failure this design exists to prevent: an agent that cannot read a supplier's response and tries again has just created a second campaign it does not know about.
Which MCP protocol versions do you support?
The modern 2026-07-28 protocol over both streamable HTTP and stdio, with server/discover negotiation and per-request metadata. The pre-2026 initialize handshake also works over stdio and stateless HTTP, and the compatibility path is pinned by tests rather than assumed — including a 2025-03-26 HTTP round trip and cancellation behaviour in both eras.
Can I use this from something other than Claude?
Yes. It is a standard MCP server over stdio and streamable HTTP, so any MCP-compatible client can drive it. The setup instructions name Claude Code, Claude Desktop and claude.ai because those are the clients most people have, not because the server knows the difference.