AEOForged
Get in touch

MCP Setup Guide

Connect your AI agents to AEOForged via the Model Context Protocol.

1. Get an API Key

Sign in to AEOForged, go to Settings → API Keys, and create a new key. Copy it immediately — it's only shown once.

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. Available Tools

Once connected, your agent will have access to these tools:

aeo_accountFree

Whoami: tier, credit balance, tool costs

aeo_scoreFree

Score content for AEO readiness (0-100) with extractability bonus

aeo_schemaFree

Generate Article + FAQPage + HowTo JSON-LD with speakable and entity linking

aeo_extractFree

Reformat content for answer engine extraction (featured snippet, knowledge panel, PAA)

aeo_research10/15 credits

Live web research + source extraction. Standard (10cr) or deep mode (15cr)

aeo_outline3 credits

Generate structured content outline with snippet targets and word count targets

aeo_write8 credits

Write sections with verified citations, tone/voice control, and coherence pass

aeo_polish2 credits

Style pass with changelog, heading preservation, brand voice, and idempotency guard

aeo_verify2 credits

Fact verification with confidence tiers and verification report

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 for existing content

aeo_cluster5 credits

Keyword clustering + content hierarchy with content calendar

aeo_full_pipeline12/20 credits

End-to-end pipeline. Draft mode (12cr) or publish mode (20cr)

aeo_trackFree

Register a published URL for citation monitoring across Brave, Google AI, and Perplexity. Tracks position, detects score decay, and triggers alerts. Included with Pro.

aeo_workflow_audit_improve5-13 credits

Composite: audit URL + conditional refresh plan if below threshold

aeo_workflow_strategy~44 credits

Composite: cluster keywords → research + outline top N pillars

aeo_workflow_health5/URL credits

Composite: batch-audit up to 10 URLs, priority dashboard

aeo_workflow_quality_gateFree

Composite: score against target threshold, pass/fail with fixes

aeo_client_profile5 credits

Build client intelligence profile: brand voice, company facts, credentials, team, work evidence

aeo_optimise8 credits

Page-level section analysis, intent classification, and AEO-optimised rewrites

aeo_complete_auditFree

Comprehensive site-wide audit: discovers pages, scores each across 8 dimensions, benchmarks competitors, maps findings to services

aeo_crawlabilityFree

Check AI bot access: robots.txt for 11 AI bots, meta directives, llms.txt, sitemap, JS rendering — pass/fail per bot + fix recommendations

aeo_llms_txt3 credits

Generate spec-compliant llms.txt + llms-full.txt for a website with semantic page grouping and deployment instructions

aeo_share_of_voice10 credits

Measure AI answer visibility: SOV %, coverage, avg position, gap/domination keywords across 3 engines for up to 20 keywords vs 5 competitors

4. Example Workflows

Create from scratch

1

Research the topic

Call aeo_research with your keyword. Use depth: "deep" for comprehensive coverage (15cr).

2

Generate outline and write

aeo_outline → aeo_write with tone and reading level control.

3

Polish, verify, and extract

aeo_polish → aeo_verify → aeo_extract (free) for answer engine formats.

For web UI users without an agent: aeo_full_pipeline provides a full chain (12-20cr), but agents get better results using the research-write-score loop above.

Audit and improve existing content

1

Audit a URL

aeo_audit fetches the page, scores it, and returns a prioritized improvement plan (5cr).

2

Refresh stale content

aeo_refresh runs fresh research and produces section-by-section update instructions (8cr).

Content strategy

1

Cluster keywords

aeo_cluster groups keywords into pillar/supporting hierarchy with a content calendar (5cr).

2

Compare articles

aeo_compare scores two URLs or articles head-to-head with per-dimension analysis (3cr).

5. What Agents Should Know

Key patterns for agents using AEOForged tools effectively:

Credit awareness

Call aeo_account before expensive workflows to check your balance. Score, schema, and extract are free. The account response includes per-tool costs so you can budget.

Error handling

On 402, stop and inform the user about credits. On 429, wait retry_after_seconds. On timeout, retry once with smaller input. Failed tools never consume credits.

Tool chaining order

Always research before outlining, verify after writing, and score after every edit (it's free). See the Workflow Recipes for complete patterns, or download an Agent Skill to give your agent this knowledge automatically.

6. Real-Time Project Sync

Pass a project_id to any tool and the output is automatically saved to your project. Open the project page in your browser and watch results appear in real-time as your agent works.

How it works

Every tool (aeo_research, aeo_outline, aeo_write, aeo_score, aeo_schema) accepts an optional project_id (UUID). When provided, the tool saves its output to that project in the database and your project page updates instantly via WebSocket.

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 the research, outline, and content appear on screen as the agent works
  5. Step in any time — edit content on the page or redirect the agent in your 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."

7. 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_...(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.

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-remotebridge — see the "Other MCP Clients (stdio bridge)" section above.

Network / firewall errors

  • AEOForged MCP uses Streamable HTTP. Outbound HTTPS must be allowed to aeoforged.com.
  • Long-running tools may run up to 5 minutes — keep client timeouts ≥ 300s.