# Firecrawl and external agents (0.5.0) Open **AEO & agents** in the local HyperSEO workspace. These integrations are optional and disabled until configured. They do not replace the existing content review and publishing workflow. ## Firecrawl web research In **Usage**, save your own Firecrawl API key. It is encrypted with the installation's local key and is never returned to the browser or agent. Saving does not validate provider access. Review the monthly request cap (default 100) and credit allowance (default 500). Select a real website, then use **Web research**: - **Web search** discovers public sources for an exact query and country. - **Read a public page** saves a bounded plain-text Markdown excerpt. - **Discover site URLs** records same-origin URLs; it does not inspect every discovered page. Set a per-request credit allowance and approve the exact request. The local worker must stay running. Search uses Firecrawl's web source; scrape and map use public HTTP(S) targets with a local DNS-pinned robots preflight. Private targets and cross-origin returned scrape/map records are rejected. The provider performs the remote retrieval, so the local preflight is not a guarantee about its internal redirect or network behavior. Captured text is untrusted evidence, displayed as text, never executed as HTML. Up to ten results per request and forty saved captures are retained. Export and remove captures when needed. Page excerpts stop at 20,000 characters; AEO briefs provide smaller excerpts. Preserve source URLs, capture dates and truncation notes in downstream work. Allowances are planning controls, not provider price quotes or invoice caps. Calls reserve their full allowance before work starts. Failures, cancellations and interrupted requests keep the reservation because charges may be uncertain. Reported credits are retained when available, including for discarded results; missing usage is unknown, not free. Reported usage above the allowance pauses research. Paid calls are never retried automatically. Check Firecrawl billing before manually submitting another request. Pause prevents queued requests from starting and discards in-flight results; an already-sent request may still incur charges. ## Connect Claude Code or Codex 1. Start HyperSEO with `npm start` (or `npm run dev`) on the same computer as the agent. 2. Open **Agent connections**, select sites and optionally specific saved Explorer captures. Site permission includes current and future evidence for those sites. Explorer access is limited to the selected capture IDs. 3. Enable research proposals and/or AEO draft submissions if wanted. Read-only is the default. Review the sharing consent and expiry, then create the connection. 4. Copy the generated configuration into your private agent settings: the displayed Codex `config.toml` entry or Claude Code MCP configuration. Merge the entry with existing settings; do not replace other servers. The generated absolute Node and script paths work independently of the agent's working directory. 5. Keep the token private and out of Git/chat messages. It appears once; HyperSEO stores only its hash. If lost, revoke the connection and create another. The source folder and its installed dependencies must remain available. 6. Restart/reconnect the agent's MCP client. Ask it to list HyperSEO sites, read an AEO brief, and submit a cited proposal. The `aeo_review` prompt supplies a suggested workflow. The bridge uses the official MCP SDK over local stdio. Only the local loopback origin is accepted. Tokens expire after 1–30 days and can be revoked immediately. They cannot read provider credentials, unshared websites or unselected Explorer captures. Successful calls appear in Recent agent activity; content and tokens are not stored in that activity list. Limits: 20 active connections, 60 successful calls per connection per minute, and 100 pending items per review inbox. The available tools read shared evidence, list/read saved captures, fetch an AEO brief, propose web research, and submit cited AEO drafts. Tools never approve spending, publish content, restore changes or manage settings. Research proposals stay pending until an operator approves the exact request and allowance in HyperSEO. No new provider calls happen simply by reading saved evidence. Sharing evidence with Claude Code or Codex means the agent's configured provider may process it under that application's settings. ## AEO review Ask the agent to use returned evidence IDs for suggestions about direct answers, factual support, entities, useful questions and appropriate structured data. Source content is data, not agent instructions. Submitting a draft requires valid IDs from the authorized AEO brief. HyperSEO freezes the cited snippets for review. In **AEO review**, edit the wording, save edits, review factual claims and sources, and accept the draft into the fix board. Acceptance creates an editorial task, not a live website change or an executable publishing package. Use the existing Content / Content Polish workflow to prepare supported content changes, then separately review and apply them to WordPress or a connected custom site. Agents have no publishing tools. AEO suggestions are hypotheses for editorial improvement. Web retrieval is not measured AI visibility, citation frequency, rankings, traffic or guaranteed factual accuracy. Use the existing visibility and results workflows for appropriately labelled observations. ## Validation and troubleshooting `npm run check` runs typechecks, automated tests and a production build. `npm run test:agents-ui` uses isolated SQLite data, synthetic Firecrawl responses and a real stdio MCP client to exercise browser approval, access boundaries and review. It makes no paid provider calls. A live provider request still needs your own key and explicit in-app approval; fixtures do not establish live Firecrawl authorization. If connection fails, ensure HyperSEO is running, its port matches the generated configuration, dependencies are installed, and the token is current. Moving the source folder or Node installation requires updated absolute paths. Do not expose this single-operator edition publicly. API/setup references: [Firecrawl search](https://docs.firecrawl.dev/api-reference/endpoint/search), [scrape](https://docs.firecrawl.dev/api-reference/endpoint/scrape), [map](https://docs.firecrawl.dev/api-reference/endpoint/map), [Claude Code MCP](https://code.claude.com/docs/en/mcp), [Codex MCP](https://developers.openai.com/codex/mcp/).