Casper

MCP (Model Context Protocol) server for the Casper Network blockchain. Gives any AI assistant or MCP-compatible tool access to on-chain data — accounts, blocks, deploys, validators, smart contracts, tokens, NFTs, transfers, and network status.

Language-agnostic. Supports both stdio (local) and Streamable HTTP (remote, multi-tenant) transports. Use it from any project — Python, Node.js, Rust, Go, or any MCP client.

Built with CSPR.Cloud.Net and the ModelContextProtocol SDK.

v3.0.0 BREAKING CHANGES — if you are upgrading from v2.x, see the Breaking Changes section before updating.

Quick Start

Option 1: .NET Global Tool (recommended)

dotnet tool install -g CasperMcp
casper-mcp --api-key YOUR_API_KEY

Option 2: Docker (no .NET required)

# Pre-built image from GitHub Container Registry
docker pull ghcr.io/msanlisavas/casper-mcp:latest
docker run -i ghcr.io/msanlisavas/casper-mcp:latest --api-key YOUR_API_KEY

# Or build locally
docker build -t casper-mcp .
docker run -i casper-mcp --api-key YOUR_API_KEY

Option 3: Build from source

git clone https://github.com/msanlisavas/casper-mcp.git
cd casper-mcp
dotnet build
dotnet run --project src/CasperMcp -- --api-key YOUR_API_KEY

Configuration

Breaking Changes (v3.0.0)

Client Setup

The server works with any MCP client regardless of what language your project uses. Below are copy-paste configs for popular clients.

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "casper": {
      "command": "casper-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}

{
  "mcpServers": {
    "casper": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/msanlisavas/casper-mcp:latest", "--api-key", "YOUR_API_KEY"]
    }
  }
}

