# Endpoint Arena MCP Integration

Endpoint Arena exposes a remote Model Context Protocol server for approved API users.

- MCP server URL: `https://endpointarena.com/api/mcp`
- Human docs: `https://endpointarena.com/mcp`
- REST API docs: `https://endpointarena.com/api`
- Transport: Streamable HTTP
- Auth: `Authorization: Bearer <Endpoint Arena API key>`

Use MCP when an agent needs live Endpoint Arena account readiness, market context, quotes, mock-USDC trade submission, or trade status.

## Access Flow

1. Create a normal Endpoint Arena account.
2. Complete Season 5 setup in the web app.
3. Request API access from `/profile`.
4. After approval, create an API key in `/profile`.
5. Configure your MCP client with the server URL and bearer token.

## Codex Setup

Set your approved Endpoint Arena API key in your shell:

```sh
export ENDPOINT_ARENA_API_KEY="ea_s4_..."
```

Add the remote MCP server:

```sh
codex mcp add endpointArena --url https://endpointarena.com/api/mcp --bearer-token-env-var ENDPOINT_ARENA_API_KEY
codex mcp list
```

Manual `~/.codex/config.toml`:

```toml
[mcp_servers.endpointArena]
url = "https://endpointarena.com/api/mcp"
bearer_token_env_var = "ENDPOINT_ARENA_API_KEY"
tool_timeout_sec = 120
```

Useful project instruction:

```text
Use the Endpoint Arena MCP server for Endpoint Arena account readiness, market lookup, quotes, trade submission, and trade status. Quote before submitting trades and ask for human confirmation before submit_trade.
```

## Tools

| Tool | Purpose |
| --- | --- |
| `get_account` | Account approval, mock-USDC balance, readiness flags, and environment guardrails. |
| `list_markets` | Current Season 5 market summaries. |
| `get_market` | Market detail, trial context, price history, and recent trades for one market. |
| `quote_trade` | Validate and price a proposed trade. |
| `submit_trade` | Submit a mock-USDC trade with a required idempotency key. |
| `get_trade` | Refresh and return one submitted trade status. |
| `list_trades` | Return recent trades for the authenticated API key. |

## Trade Request

`quote_trade` and `submit_trade` use:

```json
{
  "marketId": "example-market",
  "action": "BUY_YES",
  "amountUsd": 1,
  "slippageBps": 100
}
```

`submit_trade` also requires:

```json
{
  "idempotencyKey": "unique-key-for-this-intended-trade"
}
```

Actions are `BUY_YES`, `BUY_NO`, `SELL_YES`, and `SELL_NO`.

For buys, `amountUsd` is spend. For sells, `amountUsd` is desired proceeds. `slippageBps` is optional, defaults to `100`, and must be an integer from `0` through `5000`.

## Trading Safety

MCP v1 trades only Season 5 Base Sepolia mock-USDC markets. This is not a real-money production trading surface.

Agents should:

1. Call `get_account` before trading.
2. Stop if `readiness.canTrade` is false.
3. Inspect markets with `list_markets` or `get_market`.
4. Call `quote_trade` with the exact intended trade body.
5. Show the quote to the user before `submit_trade`.
6. Use a unique `idempotencyKey` for each intended trade.
7. Poll `get_trade` until status is `settled` or `failed`.

The existing REST API remains available at `/api`, but agent integrations should prefer MCP because tools are discoverable, typed, and described through the protocol.