Cookies & analytics
Essential cookies keep you signed in. Analytics load only with your OK. Privacy Policy
Connect your AI agents to AEOForged via the Model Context Protocol.
Last updated
This guide shows you how to connect AEOForged to Cursor, Claude Code, or any MCP-compatible client in three steps: create an API key (or use a project handoff token), add the MCP server config pointing athttps://aeoforged.com/api/mcp/mcp, and reload the agent. Once connected, the agent gains the live tool catalog (tools/list). A filtered tools/list is returned for handshake tokens, audit-session tokens, and handoffs labelled Jobs list, Page fix batch, Technical fix batch, or Article revision. Jobs Send still mints a Jobs-list key so a job session can call aeo_jobs; the paste itself is the work order, not an MCP install. The standing Client MCP / Connect-your-agent key stays the coworker catalog. Handshake keys may only call aeo_edit_handshake. After that, the same MCP works the Jobs list (aeo_jobs). Consolidated verbs compose multiple tools behind a single intent-driven call. For the live catalog and costs, call GET /api/v1/onboard or aeo_account.
Account API key (aeo_sk_…): sign in, go to Settings → API Keys, and create a key. Copy it immediately — it's only shown once.
Project handoff (aeo_ho_…): a human mints a short-lived, workspace-scoped token from the dashboard. Bootstrap with GET /api/v1/handoff/{token}, then use the same token as Authorization: Bearer. Handoff tokens cannot call account-level listings outside their Project.
Add an OAuth connector using https://aeoforged.com/api/mcp/mcp. claude.ai custom connectors need a Pro, Max, Team, or Enterprise plan. ChatGPT connectors need developer mode on Business, Enterprise, or Edu. If you are on a free chat plan, use the agent in this room instead. IDE clients still use a bearer key.
Add this to your Cursor MCP settings (.cursor/mcp.json or IDE settings):
{
"mcpServers": {
"aeoforge": {
"url": "https://aeoforged.com/api/mcp/mcp",
"headers": {
"Authorization": "Bearer aeo_sk_YOUR_KEY_HERE"
}
}
}
}One command writes the config for you:
claude mcp add --transport http aeoforge \ https://aeoforged.com/api/mcp/mcp \ --header "Authorization: Bearer aeo_sk_YOUR_KEY_HERE"
Or add it to .mcp.json in your project root:
{
"mcpServers": {
"aeoforge": {
"type": "http",
"url": "https://aeoforged.com/api/mcp/mcp",
"headers": {
"Authorization": "Bearer aeo_sk_YOUR_KEY_HERE"
}
}
}
}Add to .vscode/mcp.json. The top-level key is servers, not mcpServers — a config copied from Cursor loads nothing and shows no error. Then switch Copilot to Agent mode.
{
"servers": {
"aeoforge": {
"type": "http",
"url": "https://aeoforged.com/api/mcp/mcp",
"headers": {
"Authorization": "Bearer aeo_sk_YOUR_KEY_HERE"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json. The field is serverUrl, not url — with url Windsurf fails silently. Press Refresh in Cascade after saving.
{
"mcpServers": {
"aeoforge": {
"serverUrl": "https://aeoforged.com/api/mcp/mcp",
"headers": {
"Authorization": "Bearer aeo_sk_YOUR_KEY_HERE"
}
}
}
}For clients that launch a local command instead of calling a URL, bridge with mcp-remote (needs Node). In Claude Desktop use Settings → Developer → Edit Config — not “Add custom connector”, which insists on OAuth and cannot take this token. Keep the token in env and leave no space around the colon in the header: Cursor and Claude Desktop on Windows split the argument there and the call 401s.
{
"mcpServers": {
"aeoforge": {
"command": "npx",
"args": [
"-y", "mcp-remote@latest",
"https://aeoforged.com/api/mcp/mcp",
"--header", "Authorization:${AEOFORGE_TOKEN}"
],
"env": { "AEOFORGE_TOKEN": "Bearer aeo_sk_YOUR_KEY_HERE" }
}
}
}Use the Cursor shape above — mcpServers + url + an Authorization header is the most common form for a remote MCP server. If it will not connect, your client wants a variant: servers instead of mcpServers, serverUrl instead of url, or an added "type": "http".
For claude.ai and ChatGPT, use Cursor, Claude Code, VS Code, or Windsurf with the config above; connect your site to AEOForged and we apply the fixes; open the developer fix sheet from Pages and apply them by hand; or add the OAuth connector from this room's Connect section.
New integrations should prefer these intent-driven verbs. Each composes multiple granular tools behind a single call. The granular tools remain as stable aliases. REST twins live under /api/v1/{verb} — see the REST API reference.
| Verb | Credits | Description |
|---|---|---|
aeo_create | 20/~44 | Produce a finished, grounded article — single, gated to a target score, or a multi-article strategy. Replaces full_pipeline, generate, quality_gate, strategy. |
aeo_improve | 2-8 | Transform existing content: brand voice, AEO rewrite, score-driven rewrite, freshness plan, or humanize. Pass project_id to save the result onto that project's draft. Replaces polish, optimise, refresh. |
aeo_package | Free/3 | Turn finished content into machine-readable artifacts: JSON-LD, featured-snippet formats, or llms.txt. Replaces schema, extract, llms_txt. |
aeo_audit | 5 | Single URL: fetch + score + improvement plan + crawlability + deterministic grounding. |
aeo_diagnose | Free | Site-wide audit: discover pages, score each, benchmark competitors, action plan. Async by default (202 + poll_url). Replaces complete_audit, workflow_health, workflow_audit_improve. |
aeo_factcheck | Free | Deterministic grounding: extract statistical claims and verify each against research sources. No LLM, reproducible. Prefer over aeo_verify for statistics. |
aeo_visibility | 10 | Estimate AI-answer share of voice vs competitors. Brave web-search proxy — report as likely visibility, not confirmed citations. Async by default. |
Long-running verbs (aeo_diagnose, aeo_visibility, aeo_research, study runs) return 202 with a poll_url / run_id by default. Poll GET /api/v1/tool-runs/{run_id} until status: "complete".
Highlights across content creation, diagnosis, authority, original research, action queue, and monitoring. After you connect MCP, your client's tool list is authoritative; costs also appear on aeo_account and GET /api/v1/onboard. Costs marked * vary by mode or lane — never invent prices.
aeo_accountFreeAccount info: tier, credit balance, per-tool costs
aeo_scoreFree8-dimension AEO scoring (0-100), page-type aware — publish-readiness feedback, not a citation guarantee
aeo_schemaFreeGenerate Article + FAQPage + HowTo JSON-LD structured data
aeo_extractFreeReformat content for featured snippets, knowledge panels, and PAA
aeo_research10/15 creditsLive web research + LLM synthesis. Standard (10cr) or deep (15cr). Async by default (202 + poll_url).
aeo_outline3 creditsStructured outline from research JSON with snippet and word-count targets
aeo_write8 creditsSection-by-section hosted draft; requires research sources (422 research_required otherwise)
aeo_importFreeImport external markdown or URL into a workspace as a baseline-scored content-mode article
aeo_polish2 creditsBrand-voice polish pass with changelog (prefer aeo_improve mode voice)
aeo_verify2 creditsLLM review of non-statistical claims. For statistics, prefer aeo_factcheck (free).
aeo_factcheckFreeDeterministic statistical grounding against the research allow-list. No LLM.
aeo_audit5 creditsFetch a URL, score it, and get a prioritized improvement plan
aeo_compare3 creditsCompare two articles head-to-head across all 8 AEO dimensions
aeo_refresh8 creditsFresh research + targeted update plan (prefer aeo_improve mode freshness)
aeo_cluster5 creditsKeyword clustering + content hierarchy with content calendar
aeo_full_pipeline12/20 creditsLegacy end-to-end pipeline. Prefer aeo_create for new integrations.
aeo_submit_for_reviewFreeClient review gate; enforces grounding + score bar (≥80) unless human-authorized override
aeo_gate_statusFreeRead the review gate next action; poll at most twice, then stop when it returns wait
aeo_ask_humanFreeDurable decision gate: ask a question, poll at most twice. When wait, stop and tell the human. REST: POST/GET /api/v1/decisions.
aeo_client_profile5 creditsBuild client intelligence: brand voice, company facts, competitors, audience
aeo_optimise8 creditsPage-level section analysis and AEO-oriented rewrites (prefer aeo_improve mode aeo)
aeo_complete_auditFreeSite-wide audit → snapshot + action items. Async by default. Prefer aeo_diagnose for new work.
aeo_verify_pageFreeRe-fetch URL, re-score vs snapshot baseline; sole path that promotes items to verified
aeo_audit_queueFreeRead an audit snapshot's action queue: status counts + prioritised open backlog
aeo_action_updateFreeTransition one action item: claim, done, blocked+reason, reopen. Rejects verified.
aeo_apply_fixFreeApply one item's fix through the connected CMS or GitHub — for agents with no site files. GitHub opens a PR (proposed, not live).
aeo_page_reviewFreeStructured page review only (read when only url; write when review fields are present). Do not apply fixes in this tool.
aeo_document_fixFreeCapture a Remediation Story (problem + fix) for an action item. No LLM.
aeo_crawlabilityFreeCheck AI bot access: robots.txt, meta directives, llms.txt, sitemap, JS rendering
aeo_agent_readyFreeProbe-based agent readiness: agent UAs, forms, commerce schema, protocol signals
aeo_agent_policy3 creditsGenerate robots.txt agent allow rules + AGENT-POLICY.md draft
aeo_llms_txt3 creditsGenerate spec-compliant llms.txt + llms-full.txt with semantic page grouping
aeo_share_of_voice10 creditsBrave-search visibility proxy (likely visibility, not confirmed citations). Prefer aeo_visibility.
aeo_moat_check15 creditsCompetitive gap analysis: topic/format/schema/depth gaps and action plan
aeo_citation_sourcesFreeOff-site sources real answer engines cite for tracked queries (measured checks — not Brave proxy)
aeo_citation_graphFreeMeasured hubs and clusters for this workspace's tracked queries — not a citation guarantee, not the Brave proxy
aeo_workspace_contextFreeTyped join of this workspace's records (index or one neighbourhood). Not a citation guarantee; hub URLs are not an allow-list
aeo_edit_handshakeFreePersist whether this session can change this room's signup host. Omit result for briefing; honor-system files_match. Then stop.
aeo_jobsFreeIndex of this workspace's Jobs. Omit job_id for the list; pass job_id for one row. Technical rows carry fix/snippet; article rows carry the hosted draft.
aeo_crawler_logsFreeParse an access-log export for AI bots seen, top pages, errors, crawl-vs-citation cross-ref
aeo_authority0-8* creditsAuthority OS modes (audit, blueprint, distribution, entity, nap_scan, …). Costs by mode — see aeo_account / onboard.
aeo_study8* creditsOriginal Research Engine: design → run → draft → register. Lane-priced runs; depth floors refuse thin samples.
aeo_trackFreeRegister a URL for Brave-proxy visibility monitoring — not measured engine citations
aeo_workflow_audit_improve5-13 creditsComposite: audit URL + conditional refresh (prefer aeo_diagnose / aeo_improve)
aeo_workflow_strategy~44 creditsComposite: cluster → research + outline pillars (prefer aeo_create mode strategy)
aeo_workflow_health5/URL creditsComposite: batch-audit up to 10 URLs (prefer aeo_diagnose)
aeo_workflow_quality_gateFreeComposite: score against target threshold (prefer aeo_create mode gate)
One-call create (recommended for lightweight agents)
Call aeo_create — researches, drafts, strips bad citations, scores, and packages in one grounded path.
Or step through: research → outline → write
aeo_research first (required for grounding), then aeo_outline → aeo_write. Weave research URLs as inline citations.
Score loop, then review gate
aeo_score (free) → aeo_improve mode to-score until ≥80 → aeo_submit_for_review. On blockers use aeo_ask_human; wait means stop.
Diagnose the site
aeo_diagnose / aeo_complete_audit (async). Pass workspace_id when using an account key.
Claim → apply → verify
aeo_audit_queue → aeo_action_update (in_progress → done) → aeo_verify_page. Optionally aeo_document_fix for a Remediation Story. Never set verified yourself.
No site files in your session (a CMS client, or a chat with no repo)? Ship the change with aeo_apply_fix through the client’s connected CMS or GitHub instead of searching for a repo. A GitHub apply opens a pull request — proposed, not live.
Authority program
aeo_authority mode audit (free), then blueprint / distribution / entity modes as needed. Costs by mode from aeo_account.
Original research study
aeo_study design → run → draft → register. Measurement is deterministic; thin samples are refused in code.
Key patterns for agents using AEOForged tools effectively:
Credit awareness
Call aeo_account before expensive workflows. Score, schema, extract, diagnose, factcheck, verify_page, citation_sources, and crawler_logs are free. Do not invent credit prices — use the account / onboard cost tables.
Grounding + score bar
Research before write. Submit-for-review requires research-allow-listed citations and score ≥ 80 (or a human-authorized low-score acknowledgment). Payment and package checkout are human-only.
Error handling
On 402, stop and inform the user about credits. On 422, read the code (research_required, ungrounded_content, below_score_bar) and follow next_steps. On 429, wait retry_after_seconds. Failed tools never consume credits.
Citation honesty
aeo_visibility / aeo_share_of_voice / aeo_track use a Brave-search proxy. Measured engine citations come from the visibility scoreboard and aeo_citation_sources.
Tool chaining order
Always research before outlining/writing, factcheck statistics after drafting, and score after every edit (it's free). See the Workflow Recipes or download an Agent Skill to give your agent this knowledge automatically.
Pass a project_id to research, outline, and write so output is saved to the workspace article. Open the project page in your browser to review while the agent works.
How it works
Tools such as aeo_research, aeo_outline, aeo_write, and aeo_score accept an optional project_id (UUID). When provided, results persist to that article so the human can review in the dashboard.
The workflow
Agent prompt example
"Research 'answer engine optimization' and save to project abc12345-6789-def0-1234-567890abcdef. Then generate an outline and score it. Use project_id on every call so I can watch progress on the site."
401 Unauthorized / "Missing API key"
/api/mcp/mcp (the second mcp is the Streamable HTTP transport segment).Authorization: Bearer aeo_sk_... or Bearer aeo_ho_... (case-sensitive "Bearer").curl -H "Authorization: Bearer KEY" https://aeoforged.com/api/v1/me402 / insufficient_credits
aeo_account first to confirm your balance and tier.422 grounding / score bar
research_required / ungrounded_content — run aeo_research, cite allow-listed URLs, or use aeo_create.below_score_bar — improve to ≥80, or aeo_ask_human then resubmit with an authorized acknowledgment.429 / rate_limited
aeo_score, aeo_schema).retry_after_seconds field tells you when to retry.Tool list is empty / agent can't see tools
mcp-remote bridge — see the "Other MCP Clients (stdio bridge)" section above.Network / timeout errors
aeoforged.com.Guide refreshed 2026-08-08. Prefer live GET /api/v1/onboard over any static tool list when costs or modes disagree.