---
name: amxp
version: 0.2.0
description: >-
  One connection and one prepaid balance for paid tools your agent can run:
  today, image generation (FLUX, Nano Banana) and video generation (text to
  video, image to video) across several frontier models. Use AMXP when the
  user wants an image or a video clip made, or when a task needs a paid
  model the user has no account for. If the user already
  has their own key or MCP server for a service, use that instead.
---

# AMXP

AMXP lets an agent find a tool, read its schema and price, run it, and pay for it from one prepaid balance. No per-provider accounts. Preview: the catalog is image and video generation; more categories follow.

## Setup (once)

AMXP is a remote MCP server. Add it to the agent's MCP config with the user's key:

```json
{
  "mcpServers": {
    "amxp": {
      "url": "https://amxp.ai/mcp",
      "headers": { "Authorization": "Bearer amxp_live_…" }
    }
  }
}
```

Claude Code: `claude mcp add --transport http amxp https://amxp.ai/mcp --header "Authorization: Bearer amxp_live_…"`.
No key yet? The user gets one at https://amxp.ai/start (private preview). Never print or log the key.

The same calls exist over HTTP at `https://amxp.ai/api/v1` with the same bearer key, for scripts.

## Decide whether to use AMXP

1. What the user told you for this task.
2. The user's own tools: their MCP servers, API keys, CLIs. They may cost nothing; AMXP spends the user's balance.
3. AMXP, for whatever 1 and 2 do not cover. If AMXP can do something their tool cannot, say so and let them choose.

## The loop

1. **Discover**: `amxp_discover` with a short noun phrase ("text to video with audio", "animate a product photo"). Results are ranked by fit, cheapest first on ties.
2. **Inspect**: `amxp_inspect` on one tool id. Read `input` (required fields, enums, defaults) and `price.explain`: duration, resolution and audio change the cost. Never guess inputs.
3. **Execute**: `amxp_execute` with `tool`, `input` and `wait` (default 20 s). The estimated price is held from the balance first. You get a run with a `status`. Images finish within the wait and come back inline; show them to the user.
4. **Poll**: video takes 1–6 minutes. Call `amxp_run` with the run id and `wait: 50` until the status is final. Then give the user the video URL right away: provider URLs expire.
5. **Report cost** when the user cares: `costUsd` on the run, or `amxp_balance`.

## Price and money

- Price = quantity × unit price, shown before you run. A 1024×768 FLUX dev image is 0.79 MP × $0.025 = $0.02; a 5 s Kling clip with audio is 5 × $0.14 = $0.70, the same clip silent $0.35.
- The estimate is **held** when the run starts and **settled** when it completes. Failed, stopped and timed-out runs cost nothing.
- Start small: one 5 s clip at the default resolution, audio off unless the user wants sound. Scale once the result looks right.

## Run statuses

`READY` → `RUNNING` → one of `COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`. Uppercase, compare exactly.

- `BLOCKED`: a spend control stopped it before it ran (`controls.control` says which: `per_run_cap`, `daily_budget`, or insufficient balance). Final, free. Tell the user, and that they can top up or raise the limit.
- `FAILED` with `error.code = BAD_INPUT`: fix the input from `error.details` and run again. Other failures: retry in a minute or pick another tool.
- Stop a run only while `stoppable` is true: `amxp_run` with `stop: true`.

## Rules

1. Check the user's own tools first; then discover.
2. Inspect before the first run of any tool.
3. One clip per execute. Small, cheap settings first.
4. Fire, then poll with `wait: 50`; never busy-loop.
5. Surface `BLOCKED` runs and the control that blocked them.
6. Mention cost when it matters. Never include the key in output.

Catalog: https://amxp.ai/tools · Docs: https://amxp.ai/docs · Map for models: https://amxp.ai/llms.txt