AEOForged
Get in touch

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, add the MCP server config pointing athttps://aeoforged.com/api/mcp/mcp, and reload the agent. Once connected, the agent gains all 27 AEOForged tools plus 7 consolidated verbs that compose multiple tools behind a single intent-driven call.

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

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, or freshness plan. 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_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. Replaces 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) return 202 with a poll_url by default. Poll GET /api/v1/tool-runs/{run_id} until status: "complete".

4. All 34 Tools

The full tool catalog, spanning content creation, analysis, auditing, monitoring, action queue, and competitive intelligence. Free tools (score, schema, extract, crawlability, diagnose, factcheck) cost no credits.

aeo_accountFree

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

aeo_scoreFree

8-dimension AEO scoring (0-100), page-type aware, with grade and actionable suggestions

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 via Brave Search + LLM synthesis. Standard (10cr) or deep mode (15cr). Async by default (202 + poll_url).

aeo_outline3 credits

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

aeo_write8 credits

Section-by-section hosted draft with verified citations and tone control

aeo_polish2 credits

Brand-voice polish pass with changelog and idempotency guard

aeo_verify2 credits

LLM-judged review of non-statistical claims (qualitative/entity). For statistics, prefer aeo_factcheck (deterministic, free).

aeo_factcheckFree

Deterministic grounding check for statistical claims — verifies each stat against the research allow-list. No LLM, reproducible.

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 URL for citation monitoring. NOTE: uses Brave web-search rankings as a proxy — not confirmed AI-engine citations.

aeo_importFree

Import an externally-written article (markdown or URL) into a workspace as a baseline-scored content-mode article

aeo_client_profile5 credits

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

aeo_optimise8 credits

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

aeo_complete_auditFree

Site-wide audit: discovers pages, scores each, benchmarks competitors, action plan. Async by default (202 + poll_url).

aeo_crawlabilityFree

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

aeo_llms_txt3 credits

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

aeo_share_of_voice10 credits

Measure AI answer visibility: SOV %, coverage, avg position vs competitors. Brave-search proxy (likely visibility, not confirmed citations). Async by default.

aeo_moat_check15 credits

Competitive gap analysis: topic/format/schema/depth gaps, moat score, prioritized action plan

aeo_agent_readyFree

Probe-based agent readiness audit: 5 agent user-agents, form operability, commerce schema, protocol signals

aeo_agent_policy3 credits

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

aeo_verify_pageFree

Re-fetch URL, re-score vs snapshot baseline, promote done items to verified (system-only status)

aeo_document_fixFree

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

aeo_action_updateFree

Transition one action item: claim (in_progress), done, blocked+reason, reopen. Rejects verified — use verify_page.

aeo_audit_queueFree

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

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

5. 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, fact-check, and extract

aeo_polish → aeo_factcheck (deterministic, free; aeo_verify for non-statistical claims) → 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).

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

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

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