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 29-tool surface plus consolidated verbs that 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

Add to your ~/.claude/mcp_servers.json:

{
  "aeoforge": {
    "type": "url",
    "url": "https://aeoforged.com/api/mcp/mcp",
    "headers": {
      "Authorization": "Bearer aeo_sk_YOUR_KEY_HERE"
    }
  }
}

Other MCP Clients (stdio bridge)

For clients that only support stdio transport, use mcp-remote:

{
  "aeoforge": {
    "command": "npx",
    "args": [
      "-y", "mcp-remote",
      "https://aeoforged.com/api/mcp/mcp",
      "--header", "Authorization: Bearer aeo_sk_YOUR_KEY_HERE"
    ]
  }
}

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. 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 (29+ tools)

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; stop when it returns wait

aeo_ask_humanFree

Durable decision gate: ask a question, poll until action is proceed. Wait means stop. 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_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_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.

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.