# MCP server

The [MCP](https://modelcontextprotocol.io) server gives coding agents access to SDK references, collection data and integration checks. Use it with an MCP-compatible editor or client while building with the GraveMint and GraveMarket SDKs.

## Install

This guide covers **@solanadeads/mcp 0.3.1**, with Node.js **20 or later**,
GraveMint SDK **^1.3.0** and GraveMarket SDK **0.3.1**. The configurations below
launch the published package locally over **stdio**. To use the same server without
installing anything, [connect to the hosted server](#connect-remotely) instead.


```jsonc [Claude Desktop]
// claude_desktop_config.json
{
  "mcpServers": {
    "solanadeads": {
      "command": "npx",
      "args": ["-y", "@solanadeads/mcp"],
      "env": { "GRAVEMINT_API_KEY": "gm_live_..." }
    }
  }
}
```

```bash [Claude Code]
claude mcp add solanadeads \
  --env GRAVEMINT_API_KEY=gm_live_... \
  -- npx -y @solanadeads/mcp
```

```jsonc [Cursor]
// .cursor/mcp.json
{
  "mcpServers": {
    "solanadeads": {
      "command": "npx",
      "args": ["-y", "@solanadeads/mcp"],
      "env": { "GRAVEMINT_API_KEY": "gm_live_..." }
    }
  }
}
```


GraveMarket's tools need no credential. GraveMint's are invite-only — without a key
the server still runs and simply exposes fewer tools, so you can try it before you
have one.

Use a server-side `gm_live_` key for GraveMint tools. Browser keys require an Origin header and are not suitable for MCP. See [keys and origins](https://docs.deads.io/guides/keys.md).

### Connect remotely

The same server runs at **`https://mcp.deads.io/mcp`** over Streamable HTTP. Point any
client that supports remote MCP servers at it:


```jsonc [Claude Desktop / Cursor]
{
  "mcpServers": {
    "solanadeads": {
      "url": "https://mcp.deads.io/mcp",
      "headers": { "X-GraveMint-Api-Key": "gm_live_..." }
    }
  }
}
```

```bash [Claude Code]
claude mcp add --transport http solanadeads https://mcp.deads.io/mcp \
  --header "X-GraveMint-Api-Key: gm_live_..."
```


The key is optional and is **yours**. Send it with each request, in
`X-GraveMint-Api-Key` or as `Authorization: Bearer gm_live_...`, and that request runs
with your key alone. Nothing is stored between requests. Without a key you get the
GraveMarket tools, `sdk_reference` and `review_integration`.

Each request carries one JSON-RPC message, and requests are rate limited per caller.

> **WARNING: Keep server keys private**
The hosted server accepts requests from any origin, so a web page could call it — but a
key in a page's JavaScript is a key every visitor can copy. Connect from your MCP
client, your editor or your own backend, where the key stays private.

## Integration checks {#why-you-want-it}

`review_integration` checks supplied code for known integration mistakes and returns line numbers and suggested changes. Its checks include price-display handling, client-side fee calculations, server submission, partial batch results and wallet-mint counts.

Ask your coding agent:

> Review this file for Solana Deads integration mistakes.

Use the result alongside your application's type checks and tests. The review is a diagnostic aid, not a guarantee that an integration is complete.

## What changed in 0.3.0

- **Full type context.** `sdk_reference` includes the response/input types and error classes, so an agent can inspect fields as well as method signatures.
- **Paginated mint history.** `gravemint_get_all_minted` accepts `limit`, `offset`, `sort` and `search`. Read successive pages until `hasMore` is false; use `newest` or `oldest` for pagination because `popular` ranks within a page.
- **Supply semantics.** Availability includes `burned`; `available` can be `null` for an open-ended generative drop. In-progress reservations can still count as available, so this count alone cannot establish that a drop is sold out.
- **Larger integration reviews.** `review_integration` accepts up to 200,000 characters and refuses larger inputs. It also flags client-side platform-fee arithmetic. Its checks cover known mistakes; a clean result does not prove the integration is correct.

Match these contracts to your installed SDK and target API deployment. Publishing a package does not deploy its server dependencies. See [version and deployment compatibility](https://docs.deads.io/guides/overview.md#version-and-deployment-compatibility).

For GraveMint SDK 1.3.0, an uncertain outcome after submission can throw
`MintOutcomeUnknownError` with `code: "OUTCOME_UNKNOWN"` and `sessionIds`.
**Do not automatically mint again:** the first mint may still complete. See
[the SDK mint flow](https://docs.deads.io/sdk/gravemint.md#minting) for the full handling contract.

## Tools

### Always available

| Tool | What it does |
|---|---|
| `sdk_reference` | Published SDK method signatures, response types and error classes. |
| `review_integration` | The checks above, with line numbers and concrete fixes. |

### GraveMarket — no credential needed

`gravemarket_get_collection` · `gravemarket_search` ·
`gravemarket_get_collection_activity` · `gravemarket_get_collection_stats`

### GraveMint — needs `GRAVEMINT_API_KEY`

**The drop**
`gravemint_get_collection` · `gravemint_check_eligibility` ·
`gravemint_get_wallet_mints` · `gravemint_get_availability`

**Its art and history**
`gravemint_get_gallery` · `gravemint_get_recently_minted` · `gravemint_get_all_minted` ·
`gravemint_get_traits` · `gravemint_get_leaderboards`

`gravemint_get_gallery` lists the NFTs that can still be minted; `gravemint_get_all_minted` lists
the minted ones and pages with `limit`, `offset`, `sort` and `search`.

**Pricing**
`gravemint_get_token_prices` · `gravemint_get_phase_price`

**Claim codes**
`gravemint_get_claim_codes` · `gravemint_get_claim_code_benefits` ·
`gravemint_validate_claim_code` *(read-only — it does not redeem or consume a use)*

**Bounty**
`gravemint_get_bounty`

Reads are restricted to the collections assigned to your key. Requests outside that scope return `403 COLLECTION_NOT_IN_SCOPE`.

## Read-only tools {#what-it-deliberately-cannot-do}

The server exposes documentation and read tools. It does not expose wallet signing, `prepare-mint` or `execute-mint`. Preparation reserves supply, so use the SDK reference to inspect its response type and implement the mint flow in your application.

---
Source: https://docs.deads.io/tools/mcp
Markdown: https://docs.deads.io/tools/mcp.md