Start here: running Seolyticize as an agent

How an AI agent gets access, finds out what it may do, keeps spending in bounds and works through the playbooks.

Embed
Preview of the card
<a href="https://seolyticize.com/docs/start-here"><img src="https://seolyticize.com/docs/_api/public/orgs/71cb2b7a-a719-4003-b3ea-6321dc1db8ab/spaces/3bf2dbf7-3faa-473c-ba3b-30588f5f8de4/pages/d5c71078-642a-48f1-9027-b5bec1f88de4/social-card.svg?v=3e7ae33eec8b" alt="Start here: running Seolyticize as an agent" width="600" height="315"></a>

These playbooks are written for an AI agent doing an agency's SEO work through Seolyticize: onboarding clients, tracking and auditing them, reporting to them, and running the agency's own setup. Each step names the tool that does it. A tool is the same over REST (POST /api/v1/tools/{name}), over MCP (/api/mcp), in the SDK and in the CLI, so the playbooks work whichever way the agent connects.

1. Get access, once, from a person

An agent cannot sign itself up. A person approves it once, in one of two ways:

Way

When

What the person does

Sign in (OAuth)

the agent runs in Claude, ChatGPT, Cursor or another MCP client

adds https://seolyticize.com/api/mcp as a connector, signs in, and chooses the agency, the role and the clients

API key

anything else: scripts, servers, other agent frameworks

creates a key under Settings → API keys and hands it over

After that the agent can mint narrower keys for its own integrations with create_api_key and retire them with revoke_api_key. A key can never be given more access than the credential that creates it.

Which role to ask for

Creating clients, crawls, reports, report schedules, alert rules and portal links needs client:manage, which only admin holds. Team, provider keys, branding and billing need admin as well. A manager can track, research and spend but cannot onboard a client; an analyst can read and write data and send reports; a client_viewer only reads. Ask the person for the least the job needs, pinned to one client where the job is one client.

2. Find out what this credential may do

Call whoami first. It returns the agency, the role, every permission the role holds and the clients the credential reaches. Then list the tools this credential may call: GET /api/v1/tools over REST, or the MCP tool list. Each tool says whether it only reads (readOnly), whether it can cost money (spends) and its input as JSON Schema. Build against that list rather than a copy of these pages: it is generated from the code that runs the calls.

3. Keep spending in bounds

Some tools buy data from a provider and cost money; they are marked spends. Before calling one:

  • estimate_cost {tool, arguments} quotes it without spending;

  • pass maxCostMicros on the call itself, and it is refused rather than run if it would cost more;

  • get_costs and get_client_costs show what has been spent;

  • a client can carry a monthly cap (monthlyBudgetUsd on create_client / update_client) that every call respects.

Paid calls go to the agency's own provider accounts (see Set up the agency); without a key for the provider a tool needs, it is refused with a message saying which.

4. Work through the playbooks

  1. Set up the agency: provider keys, branding, team, plan.

  2. Onboard a client: from a domain to tracking, an audit, a scheduled report and a portal link.

  3. Run the work: what to check each week and what to do about it.

  4. Local, links and logs: map-pack grids and reviews, the link profile and outreach, crawler logs.

  5. What needs a person: the few acts an agent hands back, and how.

Errors worth handling

You get

It means

403 naming a permission

this credential's role does not include it — ask for a role that does, or a person

a refusal saying a provider key is missing

the agency has not connected that provider yet

a refusal over budget

maxCostMicros or the client's monthly cap would be exceeded; quote with estimate_cost first

429 with Retry-After

slow down and retry after that many seconds

The details are in Errors and limits.

Updated