---
name: chainstack
description: Work with the Chainstack MCP server to manage blockchain nodes and projects. Use when deploying nodes, checking platform status, searching Chainstack docs, or interacting with the Chainstack platform API via MCP or curl.
metadata:
  version: "1.1"
---

# Chainstack MCP Server

Endpoint: `https://mcp.chainstack.com/mcp`

## Access tiers

The server has two tiers of access from the same endpoint.

**No API key required** (just connect to the URL, no auth header needed):
- `search_docs` — search Chainstack documentation
- `get_doc_page` — get full content of a documentation page
- `get_platform_status` — check platform status, incidents, maintenances

**API key required** (pass `Bearer <chainstack-api-key>`):
- All platform tools: `get_organization`, `list_projects`, `create_project`, `get_project`, `update_project`, `delete_project`, `list_nodes`, `get_node`, `create_node`, `update_node`, `delete_node`, `get_deployment_options`

Get an API key at https://console.chainstack.com/user/settings/api-keys

## Node tiers

Chainstack has two node tiers. Picking the right one is critical when deploying.

**Global Nodes** (cloud `CC-0016`, provider `chainstack_global`):
- Load-balanced across regions, routes to nearest location
- Deploys instantly
- Available on all plans including free
- Best for: getting started, general RPC access

**Trader Nodes** (clouds `CC-0020` through `CC-0028`, provider `chainstack_managed`):
- Region-bound, dedicated resources
- Deploys in 3-6 minutes
- Paid plans only
- Full and archive modes available
- Best for: low-latency trading, MEV, heavy indexing

The `node_tier` field in tool responses shows "Global" or "Trader" for clarity.

## Workflows

### Deploy a node

This is a multi-step flow. Always follow this order:

1. **Get deployment options**: Call `get_deployment_options` to see available blockchain/cloud/network combinations. Note the `blockchain` and `cloud` IDs you need.
2. **Confirm location with the user**: Trader nodes are region-bound (e.g., London, Ashburn, Singapore). Always show the user the available regions and ask which one before deploying. Region affects latency and cannot be changed after deployment.
3. **Get or create a project**: Call `list_projects` to find an existing project, or `create_project` to make a new one. Note the project `id` (format: `PR-123-456-789`).
4. **Create the node**: Call `create_node` with `name`, `project`, `blockchain`, and `cloud` from the previous steps.

Example: to deploy a Trader-tier Ethereum node in London:
- From `get_deployment_options`, find the entry where `protocol` is "Ethereum", `network` is "Mainnet", and `node_tier` is "Trader" with region "London". Use its `blockchain` (e.g., `BC-000-000-008`) and `cloud` (e.g., `CC-0020`).
- From `list_projects`, pick a project or create one.
- Call `create_node(name="my-eth-node", project="PR-...", blockchain="BC-000-000-008", cloud="CC-0020")`.

Trader nodes take 3-6 minutes to deploy. The response returns immediately with `status: "pending"`. Use `get_node` to poll until `status` is `"running"`.

### Check platform status

Call `get_platform_status()` for overall status and active incidents. Pass a `network` parameter (e.g., `"ethereum"`) to also get component-level status for that network.

No API key needed.

### Search documentation

Call `search_docs(query="...")` with a natural language query. Returns titles, links, and snippets from docs.chainstack.com.

To get the full content of a page, call `get_doc_page(page="docs/page-slug")` with the path from the search results Link field (without the leading slash or domain). Example: if search returns `Link: https://docs.chainstack.com/docs/ethereum-trader-nodes`, call `get_doc_page(page="docs/ethereum-trader-nodes")`.

No API key needed. Useful for finding RPC method references, deployment guides, and API examples.

### Manage projects

Projects are containers for nodes.

- `list_projects` — see all projects (returns `id`, `name`, `description`, `type`, `networks`)
- `get_project(project_id)` — full project details
- `create_project(name, description)` — create a new container
- `update_project(project_id, name, description)` — rename or update description
- `delete_project(project_id)` — irreversible, deletes the project

### Manage nodes

- `list_nodes` — all nodes with status, endpoints, tier, region
- `get_node(node_id)` — full details including cloud, blockchain, API namespaces
- `update_node(node_id, name)` — rename a node
- `delete_node(node_id)` — irreversible, deletes the node

## Using via curl

The server is fully curlable. JSON-RPC 2.0 over HTTP with Server-Sent Events responses. Parse the `data:` line from the SSE response for the JSON-RPC result.

**Step 1.** Initialize a session (no auth needed):

```bash
SESSION_ID=$(curl -sD - -X POST https://mcp.chainstack.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"agent","version":"1.0"}}}' \
  | grep -i mcp-session-id | cut -d' ' -f2 | tr -d '\r')
```

**Step 2.** Call a public tool (no API key needed):

```bash
curl -s -X POST https://mcp.chainstack.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"deploy ethereum node"}}}'
```

**Step 3.** Call an authenticated tool (requires `CHAINSTACK_API_KEY` env var):

```bash
curl -s -X POST https://mcp.chainstack.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $CHAINSTACK_API_KEY" \
  -H "MCP-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_nodes","arguments":{}}}'
```

If `CHAINSTACK_API_KEY` is not set, guide the user to add it to their shell profile
(e.g., `~/.zshrc`, `~/.bashrc`, or equivalent) so it persists across sessions:

```bash
export CHAINSTACK_API_KEY="your-key-from-console.chainstack.com/user/settings/api-keys"
```

Never ask the user to paste their API key in chat. Always use the `$CHAINSTACK_API_KEY` environment variable in curl commands.

## Error handling

- **401**: No or invalid API key. Get one at console.chainstack.com > Settings > API keys.
- **403**: Insufficient permissions for this operation.
- **404**: Resource not found. Check the ID format (e.g., `ND-123-456-789`, `PR-123-456-789`).
- **429**: Rate limit exceeded. Wait and retry.

## Updates

Latest version of this skill: https://mcp.chainstack.com/skill

If tools stop working or return unexpected errors, fetch the latest skill from the URL
above and replace your local copy. Tool names, parameters, and workflows may change
between versions.