# The MCP server

> Every ftw.trade tool over the Model Context Protocol. Authentication, how calls are checked and refused, conventions every tool shares, and the full tool catalog.

## The server

One server at two addresses, over Streamable HTTP (JSON-RPC 2.0):

- `https://ftw.trade/api/mcp`: every tool.
- `https://ftw.trade/api/mcp/essentials`: the most-used tools, with `search_tools`, `get_tool` and `run_tool` to reach the rest.

Every tool is a call the site's own pages make, through the same functions, so what an agent builds opens the same on the site.

## Authentication

- **OAuth**: point the client at the address. It discovers the authorization server, registers itself, and sends you to ftw.trade to sign in and approve (PKCE). Access tokens last 30 days; refresh tokens rotate.
- **API key**: make one on the AI & API page (`fwb_at_…`, shown once) and send `Authorization: Bearer fwb_at_…`. Keys can be narrowed to projects, tools, paper only, an expiry and a daily spend. See [API keys and session keys](https://docs.ftw.trade/agents/keys).

## Calls and refusals

Every tool has a title, a description, annotations (read-only, destructive, open-world) and a closed JSON schema. Arguments are checked before anything runs: an unknown one is refused, naming the ones it takes.

A refusal says exactly what to fix, `<status>: <message>`, with the field:

| Status | Means |
|---|---|
| 400 | The arguments are wrong. The field is named |
| 403 | Live trading isn't allowed on this connection. The message says where to allow it |
| 404 | No such thing (an id from the wrong list, a deleted project) |
| 409 | A conflict: a stale version, a name taken, a limit reached. Read the current state and redo the change |
| 422 | Understood but not allowed. The message names the fix |
| 500 | A fault on ftw.trade's side, with a reference to quote |

## Conventions

- **Ids** come from the `list_*` tools: projects, pools (`chain:address`), series, deployments (`sd_…`), automations (`au_…`).
- **Guides first**: `get_project_guide`, `get_strategy_guide`, `get_automation_guide` and others return the exact shapes their tools take, with working examples.
- **Dry runs**: many tools that change things take `apply` and only describe what would happen until it's `true`.
- **Versions**: a save made from an older copy of a document is refused (409), so an agent never undoes your edit.
- **Mode**: every trade answer carries `mode: paper | live`.
- **Checks before saves**: `check_strategy` compiles without saving, `test_strategy` runs cases, `backtest_*` replay history, previews say what would happen.

## Areas

| Area | Examples |
|---|---|
| Skills and tools | `list_skills`, `get_skill`, `search_tools`, `run_tool` |
| Projects and dashboards | `create_project`, `save_project`, `update_dashboard`, `check_dashboard` |
| Sources | `add_pool`, `add_perps_market`, `save_flow_source`, `create_source` |
| Strategies | `check_strategy`, `save_strategy`, `backtest_strategy`, `run_optimization`, `run_strategy` |
| Workflows and scripts | `save_workflow`, `control_workflow`, `save_automation`, `run_automation` |
| Trading | `place_resting_order`, `run_perps_move`, `place_prediction_order`, `get_order_book` |
| Wallets and funds | `list_account_wallets`, `transfer_funds`, `get_bridge_quote` |
| Vaults | `list_vaults`, `create_vault`, `place_vault_order` |
| Account | `get_portfolio`, `get_log`, `get_flow` |

The full, generated catalog of every tool is in the [MCP skill](https://ftw.trade/skills/ftw-mcp) and its [tool reference](https://ftw.trade/skills/ftw-mcp/references/tools.md).

## Resources and prompts

Skills are also MCP resources (`ftw://skills/<name>/<file>`), and the server offers prompts: `start`, `build-strategy`, `design-dashboard` and `check-account`.

## Pushed sources over HTTP

Pushed sources receive events at `POST /api/sources/<name>/events` with the source's own key. See [Pushed sources](https://docs.ftw.trade/sources/other-sources#pushed-sources).