> For the complete documentation index, see [llms.txt](https://www.aevo.xyz/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.aevo.xyz/docs/aevo-products/aevo-mcp.md).

# MCP

## Public market data and self-hosted trading

The hosted mainnet endpoint at `https://mcp.aevo.xyz/mcp` provides public market data without signing in. It exposes 28 public tools for prices, funding, options analytics and service health. Five additional account-read tools require an authenticated connection in a compatible client. The hosted service cannot place, sign, modify or cancel orders, change leverage, or transfer funds.

The Aevo Market Data plugin submission for ChatGPT covers public-data workflows only. It does not include account sign-in. Never paste API secrets, connection keys or wallet keys into chat.

The Aevo MCP Server enables AI agents to connect directly to the Aevo exchange through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It allows any MCP-compatible client, such as Claude Code, Claude Desktop, Cursor, Windsurf, or OpenClaw, to retrieve market data, manage accounts, and execute trades on Aevo using natural language.

The server is open-source and available on GitHub:

* [**aevo-mcp**](https://github.com/ribbon-finance/aevo-mcp) **-** The MCP server itself
* [**aevo-trading-skills**](https://github.com/ribbon-finance/aevo-trading-skills) - AI skill definitions for trading workflows

***

## Self-hosted trading capabilities

The Aevo MCP Server exposes 45+ tools across five categories:

* **Market Analysis**: Real-time prices, funding rates, volatility snapshots, and market regime classification.
* **Portfolio Management**: Positions, risk metrics, Greeks, and margin monitoring.
* **Order Execution**: Limit orders, bracket orders (entry + stop-loss + take-profit), and batch operations.
* **Options Strategies**: Straddles, strangles, spreads, iron condors, and butterflies with live pricing.
* **Risk Management**: Pre-trade validation, portfolio risk scoring, and liquidation distance monitoring.

In addition to tools, the server provides built-in **Prompts** (such as `trade_plan`, `risk_checklist`, `cancel_plan`, and `onboarding_plan`) and **Resources** (such as `aevo://status`, `aevo://markets/summary`, and `aevo://account/overview`) for structured agent workflows.

***

## Credentials for self-hosted trading

1. Navigate to [app.aevo.xyz/settings](https://app.aevo.xyz/settings/api-keys).
2. Create an API key. This gives you an `api_key` and `api_secret`.
3. For trading, you also need your `wallet_address` and `signing_key_private_key`.

### Credential Tiers

| Tier      | Credentials Required                           | Access Level                           |
| --------- | ---------------------------------------------- | -------------------------------------- |
| Read-only | `api_key` + `api_secret`                       | Account data, positions, trade history |
| Trading   | + `wallet_address` + `signing_key_private_key` | Orders, cancellations, strategies      |

> If you do not yet have API keys, you can set `AEVO_WALLET_ADDRESS` and `AEVO_WALLET_PRIVATE_KEY` as environment variables and use the `register_account` tool to generate them. It is recommended to create an account first and use the Aevo wallet to generate keys.

***

## Connection Methods

### Hosted MCP Endpoint (No Local Server)

Aevo provides a hosted MCP endpoint that requires no local installation. Point any MCP-compatible client to:

* **Mainnet**: `https://mcp.aevo.xyz/mcp`
* **Testnet**: `https://mcp-testnet.aevo.xyz/mcp`

For public data, choose **No authentication** in clients that offer an authentication setting. Do not add credential headers. The mainnet endpoint has no `aevo_authenticate` tool and does not accept separate `AEVO-KEY` and `AEVO-SECRET` headers as account authentication.

For supported clients that use authenticated account reads, a dedicated connection key must be supplied in the client's secure Bearer credential field. Account tools are unavailable to anonymous sessions. This account connection is separate from the public-data ChatGPT submission.

**Example — Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "aevo": {
      "url": "https://mcp.aevo.xyz/mcp"
    }
  }
}
```

### Self-Hosted with Docker (Recommended)

Clone the repository and run the server locally via Docker:

```bash
git clone https://github.com/ribbon-finance/aevo-mcp.git
cd aevo-mcp
cp .env.example .env
```

Edit `.env` with your Aevo credentials:

```
AEVO_API_KEY=your_key
AEVO_API_SECRET=your_secret
AEVO_SIGNING_KEY_PRIVATE_KEY=your_signing_key
```

Start the server:

```bash
docker compose up --build -d
```

Then connect Claude Code:

```bash
claude mcp add --transport http aevo-trading http://localhost:8080/mcp
```

**Example — Claude Desktop config (Docker):**

```json
{
  "mcpServers": {
    "aevo-trading": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

### Local Install (No Docker)

```bash
pip install -e .
cp .env.example .env   # edit with your credentials
aevo-mcp --transport stdio
```

Connect Claude Code via stdio:

```bash
claude mcp add --transport stdio aevo-trading -- aevo-mcp --transport stdio
```

**Example — Claude Desktop config (local):**

```json
{
  "mcpServers": {
    "aevo-trading": {
      "command": "aevo-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "AEVO_API_KEY": "your_key",
        "AEVO_API_SECRET": "your_secret",
        "AEVO_SIGNING_KEY_PRIVATE_KEY": "your_signing_key"
      }
    }
  }
}
```

### OpenClaw

```bash
clawhub install aevo
```

After installing, add your Aevo credentials as environment variables in your OpenClaw config.

***

## Self-hosted environment variables

| Variable                       | Required | Description                                             |
| ------------------------------ | -------- | ------------------------------------------------------- |
| `AEVO_API_KEY`                 | Yes\*    | API key from your Aevo account settings                 |
| `AEVO_API_SECRET`              | Yes\*    | API secret from your Aevo account settings              |
| `AEVO_SIGNING_KEY_PRIVATE_KEY` | Yes      | Signing key required for order submission               |
| `AEVO_ENVIRONMENT`             | No       | `testnet` or `mainnet` (default: `mainnet`)             |
| `AEVO_WALLET_ADDRESS`          | No       | Wallet address (used with `register_account` tool)      |
| `AEVO_WALLET_PRIVATE_KEY`      | No       | Wallet private key (used with `register_account` tool)  |
| `AEVO_AUTO_REGISTER`           | No       | Auto-register signing key on startup (`true` / `false`) |

\* Not required if using `AEVO_WALLET_ADDRESS` + `AEVO_WALLET_PRIVATE_KEY` with the `register_account` tool to generate API keys.

***

## Verifying Your Setup

Once connected, open a new session in your MCP client and type:

```
List the active BTC option expiries on Aevo.
```

The response should contain available expiry labels and times from Aevo. Then try:

```
Show the 25-delta skew for the nearest BTC option expiry.
```

Both requests work without credentials on the hosted mainnet endpoint. Analytics depend on available market data; interpolated delta points are synthetic and are not executable quotes.

***

## Testnet

For testing without real funds, use the Aevo testnet environment:

| Resource    | URL                                           |
| ----------- | --------------------------------------------- |
| Testnet App | [testnet.aevo.xyz](https://testnet.aevo.xyz/) |
| Testnet API | `https://api-testnet.aevo.xyz`                |
| Testnet MCP | `https://mcp-testnet.aevo.xyz/mcp`            |

Set `AEVO_ENVIRONMENT=testnet` in your environment variables when running the self-hosted server.

***

## Aevo Trading Skill

The [Aevo Trading Skill](https://github.com/ribbon-finance/aevo-trading-skills) provides structured guidance that helps AI agents use the MCP tools effectively. It includes reference material for all 45 tools, instrument naming conventions, risk guardrails, step-by-step workflow recipes, and an options strategy reference.

The skill can be installed alongside the MCP server for clients that support skill definitions (such as Claude Code or OpenClaw), giving the agent deeper context on how to plan trades, manage risk, and execute multi-leg strategies.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.aevo.xyz/docs/aevo-products/aevo-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
