# Agent quickstart — the pSEO Engine over MCP

**Who this is for:** an AI agent (or the human wiring one up) that wants to drive
programmatic SEO — research a query space, generate the page set, audit, publish —
from any MCP client. No card, no subscription: discovery and reads are free, and
metered spends draw from a prepaid key balance.

- **Endpoint (MCP, Streamable HTTP):** `https://pseo.quantumcx.net/api/agent/mcp`
- **Plain-language discovery:** `GET` the same URL (no JSON-RPC needed)
- **OpenAPI spec:** `https://pseo.quantumcx.net/openapi-agents.json`
- **Key creation:** https://pseo.quantumcx.net/dashboard/agent-keys
- **Agent signup (no card):** https://pseo.quantumcx.net/signup?for=agent

## 1. Connect (zero setup, zero key)

Discovery is anonymous by design — `initialize` and `tools/list` answer without a
key, so an integration can be evaluated before any account exists.

Claude Code:

```bash
claude mcp add --transport http pseo-engine https://pseo.quantumcx.net/api/agent/mcp
```

Any other MCP client: POST JSON-RPC to the endpoint over Streamable HTTP. The
server is stateless (no session id to keep alive), and a plain `GET` on the URL
returns machine-readable metadata — auth header shape, billing model, free-read
limits, and the full tool list with prices — for clients that skip the handshake.

## 2. Create a key (one minute, no card)

1. Sign up at the agent door (`/signup?for=agent`) — no card is taken and plans
   are never sold to agent accounts.
2. Open **Dashboard → Agent keys**, mint a key, copy it once (it is shown a
   single time).

Send it on every `tools/call`:

```
X-Agent-API-Key: <your key>
```

`Authorization: Bearer <your key>` works too — same key, either spelling.

## 3. First pipeline (all free until research runs)

The canonical loop, exactly as the server's own instructions field teaches it:

1. `seo_project_list` — every tool below needs a `projectId`; ids cannot be
   guessed. **Free.**
2. Empty list? `seo_project_create` — it costs nothing. **Free.**
3. `seo_project_connect_ai` with an AI provider key — generation, research and
   audits run on YOUR provider account (BYOK), so this call is also **Free**.
   A free-tier Google Gemini key from aistudio.google.com/apikey works, no card.
4. `seo_research_start` with a brief — ASYNCHRONOUS: it returns a `jobId`
   immediately and the keywords do not exist yet. **Metered — but every new
   agent account gets its FIRST research run free**, once, no pack required.
   The response's nextStep says so when it happens.
5. Poll `seo_job_status` until `COMPLETED`. **Free.** Do not re-call the start
   tool — a run already in progress makes it fail.
6. `seo_rows_list` to read the mined, qualified rows. **Free.**

Tools that do work (research, generate, audit, publish) are asynchronous; tools
that read state are free and rate-limited only by fair use
(30 reads/min, 1000/dayper key).

## 4. What things cost

Prepaid balance per key, debited **per successful call** in cents. Failed calls
are never charged — a bad argument returns `wouldHaveCostCents` with the price
that would have applied and a hint, and nothing is debited.

<!-- rendered by scripts/render-agent-quickstart.mjs — do not hand-edit the rows -->
| Tool | Cost |
| --- | --- |
| `seo_project_list` | Free |
| `seo_project_create` | Free |
| `seo_project_connect_ai` | Free |
| `seo_project_get` | Free |
| `seo_rows_list` | $0.03 |
| `seo_job_status` | Free |
| `seo_research_start` | $7.50 |
| `seo_content_generate` | $0.75 |
| `seo_audit_start` | $0.30 |
| `seo_publish` | $0.15 |

Metered spends assume the project has an AI key connected (`seo_project_connect_ai`) —
the AI itself bills your own provider account, so connect it before the first
research run.

The first research run on a new agent account is free (once per account, not
per key). After that, balance is bought once, up front, as agent packs — no
subscription, no auto renewal, and checkout refuses to sell packs to plan
accounts or plans to agent accounts. A key's own daily spend cap (24h rolling
window) bounds blast radius; raise or lower
it on the Agent keys page.

## 5. The error contract (teach this to your model)

Every refusal is machine-branchable JSON — `error`, `code`, `retryable`, and a
`howToFix` sentence written for the calling model, not a human:

| Code | Retryable | Meaning for the agent |
| --- | --- | --- |
| `missing_key` | no | Send `X-Agent-API-Key`. Listing tools is free; running them is not. |
| `insufficient_funds` | no | The error states the call's cost, the key's balance, and that nothing was charged — then points the human at the buy page. Retrying without a balance fails again. |
| `card_required` | no | The account's one free research run is spent and no plan is active. **Stop and report** — only a human on the account can start a plan. Other tools are unaffected. |
| `rate_limited` | yes | Back off and slow the polling cadence; the window clears itself. |
| `daily_cap` | no | The key hit its rolling 24h spend cap; wait or have a human raise the cap. |
| (argument errors) | — | `charged: 0` + `hint`: fix the described arguments and call again. |

One behavioral rule matters more than the rest: `card_required` on
`seo_research_start` means the *human* trial's free run is gone. The correct
agent behavior is to stop, surface the Billing page link to the human, and
continue with any other work — never to retry into the wall.

## 6. Publishing is a human gate

`seo_publish` is a real tool, but nothing goes live because software decided it
should: pages pass a review gate (with automatic near-duplicate flagging) and a
human approves. Build the pipeline, let it run, and expect the publish step to
end at an approval queue, not a live URL.