# `@anaxer/mcp`

Official [MCP](https://modelcontextprotocol.io) server for the Anaxer Solana real-time
data API. Add a few lines to Claude Desktop, Claude Code, or Cursor and the assistant
can call typed tools over your API key — prices, metadata, creations, graduations, and a
bounded live stream tail.

**Requires Node ≥ 20.** This package wraps [`@anaxer/sdk`](https://www.npmjs.com/package/@anaxer/sdk);
it adds no gateway or wire behavior.

```bash
npx -y @anaxer/mcp
```

## Setup

Set `ANAXER_API_KEY` in the MCP host config (never pass the key as a tool argument).

### Claude Desktop / Claude Code / Cursor

```jsonc
{
  "mcpServers": {
    "anaxer": {
      "command": "npx",
      "args": ["-y", "@anaxer/mcp"],
      "env": {
        "ANAXER_API_KEY": "sk_live_…"
      }
    }
  }
}
```

Optional:

| Env | Default | Purpose |
|---|---|---|
| `ANAXER_BASE_URL` | `https://api.anaxer.com` | REST base (local gateway: `http://localhost:3010`) |
| `ANAXER_WS_URL` | derived from base → `…/v1/stream` | Override WebSocket URL |

## Tools

| Tool | What it answers |
|---|---|
| `get_token_metadata` | Name/symbol/supply/socials for one mint |
| `get_tokens_metadata` | Batch metadata (≤50 mints) |
| `get_token_price` | Latest USD + SOL price / market cap for one mint |
| `get_token_prices` | Batch prices (≤50 mints) |
| `list_token_trades` | One page of swaps for a mint (either leg; optional `solOnly`; quote `:mint` rejected) |
| `list_creations` | One page of recent launches |
| `list_graduations` | One page of recent graduations |
| `get_launchpad_stats` | Aggregate launchpad stats over a window |
| `tail_stream` | Bounded live WS batch (`trades` / `creations` / `graduations` / `prices`) |

List tools default to `limit: 20` (max 200) to conserve model context. Paginate by calling
again with `cursor` set to the previous `next`; stop when `next` is null.

**Spelling:** REST list tools take a singular `source` string. `tail_stream` filters use a
`sources` **array** (WebSocket filter shape).

### `tail_stream` caps

- `maxEvents` — default `20`, cap `100`
- `timeoutMs` — default `10_000`, cap `30_000`
- Ends when **either** cap hits first; always unsubscribes before returning

Per-channel filter keys:

- `trades`: `sources`, `mints`, `wallets`, `minVolumeUsd`, `maxVolumeUsd`, `solOnly`
  (quote assets SOL/USDC/USDT rejected in `mints` — use `solOnly: true` for SOL pairs)
- `creations`: `sources`, `enriched`, `excludeMayhem`
- `graduations`: `sources`, `excludeMayhem`, `minLiquiditySol`
- `prices`: `sources`, `mints`

## v1 omissions

These are intentional, not bugs:

- No `tail_stream("transfers")` and no `list_programs` (same as `@anaxer/sdk` v1)
- No remote / hosted MCP (Streamable HTTP) — local **stdio** only
- No gap recovery on reconnect (SDK has none)
- No MCP resources or prompts — tools only

## Troubleshooting

1. **Wrong API key on `tail_stream`.** REST tools fail per call and recover as soon as you
   fix `ANAXER_API_KEY`. WebSocket `unauthorized` is **terminal** for the shared socket —
   **restart the MCP server process** (reload the host / re-run `npx @anaxer/mcp`) after
   fixing the key.
2. **`subscription_limit`.** Each open `tail_stream` holds one plan subscription until it
   returns. Overlapping tails (or a leaked subscription) on free/low plans can hit the
   cap. The server always `close()`s in `finally`; hosts normally serialize tool calls, so
   this is rare.

## License

MIT

---

## About this repository

This is a **read-only mirror**. ``packages/mcp`` in Anaxer's private monorepo is the
source of truth; this repo is regenerated from it on each release, so pull requests
here cannot be merged directly. Issues are very welcome — or reach us at
[anaxer.com/contact](https://anaxer.com/contact).