Agent Flow docs
Agent Flow is an MCP server that gives your coding agent a catalog of priced API endpoints: web search and scraping, people and company enrichment, SEO data, social platforms, market data and media generation.
Your agent's model decides what to call. Agent Flow finds the endpoint, shows its price, runs it with the right credentials, and returns the result with a receipt.
Every call follows the same three steps:
-
discoverfinds endpoints for a job and lists their prices. Free. -
inspectshows one endpoint's input schema and full pricing. Free. -
runstarts it and returns a run id at once;runs_getcollects the result. It charges what the run used.
Get started
Use the hosted gateway, which needs only a URL and an API key, or run Agent Flow on your Mac with your own provider keys.
- Quickstart Create a key, connect Claude Code, and run your first call.
- Connect a client Settings for Claude Code, Codex, Cursor and OpenCode.
- Run locally Your own provider keys in the Keychain, and signed-in websites.
- Pricing List prices, how a run is charged, and why failed calls are free.
Reference
Quickstart
Connect Claude Code to the hosted gateway in four steps.
1. Create an API key
Create an account in the app, which shows your first key, or call the API:
curl -X POST /accounts
The response holds your key. It is shown once; Agent Flow stores only its hash.
{"accountId": "acct_3f9c0a1b2d4e5f60", "apiKey": "af_..."}
2. Add the server
claude mcp add --transport http agent-flow \ /mcp \ --header "Authorization: Bearer af_YOUR_KEY"
Using Codex, Cursor or OpenCode? See Connect a client.
3. Add funds
New accounts start at $0. Ask your agent to top up, for
example "add $10 to Agent Flow". It calls the topup tool and gives you a Stripe Checkout link.
The balance updates once the payment completes.
4. Ask for something
"Search the web for recent MCP gateway launches and summarize them." The agent discovers an endpoint, checks its price, runs it, and reports the charge.
Connect a client
Add the hosted gateway to Claude Code, Codex, Cursor or OpenCode.
The hosted gateway speaks MCP over Streamable HTTP at
/mcp. Send your
key as a bearer token.
claude mcp add --transport http agent-flow \ /mcp \ --header "Authorization: Bearer af_YOUR_KEY"
Add --scope user to use it from every
project.
# ~/.codex/config.toml [mcp_servers.agent-flow] url = "/mcp" bearer_token_env_var = "AGENT_FLOW_API_KEY"
Then set AGENT_FLOW_API_KEY in the
shell that starts Codex.
// ~/.cursor/mcp.json
{
"mcpServers": {
"agent-flow": {
"url": "/mcp",
"headers": { "Authorization": "Bearer af_YOUR_KEY" }
}
}
}
// opencode.json
{
"mcp": {
"agent-flow": {
"type": "remote",
"url": "/mcp",
"headers": { "Authorization": "Bearer af_YOUR_KEY" }
}
}
}
Add the agent skill
SKILL.md teaches
your agent when to reach for Agent Flow and how to use
it well: discover before building, inspect before
running, keep costs down, read endpoint health, and
send feedback or dispute bad results. Agents that load
skills pick it up from their skills folder, for
example in Claude Code:
mkdir -p ~/.claude/skills/agent-flow curl -o ~/.claude/skills/agent-flow/SKILL.md \ /SKILL.md
For other agents, add the file to their instructions
(for example AGENTS.md). Fetch it again
now and then; it tracks the tools.
Run locally
Run Agent Flow on your Mac with your own provider keys.
The local server runs on your Mac over stdio. It uses your own provider keys, so the provider bills your key and Agent Flow charges nothing. It also lets the agent use websites you are signed in to.
You need macOS, Deno 2.x, and agent-browser for browser accounts.
Store a provider key
Every key belongs to an environment such as work or sandbox. A call never uses
another environment's key. You are prompted for the key,
and it is stored in the macOS Keychain, never in files
or environment variables.
deno task af key set work exa
Connect a private website
Sign in once in a visible browser window, MFA included. The agent reuses the session afterwards, across restarts. It can navigate, read and click, but cannot read cookies, storage or saved passwords.
deno task af browser connect work/dashboard https://example.com/login
To let the agent sign in again on its own, save a password:
deno task af browser password work/dashboard https://example.com/login you@example.com
Add the server
claude mcp add --scope user agent-flow -- \ deno task -q --config /path/to/agent-flow/deno.json mcp
Commands
| Command | What it does |
|---|---|
af key set <env>
<provider>
|
Store a provider key |
af key rm <env>
<provider>
|
Remove it from the Keychain. Revoke it at the provider too. |
af key list |
List stored key names, without secrets |
af browser connect
<env/name> <url>
|
Sign in to a website once |
af browser password
<env/name> <url>
<user>
|
Save a password for the agent's login
|
af browser list |
List connected accounts |
af browser rm
<env/name>
|
Delete the session, profile and password |
Run each as deno task af ... from the
repository.
Agent tools
These are the MCP tools your agent sees. Results are JSON text.
discover
Find endpoints for a job, ranked by how well they match, each with its price in one line and its health. Free.
| Argument | Type | Description |
|---|---|---|
query |
string, required | What the job needs, in plain words |
limit |
number | How many endpoints to return. Default 10. |
includeUnavailable |
boolean |
Also list endpoints in outage, which
are hidden by default. A
hint says how many were
hidden.
|
{
"endpoints": [
{
"id": "exa#search",
"name": "Exa Search",
"summary": "Search the web with Exa's neural + keyword search.",
"price": "$0.007 per call, extras from $0.001 per result",
"health": {"status": "healthy", "typicalSeconds": 1.2}
}
]
}
Locally, each endpoint also lists readyIn,
the environments that hold a key for its provider, and
the result lists your browserAccounts.
inspect
Show one endpoint's description, price with its billing
notes, a compact description of its input, and health
with its typical and tail run time
(tailSeconds, the 90th percentile). Check
the tail before passing a long wait. Free.
| Argument | Type | Description |
|---|---|---|
endpoint |
string, required |
An id from discover, such
as exa#search
|
full |
boolean | Also return the complete JSON Schema of each input part. Default false |
input.required lists the fields every call
must carry, and input.fields gives each
top-level field one line: its type, whether it is
required, its default and its description, required
fields first.
When the input must also match one of several shapes,
such as a search by name or by email,
input.variants lists each shape's required
fields and the fields only it accepts.
input.example is a minimal input that passes
validation; it is left out when no generic value fits a
field's pattern.
A field line shows at most 12 enum values; pass
full for the rest and for nested fields.
In the full schema, alternatives that repeat one object
schema and differ only in which fields are required are
written once, with an anyOf of the required
sets.
{
"id": "firecrawl#scrape",
"name": "Firecrawl Scrape",
"summary": "Scrape one URL into clean markdown, HTML, or schema-shaped JSON.",
"price": { ... },
"input": {
"required": ["body.url"],
"fields": {
"body.url": "string (uri), required. The URL to scrape.",
"body.onlyMainContent": "boolean. Return only the main content, ...",
...
},
"example": {"body": {"url": "https://example.com/pricing"}}
},
"hint": "Pass full: true for the complete JSON Schema of the input."
}
Endpoint health
Health is measured from the gateway's own recent runs of each endpoint, across all accounts. A provider fault, a timeout or a refusal of the gateway's provider account counts as a failure; a run rejected for its input or stopped on request does not count.
| Status | Meaning |
|---|---|
healthy |
A run succeeded in the last 15 minutes. |
stable |
No recent run, but a clean record over the past week. |
degraded |
Over a fifth of recent runs failed, or the last two did. Still works in most cases. |
outage |
The last three runs failed, the latest
within the hour. Hidden from
discover unless
includeUnavailable.
|
unknown |
No runs in the past week. Not a warning. |
Use health to break ties between endpoints that both fit the job, never to skip one that fits. A missing run time means few runs, not a slow endpoint.
run
Start a call to an endpoint. It returns a
runId at once and the call runs in the
background, so a video render or a site crawl that
takes minutes never holds the agent's connection open.
Pass wait to block until it finishes, or
collect the result with runs_get. The
price is reserved from your balance before the run
starts and the rest is returned when it settles.
| Argument | Type | Description |
|---|---|---|
endpoint |
string, required | The endpoint id |
input |
object, required |
{body?, queryParams?,
pathParams?}, following the
schema from inspect
|
env |
string, local only |
Which environment's key to use, such as
work
|
wait |
number | Seconds to wait for the run to finish, 0 to 50. Default 0 |
{
"runId": "run_mh2k1x0a4f9c2e7b1d3a",
"endpoint": "firecrawl#crawl",
"status": "RUNNING",
"stoppable": true,
"hint": "Still RUNNING. Call runs_get with runId ... for the result, or runs_stop to cancel it."
}
runs_get
Get a run by runId. Takes the same optional
wait. A finished run carries its receipt
and the provider's output. Free.
An output over 20,000 characters comes back as a
preview: the first items of each list and the start of
each long string, with markers saying what was cut. The
whole output is saved to the account's
files under
runs/<runId>/output.json, and
outputFile gives its url
(valid 7 days), path and
sizeBytes. Media returned as base64, such as
generated audio or images, is saved the same way and
replaced by savedAs with its link.
| Argument | Type | Description |
|---|---|---|
runId |
string, required | The id run returned |
wait |
number | Seconds to wait for the run to finish, 0 to 50. Default 0 |
debug |
boolean |
Also return debug: the
engine's usage evidence, timing and
resource effects. Default false
|
{
"runId": "run_mh2k1x0a4f9c2e7b1d3a",
"endpoint": "exa#search",
"status": "COMPLETED",
"receipt": {"charged": "$0.007000", "balance": "$9.993000"},
"httpStatus": 200,
"isProviderError": false,
"output": { ... }
}
| Status | Meaning |
|---|---|
RUNNING |
In progress |
STOPPING |
A stop was requested |
COMPLETED |
Finished; output holds the
result
|
FAILED |
Did not succeed; error
says why and nothing is charged. When
the provider rejected your input,
isProviderError is true and
output holds its reason
|
STOPPED |
Cancelled at the provider |
TIMED_OUT |
Passed the endpoint's time limit and was cancelled |
runs_list
List recent runs, newest first, without their output.
Takes an optional limit (default 20) and
the cursor a previous page returned. Free.
runs_stop
Cancel a run whose stoppable is true. The
stop is asynchronous: check runs_get until
the run is STOPPED. Work the provider
reports as already done is charged. Runs are kept for
30 days.
resources_* hosted
Some endpoints provision something you keep, such as a
phone number. The run's price pays for the first
period; after that the resource renews from your
balance each period until you release it. Its
inspect notes give the renewal price.
{
"resourceId": "res_...",
"resource": "saperly/phone-number",
"name": "Phone Number",
"externalId": "num_...",
"identifier": "+14155559999",
"state": "ACTIVE",
"paidThrough": "2026-11-28T12:00:00.000Z",
"renews": "$1.00 per 1 month"
}
A renewal is charged from three days before the
paidThrough date, after checking with the
provider that the resource still exists. If the
balance cannot pay it, you keep the resource until
paidThrough; then it is released and
nothing more is owed. Usage-priced lines are read from
the provider's meter and charged when each period ends.
resources_list
List your resources, newest first. Filter by
provider, resource (a type
such as saperly/phone-number) or
state (ACTIVE,
RELEASING, RELEASED). Takes
limit (default 20) and a
cursor. Free.
resources_get
One resource by resourceId, with the
provider's live views of it (for a phone
number, its AI persona). Pass views: false
to skip them. Free.
resources_release
Release a resource at the provider so it stops
renewing. Irreversible and asynchronous: check
resources_get until it is
RELEASED. The current period is not
refunded.
resources_events
A resource's history, oldest first:
PROVISIONED, CHARGED,
RENEWAL_FAILED,
RELEASE_REQUESTED, RELEASED,
REFRESHED and ERROR, each with
a message saying why. Takes limit (default
50) and a cursor. Free.
files_* hosted
A free file store for each account, for endpoints that
take a file as a URL (an image to animate, audio to
transcribe) and for results worth keeping. Each account
has 1 GB. Bytes go straight between your agent and the
gateway with curl; the tools only hand out
signed links. Files you store are never deleted on
their own: files_rm frees their space.
Outputs saved under runs/ expire a day
after their newest link does; runs_get
on the run gives a fresh link and keeps the file a week
longer, and files_mv out of
runs/ keeps it for good.
# 1. Reserve the upload (sizeBytes from wc -c)
files_put {"path": "in/photo.png", "sizeBytes": 48213}
-> {"uploadUrl": "/files/...", ...}
# 2. Send exactly those bytes within the hour
curl -T ./photo.png '<uploadUrl>'
# 3. A link any provider can fetch: 1h, 1d, 7d or 30d
files_url {"path": "in/photo.png", "ttl": "1d"}
-> {"url": "/files/.../photo.png", ...}
files_list lists files under an optional
prefix with the space used,
files_mv renames one (its links keep
working), and files_rm deletes one. A link
stops working when it expires or its file is removed or
replaced. Putting a path that exists replaces it once
the upload finishes.
wallet
Show the balance and recent charges, refunds and
top-ups. Free. Takes an optional limit,
default 10.
feedback hosted
Send feedback to the Agent Flow team: an endpoint that
failed or misbehaved on valid input, a job
discover had nothing for, or a confusing
error. Pass text (1 to 4000 characters)
and, when it is about a run, its runId.
Returns a feedbackId. Free.
dispute hosted
Flag finished runs whose results were broken or useless for what you asked, although the input was right: empty output for a valid query, stale or wrong data, the wrong entity. The Agent Flow team reviews each dispute and may refund its runs; a refund shows in the wallet as its own entry, and each run is refunded at most once. Not for a wrong input or endpoint choice. Free.
| Argument | Type | Description |
|---|---|---|
runIds |
string[], required | The runs disputed, 1 to 100. Each run can be in one dispute. |
reason |
string, required | What was wrong: what was expected and what came back |
userQuery |
string, required | The request the runs were for |
discoverQueries |
string[] | Queries passed to discover |
contextRunIds |
string[] | Other runs for the same request, such as a retry or a run that worked |
topup hosted
Create a Stripe Checkout link that adds usd
(5 to 500) to the balance. The agent gives you the link;
it never opens or pays it.
browser local
Drive a connected browser account such as work/dashboard. command is an
agent-browser argument list, for example ["open",
"https://..."], ["snapshot",
"-i"], ["click", "@e3"] or ["login"], which replays the saved password.
Pricing
What a call costs, and how a run is charged.
Each endpoint costs what
Monid, an API price
registry, lists for the same call. Apify actors cost
the actor's own event prices, the same ones each run is
charged, such as a start fee plus a price per result.
Providers Monid does not sell cost their own entry-level
list price, shown in the same format. There is no subscription and no fee on
top. Endpoints with no price are not sold on the hosted
gateway, and endpoints that cost nothing, such as
checking on a running job, are listed as
PER_CALL $0.
Price shapes
discover gives each price in words, such
as "$0.000253 per result, billed in blocks of 10
results". inspect and
/catalog give it in words too, as
priceText, and the full price, which has
one of these shapes:
| Type | Meaning | Example |
|---|---|---|
PER_CALL |
A fixed amount for each call |
exa#contents: $0.001 per
call
|
PER_RESULT |
An amount for each result returned,
plus a flatFee once per
call when the provider charges one
|
firecrawl#search: $0.0002
per result
|
PER_UNIT |
An amount for every
per units of the
unit, such as credits or
tokens. Tokens and characters are priced
per million.
|
firecrawl#agent: $0.001 per
credit
|
TIERED |
A default price plus tiers that apply depending on
the input or output. amount
is the starting price
|
exa#search: from $0.007 per
call
|
PER_UNIT_MATRIX |
A unit price that depends on an input,
listed as variants
|
Video generation priced per second by resolution |
inspect also returns notes
when an endpoint has billing details, such as "Charged
only when an address is found."
How a run is charged
- Before dispatch, the run holds its estimated cost for this input, or $1 when the price depends on results that cannot be estimated up front. If the balance is lower, the run is refused and nothing is sent to the provider.
- The provider is called.
- The run is settled at what it actually used. The rest of the hold is returned; a cost above the estimate is taken from the balance, which can go below zero and then refuses paid runs until a top-up covers it.
If the provider returns an error, the run settles at $0. Every settled run leaves a receipt in the ledger.
A run that completed but returned broken or useless
results can be disputed with
dispute.
An upheld dispute refunds the run's charge to the
balance once, as a refund entry in the ledger.
A run that provisions a resource, such as a phone number, pays for its first period. The resource then renews from the balance until you release it; see Resources.
Balance and top-ups
The hosted gateway is prepaid. Your balance is in US dollars, tracked to the millionth of a dollar.
Top-ups go through Stripe Checkout, from $5 to $500. You can pay in your local currency; the USD amount you chose is what gets credited. Each payment is credited exactly once. If a payment is refunded or disputed, the refunded or disputed amount is taken back out of the balance, which can go below zero; paid runs are then refused until a top-up covers it.
Top up
Ask your agent for a top-up, or call the API with your key:
curl -X POST /topup \
-H "Authorization: Bearer af_YOUR_KEY" \
-d '{"usd": 10}'
{"url": "https://checkout.stripe.com/c/pay/..."}
Keys, budgets and usage
The app manages your account. Sign in with any of your API keys; the browser stays signed in for 30 days.
API keys
Give each agent or machine its own labelled key. A key is shown once when you create it. Revoking a key stops it at once; your other keys keep working.
Budgets
A daily budget caps what your agents spend per day, counting both charged calls and calls still running. It resets at 00:00 UTC. A per-call budget refuses any single call whose estimated cost is above it. A call that would pass a budget is refused before it reaches the provider, and nothing is charged. Budgets are checked against the estimate, so a run that ends up costing more than its estimate can take spend past a budget.
Usage
Every call is listed with the key that made it, the provider's HTTP status, and what it cost.
Errors
Tool errors come back as MCP results with isError:
true and a message your agent can act on.
| Message | What to do |
|---|---|
missing or invalid API key
|
HTTP 401. Check the Authorization:
Bearer af_... header.
|
Balance $… is below the $… this
call may cost.
|
Nothing was run. Top up, or ask for fewer results. |
unknown endpoint … |
The id is wrong or not sold here. Use
discover.
|
No … credential in environment
"…"
|
Local only. Store the key with deno task af key set <env>
<provider>.
|
This call may cost $…, above the
$… per-call budget.
|
Nothing was run. Raise the budget in the app, or ask for fewer results. The daily budget refuses calls the same way. |
usd must be between 5 and
500
|
HTTP 400 from /topup. Pick
an amount in range.
|
HTTP API
The catalog, accounts and top-ups over plain HTTP.
Base URL: . Routes
that need your API key take it as Authorization: Bearer af_....
GET/categories
No key
The catalog's categories: id,
name, description.
curl /categories
GET/providers
No key
The catalog's providers: id,
name, description. An
endpoint's provider is the part of its id
before #.
curl /providers
GET/catalog
No key
Every priced endpoint: id,
provider, name,
summary, path,
categories, price, priceText (the price in words), and hosted when this gateway sells it.
curl /catalog
POST/accounts
No key
Create an account. Returns accountId and
apiKey; the key is shown once.
curl -X POST /accounts
POST/mcp
API key
MCP over Streamable HTTP. Stateless; each request stands alone. See Connect a client for client settings.
POST/topup
API key
Body {"usd": 10}, from 5 to 500. Returns a
Stripe Checkout url.
curl -X POST /topup \
-H "Authorization: Bearer af_YOUR_KEY" \
-d '{"usd": 10}'