{
  "mcpServers": {
    "casper": {
      "command": "casper-mcp",
      "env": {
        "CSPR_CLOUD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add casper -- casper-mcp --api-key YOUR_API_KEY

Or add to your MCP settings JSON:

{
  "mcpServers": {
    "casper": {
      "command": "casper-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "casper": {
      "command": "casper-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "casper": {
      "type": "stdio",
      "command": "casper-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "casper": {
      "command": "casper-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "casper-mcp",
          "args": ["--api-key", "YOUR_API_KEY"]
        }
      }
    ]
  }
}

Any MCP Client (generic)

The server supports stdio and Streamable HTTP transports. For stdio, start the process and communicate over stdin/stdout using JSON-RPC. For http, connect over HTTP:

# stdio mode (local, default)
casper-mcp --api-key YOUR_API_KEY

# Or with environment variable
CSPR_CLOUD_API_KEY=YOUR_API_KEY casper-mcp

# Or with Docker
docker run -i --rm casper-mcp --api-key YOUR_API_KEY

# HTTP mode (remote/multi-tenant, stateless Streamable HTTP at /mcp)
casper-mcp --transport http --port 3001
# Clients must send: X-CSPR-Cloud-Api-Key: <key> in each request

Transport Modes

The server supports two transport modes. Choose based on your use case:

Understanding the Two API Keys

In stdio mode there is a single API key that identifies the local user to CSPR.Cloud:

In http mode the CSPR.Cloud key is supplied per request (no startup key required):

Authentication Modes (http transport)

Configure with --auth-mode / CASPER_MCP_AUTH_MODE:

The server validates tokens only — it does not issue them.

Remote Deployment (v3.0.0)

From v3.0.0, casper-mcp is designed for stateless multi-tenant remote deployment:

• Endpoint: POST /mcp (Streamable HTTP, stateless — no persistent SSE sessions).
• Per-agent CSPR.Cloud key: each HTTP request must carry X-CSPR-Cloud-Api-Key: <key>. Different agents can use different keys in the same server instance.
• Per-request network: optionally override the network via X-Casper-Network: mainnet|testnet.
• Pluggable auth: choose none (WAF-trust), apikey (shared secret), or jwt (OAuth 2.1) at startup.
• Designed to sit behind a WAF/reverse proxy for TLS termination, rate limiting, and IP filtering.

Built for remote AI agents behind a WAF (at scale)

One shared instance can serve thousands of agents as a remote MCP endpoint. How each common requirement is met:

Per-tenant isolation and connection reuse are handled by IHttpClientFactory (pooled sockets) plus a fresh per-request client, so a single instance handles many distinct agent keys concurrently without leaking credentials across tenants or exhausting sockets.

Run locally in http mode

dotnet run --project src/CasperMcp -- --transport http --port 3001

Output:

Casper MCP (http) on http://0.0.0.0:3001/mcp | auth=None | default-network=mainnet

Endpoints:

• POST /mcp — Streamable HTTP transport for MCP clients (requires X-CSPR-Cloud-Api-Key header)
• GET /health — Liveness check (returns JSON status, always public)
• GET /ready — Readiness check (always public)

Docker (http mode)

docker pull ghcr.io/msanlisavas/casper-mcp:latest
docker run -p 3001:3001 ghcr.io/msanlisavas/casper-mcp:latest \
  --transport http --port 3001

Each MCP client request must include X-CSPR-Cloud-Api-Key: YOUR_API_KEY.

Docker Compose

# Optional: set auth mode
echo "CASPER_MCP_AUTH_MODE=none" > .env

# Optional: protect the endpoint with a shared API key
# echo "CASPER_MCP_AUTH_MODE=apikey" > .env
# echo "CASPER_MCP_AUTH_API_KEY=your-secret-key" >> .env

# Start the server
docker compose up -d

# Verify
curl http://localhost:3001/health
curl http://localhost:3001/ready

Authentication Examples

apikey mode:

# Start with apikey auth
casper-mcp --transport http --auth-mode apikey --auth-api-key my-secret

# Client sends both headers
curl -X POST http://localhost:3001/mcp \
  -H "Authorization: Bearer my-secret" \
  -H "X-CSPR-Cloud-Api-Key: YOUR_CSPR_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

jwt mode:

# Start with JWT auth
casper-mcp --transport http \
  --auth-mode jwt \
  --auth-jwt-authority https://your-idp.example.com \
  --auth-jwt-audience casper-mcp

# Client sends JWT + CSPR key
curl -X POST http://localhost:3001/mcp \
  -H "Authorization: Bearer <JWT>" \
  -H "X-CSPR-Cloud-Api-Key: YOUR_CSPR_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Observability

The server is instrumented so you can watch traffic and health in your own stack.

OpenTelemetry (traces + metrics). Set the standard OTEL_EXPORTER_OTLP_ENDPOINT env var and the server exports to your OTLP collector (Grafana/Tempo/Jaeger, Prometheus via the OTel Collector, Datadog, etc.). When the var is unset, telemetry is off and the server runs normally.

docker run -p 3001:3001 \
  -e CASPER_MCP_TRANSPORT=http \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
  ghcr.io/msanlisavas/casper-mcp:latest

What's emitted:

• Traces: an ASP.NET Core server span per request, an outbound HttpClient span per CSPR.Cloud call, and a tool/<name> span per MCP tool call (tagged mcp.tool and casper.tenant).
• Metrics: casper_mcp.tool.calls (counter) and casper_mcp.tool.duration (histogram, ms), both tagged by tool and status (ok / error / cancelled), plus standard ASP.NET Core, HttpClient, and .NET runtime metrics (request rate, latency, in-flight, GC, etc.).
• Structured logs (JSON to stdout): one line per tool call — tool, status, duration_ms, tenant, correlation_id — so you can grep/ship logs even without OTLP.

Per-agent correlation without exposing keys. Logs, spans, and metrics tag traffic with a tenant value that is a non-reversible fingerprint of the agent's CSPR.Cloud key (k_ + a short SHA-256 prefix, e.g. k_3f9a1c2b4d5e). You can see per-agent request volume, latency, and error rates and correlate a tenant's activity across logs/traces — the raw key is never logged, traced, or returned in errors. (anonymous is used when no key is present.)

Health probes: GET /health (liveness) and GET /ready (readiness) — both unauthenticated, for your load balancer / k8s.

HTTP Client Configs

Clients that support Streamable HTTP transport can connect to a running server:

{
  "mcpServers": {
    "casper": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "X-CSPR-Cloud-Api-Key": "YOUR_CSPR_CLOUD_KEY"
      }
    }
  }
}

{
  "servers": {
    "casper": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "headers": {
        "X-CSPR-Cloud-Api-Key": "YOUR_CSPR_CLOUD_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "casper": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "X-CSPR-Cloud-Api-Key": "YOUR_CSPR_CLOUD_KEY"
      }
    }
  }
}

Connecting from Python

pip install mcp

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {
        "X-CSPR-Cloud-Api-Key": "YOUR_CSPR_CLOUD_KEY",
        # Optional: "X-Casper-Network": "testnet"
    }
    async with streamablehttp_client("http://localhost:3001/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            result = await session.call_tool("GetNetworkStatus", {})
            print(result)

asyncio.run(main())

Connecting from Node.js

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3001/mcp"),
  {
    requestInit: {
      headers: {
        "X-CSPR-Cloud-Api-Key": "YOUR_CSPR_CLOUD_KEY",
        // Optional: "X-Casper-Network": "testnet"
      }
    }
  }
);
const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
const result = await client.callTool({ name: "GetNetworkStatus", arguments: {} });
console.log(result);

