AEOForgedAEOForged
Join

MCP Setup Guide

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.

1. Get credentials

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.

2. Configure Your Agent

Cursor

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"
      }
    }
  }
}

Claude Code

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"
      }
    }
  }
}

VS Code / GitHub Copilot

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"
      }
    }
  }
}

Windsurf

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"
      }
    }
  }
}

Claude Desktop & other stdio-only clients

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" }
    }
  }
}

Any other client

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".

If your assistant has no way to add a custom MCP server with an Authorization header — ChatGPT’s web connectors today — it cannot reach a workspace. Connect your site to AEOForged and we apply the fixes, or open the developer fix sheet from the room and apply them by hand.

3. Consolidated Verbs (recommended)

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.

VerbCreditsDescription
aeo_create20/~44Produce a finished, grounded article — single, gated to a target score, or a multi-article strategy. Replaces full_pipeline, generate, quality_gate, strategy.
aeo_improve2-8Transform 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_packageFree/3Turn finished content into machine-readable artifacts: JSON-LD, featured-snippet formats, or llms.txt. Replaces schema, extract, llms_txt.
aeo_audit5Single URL: fetch + score + improvement plan + crawlability + deterministic grounding.
aeo_diagnoseFreeSite-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_factcheckFreeDeterministic grounding: extract statistical claims and verify each against research sources. No LLM, reproducible. Prefer over aeo_verify for statistics.
aeo_visibility10Estimate 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".

4. Tool catalog (representative — live list after connect)

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_accountFree

Account info: tier, credit balance, per-tool costs

aeo_scoreFree

8-dimension AEO scoring (0-100), page-type aware — publish-readiness feedback, not a citation guarantee

aeo_schemaFree

Generate Article + FAQPage + HowTo JSON-LD structured data

aeo_extractFree

Reformat content for featured snippets, knowledge panels, and PAA

aeo_research10/15 credits

Live web research + LLM synthesis. Standard (10cr) or deep (15cr). Async by default (202 + poll_url).

aeo_outline3 credits

Structured outline from research JSON with snippet and word-count targets

aeo_write8 credits

Section-by-section hosted draft; requires research sources (422 research_required otherwise)

aeo_importFree

Import external markdown or URL into a workspace as a baseline-scored content-mode article

aeo_polish2 credits

Brand-voice polish pass with changelog (prefer aeo_improve mode voice)

aeo_verify2 credits

LLM review of non-statistical claims. For statistics, prefer aeo_factcheck (free).

aeo_factcheckFree

Deterministic statistical grounding against the research allow-list. No LLM.

aeo_audit5 credits

Fetch a URL, score it, and get a prioritized improvement plan

aeo_compare3 credits

Compare two articles head-to-head across all 8 AEO dimensions

aeo_refresh8 credits

Fresh research + targeted update plan (prefer aeo_improve mode freshness)

aeo_cluster5 credits

Keyword clustering + content hierarchy with content calendar

aeo_full_pipeline12/20 credits

Legacy end-to-end pipeline. Prefer aeo_create for new integrations.

aeo_submit_for_reviewFree

Client review gate; enforces grounding + score bar (≥80) unless human-authorized override

aeo_gate_statusFree

Read the review gate next action; poll at most twice, then stop when it returns wait

aeo_ask_humanFree

Durable 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 credits

Build client intelligence: brand voice, company facts, competitors, audience

aeo_optimise8 credits

Page-level section analysis and AEO-oriented rewrites (prefer aeo_improve mode aeo)

aeo_complete_auditFree

Site-wide audit → snapshot + action items. Async by default. Prefer aeo_diagnose for new work.

aeo_verify_pageFree

Re-fetch URL, re-score vs snapshot baseline; sole path that promotes items to verified

aeo_audit_queueFree

Read an audit snapshot's action queue: status counts + prioritised open backlog

aeo_action_updateFree

Transition one action item: claim, done, blocked+reason, reopen. Rejects verified.

aeo_apply_fixFree

Apply 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_reviewFree

Structured page review only (read when only url; write when review fields are present). Do not apply fixes in this tool.

aeo_document_fixFree

Capture a Remediation Story (problem + fix) for an action item. No LLM.

aeo_crawlabilityFree

Check AI bot access: robots.txt, meta directives, llms.txt, sitemap, JS rendering

aeo_agent_readyFree

Probe-based agent readiness: agent UAs, forms, commerce schema, protocol signals

aeo_agent_policy3 credits

Generate robots.txt agent allow rules + AGENT-POLICY.md draft

