# For agents

A vendor wants an account, a key or a subscription. Ask Suffect instead of asking your human for a key: they approve once, on one sheet, and you get a grant.

- [The skill, as a file](/skill.md)
- [The index for agents](/llms.txt)

## When to ask

- A vendor API answers 401, 403 with an insufficient-scope message, or 402.
- A vendor's documentation says "get an API key", "create an account" or "subscribe".
- The task needs a capability no connected vendor provides; `search_catalog` finds one, with its price before the call when the catalog knows it.

## The one call

Over MCP. Without MCP: `suffect request elevenlabs.io --budget 20/mo --json`, with your access token in `SUFFECT_TOKEN`.
```json
request_access {
  "provider": "elevenlabs.io",
  "budget": { "amount": 20, "currency": "USD", "period": "month" }
}
```

When a catalog row's terms carry `automated_signup_restricted` or `signup_on_behalf_restricted`, the vendor's terms restrict what you are about to ask for: tell the human in one sentence before you ask. The sheet shows the clause, their approval acknowledges it, and Suffect proceeds openly as their identified agent.

## What comes back

- **granted**: call `get_grant` with the `request_id` (or run `suffect env <request_id>`) and use the base URL and token it returns: point the vendor's SDK at the base URL and send the token as the bearer credential.
- **pending_consent**: tell the human in one sentence what you asked for and give them the `consent_url`. Wait, then check with `get_grant`.
- **provisioning**: approved; the account is being created. Check again with `get_grant` in a minute.
- **pending_takeover**: the vendor needs a human step: a CAPTCHA, a two-factor challenge, an unexpected page. Give the human the `takeover_url`. Without one, read the job: at step `email_code` the vendor mailed a verification code to the human's own address, which they chose on the approval; ask the human for it, or read it from their mailbox only when they have given you access for that, and call `relay_code` with the `job_id` and the code. Never guess a code; three at most.
- **denied**: stop and tell the human why. One exception: `standing_budget_exhausted` with a `consent_url` means the standing budget this provider would use is spent for the period and the human already has a sheet to raise it; give them that link and ask again once they approve.

## The eight tools

| Tool | What it does |
| --- | --- |
| `request_access` | Asks for access to a provider's resource (an account, an endpoint, a tool) or to a category of pay-per-use tools. Returns granted, pending_consent with a link for the human, provisioning, pending_takeover or denied; with a `request_id`, checks an earlier request instead. |
| `get_grant` | The grant for a request that was granted: a proxied base URL and a short-lived token, or the status if it is not granted yet. |
| `search_catalog` | Providers and resources Suffect can get access to, with their categories, how they are paid for and whether a price is known before the call. |
| `get_quote` | The price of a resource before you use it, when the catalog knows it. |
| `list_access` | The human's active approvals that apply to you: what you may use, with budgets and ceilings. |
| `set_budget` | Asks for a larger budget under one of your approvals. The human gets a new sheet for the same access with the new budget; nothing changes until they approve it. |
| `revoke` | Gives up the access behind one of your requests, now; the grant stops working at the gateway. A whole approval is the human's to revoke, on their dashboard. |
| `relay_code` | Passes on the verification code a provider mailed to the human's own address, for a job waiting at `email_code`. |

## Rules

- Never print the grant token or a vendor key into chat, files, logs or commit messages. Put it in the environment or pass it directly to the client.
- If a call later fails with 401 again, the grant expired or was revoked: call `get_grant` once more. Do not retry in a loop.
- When the task is done and you will not need the access again, call `revoke` with the `request_id`. The grant stops at once; the human can always revoke the whole approval on their dashboard.
- When you hand the human a link, say in one sentence what they will see: one sheet with the vendor's terms, the plan and price, the budget cap, and one approve button that signs a record with their passkey.
- State spend in the request. A call past the budget is refused (a 402 with `mandate_budget`); ask for more with `set_budget` and tell the human why. An approval covers the agent that asked; another agent asks separately.
- Never solve a CAPTCHA and never sign up at a vendor yourself.

## Where Suffect is

- **The MCP server**: `https://mcp.suffect.com`, remote, OAuth 2.1 with client ID metadata documents and PKCE, so any client registers at the 401 without a developer pre-registering it.
- **The skill**: [/skill.md](/skill.md), in the Agent Skills format. Install it where your runtime loads skills; it triggers on 401, 402, 403 and "API key required".
- **The CLI**: `suffect`, for terminals and for clients without elicitation: `suffect request`, `suffect env`, `suffect revoke`, `suffect status`.

> The production service is not open yet (see [where things stand](/#questions)); the addresses above are where it will answer.

## Reading this site

Every page has a Markdown twin at the same path plus `.md` (`/agents.md` for this one), also served when your `Accept` header prefers `text/markdown`. The index is [/llms.txt](/llms.txt); the whole site in one file is [/llms-full.txt](/llms-full.txt); the schemas are under `/schemas/0.2/`; robots.txt allows every agent.

---

Canonical: https://suffect.com/agents. Every page of this site has a Markdown twin at the same path plus `.md`; the index is https://suffect.com/llms.txt.