Connecting from OpenAI Agents SDK

pip install openai-agents mcp

from agents import Agent
from agents.mcp import MCPServerStreamableHttp

casper = MCPServerStreamableHttp(
    url="http://localhost:3001/mcp",
    headers={
        "X-CSPR-Cloud-Api-Key": "YOUR_CSPR_CLOUD_KEY",
        # Optional server auth if auth-mode is apikey:
        # "X-API-Key": "your-server-secret"
    }
)

agent = Agent(
    name="Blockchain Assistant",
    instructions="You help users query the Casper blockchain.",
    mcp_servers=[casper]
)

Available Tools (87 tools)

Account Tools

Block Tools

Deploy Tools

Validator Tools

Contract Tools

Token Tools (CEP-18)

FT Rate Tools

NFT Tools (CEP-47 / CEP-78)

Transfer Tools

Network Tools

Bidder Tools

Currency Tools

Centralized Account Tools

DEX Tools

CSPR.name Tools

Awaiting Deploy Tools

✍️ Write Tools — local signer only (stdio, opt-in)

These never run on the hosted/remote server. Signing is stdio-only; the remote POST /mcp endpoint is read-only. The private key is loaded locally and never leaves your machine.

⚠️ Use a low-balance hot account and start on testnet. Never point the signer at a high-value mainnet key. The signer is fail-closed — empty allowlists block everything — and writes are only ever possible locally over stdio.

→ Full setup: see docs/writes.md — key generation, policy configuration and the env-var reference, the build → preview → sign workflow, the mainnet runbook, isolation/hardening, the audit log, troubleshooting, and key rotation.

Note: The 10 Watch* WebSocket streaming tools (WatchBlocks, WatchDeploys, etc.) were removed in v3.0.0. Use polling with the request/response tools above instead (e.g. call GetDeploy repeatedly to wait for transaction confirmation).

Development

Prerequisites

• .NET 10 SDK
• A CSPR.Cloud API key

Build

dotnet build

Test

# Run all tests (unit + integration against testnet)
dotnet test

# Run with a specific testnet API key
CSPR_CLOUD_TESTNET_API_KEY=YOUR_KEY dotnet test

Pack as global tool

dotnet pack src/CasperMcp -c Release
dotnet tool install -g --add-source src/CasperMcp/nupkg CasperMcp

CI/CD

The project uses GitHub Actions for continuous integration and Docker image publishing.

Docker images are published to ghcr.io/msanlisavas/casper-mcp with these tags:

To release a new version:

git tag v3.0.0
git push origin v3.0.0

Debug with MCP Inspector

npx @modelcontextprotocol/inspector casper-mcp --api-key YOUR_API_KEY

Project Structure

casper-mcp/
├── src/CasperMcp/
│   ├── Configuration/     # Server + per-request options
│   ├── Helpers/           # Formatting (motes → CSPR, etc.)
│   ├── Middleware/        # HTTP middleware (per-agent key check, apikey auth)
│   ├── Observability/     # OpenTelemetry wiring, tool telemetry, key fingerprint
│   ├── Remote/            # Per-request client factory, header parsing, error mapping, tool filter
│   ├── Tools/             # MCP tool implementations (82 read + 5 stdio-only write)
│   ├── Writes/            # Local signer: fail-closed policy engine, ledger, introspector, builder
│   └── Program.cs         # Entry point, DI setup, dual transport
├── tests/CasperMcp.Tests/ # Unit + middleware + integration + HTTP-pipeline tests
├── observability/         # Ready-to-run Grafana (otel-lgtm) + .NET Aspire stacks
├── mcp.json               # MCP server manifest
├── Dockerfile
├── docker-compose.yml
└── casper-mcp.slnx

How It Works

┌──────────────┐  stdio / HTTP  ┌──────────────┐    HTTPS     ┌──────────────┐
│  MCP Client  │◄──────────────►│  casper-mcp   │◄────────────►│  CSPR.Cloud  │
│  (any lang)  │   JSON-RPC     │  (.NET 10)    │   REST API   │    API       │
└──────────────┘                └──────────────┘               └──────────────┘
  Claude, GPT,                    This server                    Casper Network
  Cursor, etc.                  (stdio or HTTP)                  blockchain data

The MCP server is a bridge between AI tools and the Casper blockchain. It supports two transport modes:

• stdio — spawn the process locally, communicate over stdin/stdout (default). Pass --api-key at startup.
• http — run as a stateless Streamable HTTP server; each request carries its own X-CSPR-Cloud-Api-Key. Designed for multi-tenant remote deployments behind a WAF.

License

MIT — see LICENSE.