aeo_llms_txt3 credits

Generate spec-compliant llms.txt + llms-full.txt with semantic page grouping

aeo_share_of_voice10 credits

Brave-search visibility proxy (likely visibility, not confirmed citations). Prefer aeo_visibility.

aeo_moat_check15 credits

Competitive gap analysis: topic/format/schema/depth gaps and action plan

aeo_citation_sourcesFree

Off-site sources real answer engines cite for tracked queries (measured checks — not Brave proxy)

aeo_citation_graphFree

Measured hubs and clusters for this workspace's tracked queries — not a citation guarantee, not the Brave proxy

aeo_workspace_contextFree

Typed join of this workspace's records (index or one neighbourhood). Not a citation guarantee; hub URLs are not an allow-list

aeo_edit_handshakeFree

Persist whether this session can change this room's signup host. Omit result for briefing; honor-system files_match. Then stop.

aeo_jobsFree

Index 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_logsFree

Parse an access-log export for AI bots seen, top pages, errors, crawl-vs-citation cross-ref

aeo_authority0-8* credits

Authority OS modes (audit, blueprint, distribution, entity, nap_scan, …). Costs by mode — see aeo_account / onboard.

aeo_study8* credits

Original Research Engine: design → run → draft → register. Lane-priced runs; depth floors refuse thin samples.

aeo_trackFree

Register a URL for Brave-proxy visibility monitoring — not measured engine citations

aeo_workflow_audit_improve5-13 credits

Composite: audit URL + conditional refresh (prefer aeo_diagnose / aeo_improve)

aeo_workflow_strategy~44 credits

Composite: cluster → research + outline pillars (prefer aeo_create mode strategy)

aeo_workflow_health5/URL credits

Composite: batch-audit up to 10 URLs (prefer aeo_diagnose)

aeo_workflow_quality_gateFree

Composite: score against target threshold (prefer aeo_create mode gate)

5. Example Workflows

Create from scratch (grounded)

1

One-call create (recommended for lightweight agents)

Call aeo_create — researches, drafts, strips bad citations, scores, and packages in one grounded path.

2

Or step through: research → outline → write

aeo_research first (required for grounding), then aeo_outline → aeo_write. Weave research URLs as inline citations.

3

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.

Audit and verify fixes

1

Diagnose the site

aeo_diagnose / aeo_complete_audit (async). Pass workspace_id when using an account key.

2

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 & research

1

Authority program

aeo_authority mode audit (free), then blueprint / distribution / entity modes as needed. Costs by mode from aeo_account.

2

Original research study

aeo_study design → run → draft → register. Measurement is deterministic; thin samples are refused in code.

6. What Agents Should Know

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.

7. Real-Time Project Sync

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

  1. Create a project in the AEOForged web app — copy its ID from the URL
  2. Open the project page in your browser
  3. In Cursor/Claude Code, tell your agent: “Research [keyword] and save to project [id]”
  4. Watch research, outline, and content appear as the agent works
  5. Step in any time — edit on the page or redirect the agent in chat

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."

8. Troubleshooting

401 Unauthorized / "Missing API key"

  • Check the URL is exactly /api/mcp/mcp (the second mcp is the Streamable HTTP transport segment).
  • Header must be Authorization: Bearer aeo_sk_... or Bearer aeo_ho_... (case-sensitive "Bearer").
  • Test your key: curl -H "Authorization: Bearer KEY" https://aeoforged.com/api/v1/me

402 / insufficient_credits

  • Call aeo_account first to confirm your balance and tier.
  • Free tier has 0 credits — buy a top-up at Settings → Billing.
  • Credits are charged after a tool succeeds, so failed runs are free.

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

  • Free: 10 req/min. Pro: 60/min. Team: 120/min. Free tier also has a 100-call/day cap on free tools (aeo_score, aeo_schema).
  • The retry_after_seconds field tells you when to retry.

Tool list is empty / agent can't see tools

  • After editing your MCP config, fully restart the agent (Cursor: reload window; Claude Code: restart).
  • Verify the server appears in MCP UI as "connected". If it shows red, open the agent's MCP logs.
  • Some clients require mcp-remote bridge — see the "Other MCP Clients (stdio bridge)" section above.

Network / timeout errors

  • AEOForged MCP uses Streamable HTTP. Outbound HTTPS must be allowed to aeoforged.com.
  • Prefer async + poll for long tools instead of raising client timeouts indefinitely.

Guide refreshed 2026-08-08. Prefer live GET /api/v1/onboard over any static tool list when costs or modes disagree.