# FMZ AI Agent Setup

This page is written for AI agents (Claude Code, Codex, Cursor, OpenClaw and similar). Follow the steps in order; the user only has to click "Approve" once in a browser. Once connected you can write strategies, run backtests and create and manage live trading robots on FMZ through MCP tools.

中文版：https://www.fmz.com/agent/setup.zh-CN.md

## 1. Request authorization

```
POST https://www.fmz.com/api/agent/device/code
Content-Type: application/json

{"name": "<your name @ machine, e.g. Claude Code @ MacBook>", "scopes": "read,backtest,write,trade"}
```

Response:

```json
{"device_code": "...", "user_code": "ABCD-EFGH",
 "verification_uri_complete": "https://www.fmz.com/agent/authorize?code=ABCD-EFGH",
 "expires_in": 600, "interval": 5, "scopes": "read,backtest,write,trade"}
```

Show `verification_uri_complete` to the user verbatim and ask them to open it in a browser and approve. The link is valid for 10 minutes.

`name` is also the key's identity: approving a new request with the same name revokes the previous key and issues a fresh one, so re-running setup after losing your configuration does not pile up keys. To use several machines at once, include the machine name.

`scopes` is a comma-separated permission list; the user can still untick parts of it on the approval page:

| scope | What it allows |
|---|---|
| read | Lists, details, logs, messages and the account summary (never any secrets) |
| backtest | Start, poll and stop backtests |
| write | Save strategies and versions, manage groups and alerts, edit a stopped robot's configuration |
| trade | Create, start, stop and command live robots (spends balance and places real orders) |
| danger | Delete strategies, robots and nodes; publish strategies |

Leaving it empty defaults to `read,backtest,write,trade`. `danger` is never included by default: ask for it explicitly, and tell the user why before you do.

## 2. Poll for the key

```
POST https://www.fmz.com/api/agent/device/token
Content-Type: application/json

{"device_code": "..."}
```

Poll every 5 seconds. `status` `pending` means keep waiting; `slow_down` means back off; `denied` or `expired` ends the flow (tell the user); `approved` returns:

```json
{"status": "approved", "access_key": "...", "secret_key": "...",
 "mcp_url": "https://www.fmz.com/api/mcp/<access_key>", "scopes": "read,backtest,write,trade"}
```

It is returned **once**. Store it in your configuration immediately; never write it into the conversation, logs or a code repository.

## 3. Connect over MCP

- URL: `mcp_url`
- Header: `Authorization: Bearer <secret_key>`
- Protocol: MCP Streamable HTTP (2026-07-28, 2025 revisions also accepted). The secret goes in the header only, never in the URL.

Claude Code:

```bash
claude mcp add --transport http fmz "<mcp_url>" --header "Authorization: Bearer <secret_key>"
```

Cursor (`~/.cursor/mcp.json`):

```json
{"mcpServers": {"fmz": {"url": "<mcp_url>", "headers": {"Authorization": "Bearer <secret_key>"}}}}
```

Claude Desktop (`claude_desktop_config.json`, needs npx):

```json
{"mcpServers": {"fmz": {"command": "npx", "args": ["mcp-remote", "<mcp_url>", "--header", "Authorization: Bearer <secret_key>"]}}}
```

Any other client: enter the Streamable HTTP URL and the header above in its MCP configuration.

After connecting, call `tools/list` for the full tool set with descriptions; the `instructions` returned by `server/discover` (or `initialize` on older protocol revisions) describe the recommended workflow.

## 4. Rules

- Confirm with the user before calling any tool whose description starts with `[trade]` or `[danger]`.
- Exchange API keys are never configured through an agent: the user adds them on the website, you pick them by id with `list_platforms`. Tool results never contain secrets.
- The user can inspect, re-scope or lock this key at any time at `https://www.fmz.com/m/account#apikey`.
- When the user asks you to disconnect, or you are done for good, call `revoke_my_key` (`confirm: true`) to revoke the key this connection uses; it never touches any other key.

## Install the skills (recommended)

```bash
npx skills add fmzquant/skills --global --yes -a claude-code
```

One command installs every skill: platform operation (`fmz-platform`), the full API documentation (`fmz-api-reference`), strategy writing per language (`fmz-strategy-javascript` / `-python` / `-cpp` / `-rust` / `-pine` / `-mylanguage`), backtesting (`fmz-backtest`) and indicators (`fmz-indicators`). You can also just read them on GitHub: `https://github.com/fmzquant/skills`.

Set `-a` to your own agent (claude-code, codex, cursor, gemini-cli, ...; `npx skills add --help` lists them). Without it the CLI tries every agent it detects on the machine and the whole install fails if one of them does not support global skills.

## Manual configuration (clients that cannot run commands)

The user creates a key at `https://www.fmz.com/m/account#apikey`, then pastes the snippets from section 3 into the client. In Cherry Studio choose Streamable HTTP, URL = `mcp_url`, Headers = `Authorization=Bearer <secret_key>`.