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

# MCP Server

Search Aftermath API reference data from AI coding agents.

Aftermath MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that indexes Aftermath API reference data and exposes it to AI assistants through three lightweight tools. Instead of loading an entire API spec into your context window, your assistant can search and retrieve the endpoints it needs. Check the [API operation inventory from August 19, 2026](/for-developers/api/rest-api/endpoint-inventory.md) and the live service when an endpoint's availability or response matters.

Works with any MCP-compatible client: **Claude Code**, **Cursor**, **VS Code**, **Windsurf**, **Codex**, and more.

## Installation

No API key required — the server is hosted and ready to use. Pick your client below.

### Claude Code

Run this in your terminal:

```bash
claude mcp add --transport http aftermath-api https://mcp.aftermath.finance/mcp
```

Verify it was added:

```bash
claude mcp list
```

You should see `aftermath-api` in the output. The tools will be available immediately in your next Claude Code session.

### OpenAI Codex

Add the server with the Codex CLI:

```bash
codex mcp add aftermath-api --url https://mcp.aftermath.finance/mcp
```

Verify the configuration:

```bash
codex mcp list
```

Alternatively, add it to `~/.codex/config.toml`:

```toml
[mcp_servers.aftermath-api]
url = "https://mcp.aftermath.finance/mcp"
```

### Cursor

Add the following to `.cursor/mcp.json` in your project root (create the file if it doesn't exist):

```json
{
  "mcpServers": {
    "aftermath-api": {
      "type": "http",
      "url": "https://mcp.aftermath.finance/mcp"
    }
  }
}
```

Restart Cursor after saving. The MCP tools will appear in the agent's available tools.

### VS Code / Copilot

Add the following to `.vscode/mcp.json` in your project root (create the file if it doesn't exist):

```json
{
  "servers": {
    "aftermath-api": {
      "type": "http",
      "url": "https://mcp.aftermath.finance/mcp"
    }
  }
}
```

Restart VS Code after saving. The tools will be available to Copilot in agent mode.

### Windsurf

Add the following to your Windsurf MCP config (`~/.windsurf/mcp.json`):

```json
{
  "mcpServers": {
    "aftermath-api": {
      "type": "http",
      "url": "https://mcp.aftermath.finance/mcp"
    }
  }
}
```

Restart Windsurf after saving.

## How It Works

Traditional approach: paste an entire OpenAPI spec into your prompt and burn thousands of tokens on endpoints you never use.

Aftermath MCP takes a different approach:

1. The server indexes its available Aftermath API reference at startup
2. Your AI assistant discovers available categories with `list_tags`
3. It searches for relevant endpoints with `search_endpoints`
4. It fetches full details (params, schemas, descriptions) only for the endpoints it actually needs with `get_endpoint_details`

The result: your assistant can retrieve focused API context without loading the whole reference.

## Tools

| Tool                   | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| `list_tags`            | List all API categories with endpoint counts                          |
| `search_endpoints`     | Search by keyword, tag, HTTP method, or path pattern                  |
| `get_endpoint_details` | Get full parameters, request/response schemas for a specific endpoint |

## Examples

Once installed, you can ask your AI assistant to work with the Aftermath API naturally. The agent will use the MCP tools behind the scenes to discover the right endpoints, understand their schemas, and write correct code.

**Build a TypeScript function that fetches 1h candles for BTC-PERP:**

```
Write a TypeScript function using fetch that pulls the last 24 hours of 1-hour
OHLCV candles for the BTC-PERP market from the Aftermath API. Return the data
as an array of { open, high, low, close, volume, timestamp } objects.
```

The agent will search for candle/OHLCV endpoints, inspect the request body schema and response format, and produce a working function with the correct URL, method, and parameters.

**Generate a Python script to monitor perpetuals account health:**

```
Write a Python script that takes an account ID as a CLI argument, fetches its
open perpetuals positions from the Aftermath API, and prints a table showing
each position's market, side, size, entry price, mark price, margin, and
unrealized PnL. Warn if any position's margin ratio is below 5%.
```

The agent will discover the accounts and positions endpoints, understand the response schemas including margin and PnL fields, and generate a complete script with proper error handling.