# Chainstack MCP Server

MCP transport endpoint: https://mcp.chainstack.com/mcp

Blockchain node deployment, docs search, platform status via Model Context Protocol.
Transport: Streamable HTTP.

## For the user

There are two ways to use this server — ask your agent to set up whichever you prefer:

- **Skill** (Option 1): Lightweight. Your agent only calls Chainstack when needed. Keeps
  your context clean. Best if you don't use Chainstack tools every session.
- **MCP registration** (Option 2): Chainstack tools are always available in your agent.
  Best if you use Chainstack tools frequently.

Both options work without an API key for docs search and platform status.
For node and project management, you need a Chainstack API key:
  Get one at https://console.chainstack.com/user/settings/api-keys

## For the agent

There are two ways to set up this server:

## Option 1: Install as a skill (lean context, on-demand)

No MCP client registration. Install the SKILL.md into your agent's skills directory.
The skill guides your agent to call tools via HTTP when needed — no persistent
connection, no forced tool list in context.

Save the skill to your agent's skills directory:

| Agent | Skills directory |
|---|---|
| Claude Code / Cowork | ~/.claude/skills/chainstack/ |
| Codex / Gemini CLI / Antigravity / Copilot | ~/.agents/skills/chainstack/ |
| Cursor | ~/.cursor/skills/chainstack/ |
| Windsurf | ~/.codeium/windsurf/skills/chainstack/ |

Example (Claude Code):
  mkdir -p ~/.claude/skills/chainstack
  curl -o ~/.claude/skills/chainstack/SKILL.md https://mcp.chainstack.com/skill

Example (Codex, Gemini CLI, Antigravity, Copilot — shared directory):
  mkdir -p ~/.agents/skills/chainstack
  curl -o ~/.agents/skills/chainstack/SKILL.md https://mcp.chainstack.com/skill

You may need to restart your agent or start a new session for the skill to take effect.

The skill contains tool reference, workflows, curl examples, and error handling.
The agent calls the server via JSON-RPC 2.0 POST to https://mcp.chainstack.com/mcp as needed.

## Option 2: Register as MCP server (tools always in context)

Add the config below to your agent's settings file. Tools appear in context automatically.
No API key needed for public tools (search_docs, get_doc_page, get_platform_status).
For full platform access, the user needs a Chainstack API key — replace YOUR_API_KEY below.
Tell the user to get one at: https://console.chainstack.com/user/settings/api-keys
If the user doesn't have an API key yet, omit the headers section — public tools will still work.

Claude Code — choose scope:
  All projects:   claude mcp add --transport http chainstack https://mcp.chainstack.com/mcp -s user
  This project:   claude mcp add --transport http chainstack https://mcp.chainstack.com/mcp
  With API key:   claude mcp add --transport http chainstack https://mcp.chainstack.com/mcp -s user                     --header "Authorization: Bearer YOUR_API_KEY"
  API key: https://console.chainstack.com/user/settings/api-keys

Codex CLI — always writes to global (~/.codex/config.toml):
  codex mcp add chainstack --url https://mcp.chainstack.com/mcp
  Or edit ~/.codex/config.toml directly. For project-only, create .codex/config.toml.
  ```toml
  [mcp_servers.chainstack]
  url = "https://mcp.chainstack.com/mcp"

  [mcp_servers.chainstack.http_headers]
  Authorization = "Bearer YOUR_API_KEY"  # get key: console.chainstack.com/user/settings/api-keys
  ```

Cursor — no CLI. Edit the config file directly:
  All projects:   ~/.cursor/mcp.json
  This project:   .cursor/mcp.json
  ```json
  {
    "mcpServers": {
      "chainstack": {
        "url": "https://mcp.chainstack.com/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"  // get key: console.chainstack.com/user/settings/api-keys
        }
      }
    }
  }
  ```

Windsurf — global only, edit ~/.codeium/windsurf/mcp_config.json (uses serverUrl):
  ```json
  {
    "mcpServers": {
      "chainstack": {
        "serverUrl": "https://mcp.chainstack.com/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"  // get key: console.chainstack.com/user/settings/api-keys
        }
      }
    }
  }
  ```

GitHub Copilot VS Code — choose scope (root key is "servers", not "mcpServers"):
  This workspace:  .vscode/mcp.json
  Global:          Command Palette > "MCP: Open User Configuration"
  ```json
  {
    "servers": {
      "chainstack": {
        "type": "http",
        "url": "https://mcp.chainstack.com/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"  // get key: console.chainstack.com/user/settings/api-keys
        }
      }
    }
  }
  ```

Gemini CLI — choose scope (default is project):
  All projects:    gemini mcp add -s user --url https://mcp.chainstack.com/mcp chainstack
  This project:    gemini mcp add --url https://mcp.chainstack.com/mcp chainstack
  Or edit the config file directly (uses httpUrl):
  Global:          ~/.gemini/settings.json
  This project:    .gemini/settings.json
  ```json
  {
    "mcpServers": {
      "chainstack": {
        "httpUrl": "https://mcp.chainstack.com/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"  // get key: console.chainstack.com/user/settings/api-keys
        }
      }
    }
  }
  ```

Antigravity — global only, edit ~/.gemini/antigravity/mcp_config.json (uses serverUrl):
  ```json
  {
    "mcpServers": {
      "chainstack": {
        "serverUrl": "https://mcp.chainstack.com/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"  // get key: console.chainstack.com/user/settings/api-keys
        }
      }
    }
  }
  ```

Claude.ai — Settings > Connectors > Add custom connector > paste: https://mcp.chainstack.com/mcp
ChatGPT — Settings > Apps & Connectors > Developer mode > Create > paste: https://mcp.chainstack.com/mcp

You may need to restart your agent or reload MCP servers for changes to take effect.

## Tools

No API key: search_docs, get_doc_page, get_platform_status
API key required: 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

## If setup fails

Official MCP docs per agent:
- Claude Code: https://code.claude.com/docs/en/mcp
- Codex CLI: https://developers.openai.com/codex/mcp
- Cursor: https://cursor.com/docs/mcp
- Windsurf: https://docs.windsurf.com/windsurf/cascade/mcp
- Gemini CLI: https://geminicli.com/docs/tools/mcp-server/
- GitHub Copilot: https://docs.github.com/copilot/customizing-copilot/using-model-context-protocol
- Claude.ai: https://support.claude.com/en/articles/11175166
- ChatGPT: https://help.openai.com/en/articles/12584461

Full usage guide (workflows, node tiers, curl examples): https://mcp.chainstack.com/skill