Docs / Bring your own agent

Connect your AI agent to Wavefront (MCP)

Wavefront exposes its full content platform as a remote MCP server. Connect it to Cursor, Claude Code, Claude Desktop, or any MCP-capable agent and that agent can plan, draft, illustrate, validate, and publish content in your workspace, using your brand rules, your keyword registry, and your CMS connection. All third-party API keys (CMS, image generation, scraping, LLM) live on the platform; you never configure them in your client.

A common setup: you're building an app in Cursor and want to publish a launch post or changelog article about it. Your coding agent already knows your codebase; adding Wavefront gives it the publishing pipeline. See the step-by-step tutorial.

Requirements

A Wavefront account with a Pro or Scale plan (bring-your-own-agent is a paid feature; the server answers 403 with an upgrade message otherwise).
Your workspace role determines what the agent can do: viewers get read tools, members get write tools, admins get everything. The agent authenticates as you.

Server URL

https://api.wavefront.adwave-apps.com/mcp

Your workspace Settings page (Settings -> Connect an AI agent) shows the exact URL for your deployment and manages issued tokens.

Connect from Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "wavefront": { "url": "https://api.wavefront.adwave-apps.com/mcp" }
  }
}

Cursor detects the server, runs the OAuth flow in your browser (sign in with Google), and stores a per-user token. No API key needed.

Connect from Claude Code

claude mcp add --transport http wavefront https://api.wavefront.adwave-apps.com/mcp

Then run /mcp inside Claude Code to complete authentication.

Connect from Claude Desktop

Settings -> Connectors -> Add custom connector, paste the server URL, and complete the sign-in when prompted.

First calls

get_agent_context - call this first. It returns the master workflow, key constants, and tool-usage recipes (write a new article, edit a live one, ideation, AI SEO, and more). It is the runtime source of truth for how to drive the server.
get_generation_rules - the voice/SEO/format rules to follow before writing anything.

The full tool reference is in the tool catalog, including the current tool count. External clients see the content surface filtered to your role; internal agent-runner plumbing is hidden.

Tool profiles

By default your client lists the essential profile: ~40 tools covering the whole core loop (orient -> plan -> brief -> draft -> validate -> images -> publish -> measure). This keeps the catalog small enough for coding agents to use reliably.

Want everything (Link Network, visibility battery, beliefs, webhooks, workspace admin)? Append ?tools=all to the server URL:

https://api.wavefront.adwave-apps.com/mcp?tools=all

The flag only changes what tools/list returns. Any tool your role allows stays callable by name either way, so recipes that reference an advanced tool keep working on the default profile. Essential tools are marked in the tool catalog.

Auth model

The server is its own OAuth 2.1 authorization server (dynamic client registration + PKCE) with Google as the identity provider. MCP clients handle the whole flow; you just approve the sign-in.
Tokens are org-scoped and revoked immediately when your membership is removed.
Manage tokens from Settings, or with the list_mcp_tokens / revoke_mcp_token tools (admin).

Rate limits

Requests are rate-limited per workspace, sized by plan. When you exceed the limit the server returns HTTP 429 with a Retry-After header and JSON-RPC error code -32029 ("Rate limit exceeded; retry in Ns"). Back off and retry; well-behaved MCP clients do this automatically.

Metered features (image generation, scraping, keyword enrichment, publishes) also count against your plan quotas; get_billing shows usage vs limits.

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	No token, or the token expired/was revoked	Re-run the client's authentication (Cursor: MCP settings -> reconnect; Claude Code: `/mcp`)
`403` with "requires the Pro plan" (`-32002`)	Workspace plan below Pro	Upgrade in Billing, or use the in-app assistant instead
`429` / `-32029`	Per-org rate limit	Wait for `Retry-After` seconds
"Insufficient role: X requires writer/admin"	Your membership role is too low for that tool	Ask a workspace admin to raise your role
OAuth sign-in never completes	Google OAuth not configured on the deployment	Operator action: see below
A tool you expect is missing from the list	It's admin-gated above your role, or internal	Check the tool catalog for each tool's minimum role

Local development (self-hosting)

Running the stack locally (npm run dev:mcp)? Skip OAuth with a static bearer token: set ALLOW_DEV_AUTH=true and DEV_MCP_TOKEN=<token> in app/.dev.vars, then send Authorization: Bearer <token> to http://localhost:8787/mcp. Never enable this in production.

Operator prerequisites (per deployment)

External agents cannot connect until the operator has:

Created a Google OAuth client (Web) with the deployment's /callback URL as an authorized redirect URI, and set OAUTH_GOOGLE_CLIENT_ID (var) + OAUTH_GOOGLE_CLIENT_SECRET (secret) on the MCP worker.
Set MCP_PUBLIC_URL on the web worker so Settings shows the correct connect URL.
Set CREDENTIALS_MASTER_KEY (required for per-org CMS/API credentials).

See app/infra/README.md ("MCP OAuth") and app/DEPLOY.md for details.