Installation & usage

This page explains the main ways to connect an AI assistant to the Blurt blockchain through MCP.

If you are new to MCP, there are two common connection styles:

• Remote HTTP — your AI app connects to an MCP URL such as https://mcp.blurt-blockchain.com/mcp.
• Local stdio — your AI app launches a command on your computer. The command speaks MCP through standard input/output.

Use the hosted endpoint when you want the quickest read-only setup. Use the local package when your client requires stdio, when you want to choose your own Blurt blockchain RPC nodes, or when you later want opt-in local signing.

Requirements

• Node.js >= 18 to run the server or package.
• Node.js >= 20.6 for development and tests.
• npm.

Installation choices

Hosted endpoint — no install

Use this when your AI client supports remote MCP / Streamable HTTP:

https://mcp.blurt-blockchain.com/mcp

The hosted endpoint is anonymous and read-only. It does not need a private key.

Local stdio package

Use this when your client launches a local MCP server process:

npx -y -p @blurt-blockchain/blurt-mcp-server blurt-mcp-stdio

For client configuration, prefer using an environment file from the beginning. It gives read-only and write-capable setups the same layout, while keeping secrets out of JSON configs:

{
  "mcpServers": {
    "blurt": {
      "command": "npx",
      "args": ["-y", "-p", "@blurt-blockchain/blurt-mcp-server", "blurt-mcp-stdio"],
      "env": { "BLURT_ENV_FILE": "/home/you/.config/blurt-mcp/secret.env" }
    }
  }
}

The file may be empty for default read-only usage. Add read-only options such as BLURT_RPC_URLS if you want custom RPC nodes. Add a posting key only when you deliberately enable local write tools.

Source checkout

Use this when you want to develop or inspect the project from source:

npm install
npm run build

Then point your client at the compiled stdio entrypoint:

{
  "mcpServers": {
    "blurt": {
      "command": "node",
      "args": ["/absolute/path/to/blurt-mcp-server/dist/server-stdio.js"],
      "env": { "BLURT_ENV_FILE": "/home/you/.config/blurt-mcp/secret.env" }
    }
  }
}

For per-client examples, see install snippets.

Configuration

Configuration is read from environment variables. Local stdio users should normally put them in a file outside the repository and point the launcher at it with BLURT_ENV_FILE.

Example read-only file:

# /home/you/.config/blurt-mcp/secret.env
# Optional: choose several Blurt blockchain RPC nodes.
BLURT_RPC_URLS=https://rpc.blurt.world,https://blurt-rpc.saboin.com
# Optional: enable price-dependent tools.
BLURT_PRICE_URL=https://api.blurt.blog/price_info

Variable	Default / behavior when unset	Description
PORT	3000	HTTP port Express listens on.
BLURT_RPC_URLS	unset; RPC-backed tools unavailable	Comma-separated Blurt blockchain RPC endpoints. The MCP server does not hardcode a maintained node list. Provide several when self-hosting: the server scores them with @beblurt/blurt-nodes-checker and keeps the client on healthy nodes.
BLURT_RPC_TIMEOUT_MS	inherited from @beblurt/dblurt	Optional RPC call timeout for the dblurt client.
BLURT_RPC_FAILOVER_THRESHOLD	inherited from @beblurt/dblurt	Optional number of failover rounds for the dblurt client.
BLURT_NODE_CHECKER_*	inherited from @beblurt/blurt-nodes-checker	Optional node-checker timeout, interval, retry, stale-block and history settings. See .env.example for exact names and units.
BLURT_PRICE_URL	unset; price tools unavailable	Price feed used by price and market tools. Configure it explicitly for deployments that expose those tools.
BLURT_PRICE_CACHE_TTL_MS	no MCP-layer cache	Optional in-memory cache duration for the configured price feed.
BLURT_PRICE_TIMEOUT_MS	no MCP-layer fetch timeout	Optional timeout for the configured price feed request.
BLURT_HTTP_JSON_BODY_LIMIT	Express default	Optional JSON request-body limit for HTTP deployments.
HOST	Node/OS default bind behavior	Optional HTTP bind host. Use 127.0.0.1 when the MCP server runs behind a local reverse proxy; use 0.0.0.0 only when the platform network boundary is trusted.
LOG_LEVEL	info	debug | info | warn | error.
NODE_ENV	development	production switches logs to JSON output.
BLURT_CHAIN_ID	Blurt blockchain mainnet	Optional testnet chain id; set together with BLURT_ADDRESS_PREFIX.
BLURT_ADDRESS_PREFIX	mainnet BLT	Optional testnet address prefix; set together with BLURT_CHAIN_ID.

Write-related variables (BLURT_ACCOUNT, BLURT_POSTING_KEY, BLURT_WRITE_PROFILE, BLURT_WRITE_TOOLS_BANNED, BLURT_DRY_RUN_DEFAULT, BLURT_WRITE_RATE_LIMITS) are explained in write operations.

Running your own HTTP server

Use this when you want to self-host a remote MCP endpoint:

npm run build
npm start

The server listens on:

http://localhost:<PORT>/mcp

It also exposes simple operational probes outside MCP:

• GET /healthz — process liveness;
• GET /readyz — readiness with non-sensitive RPC readiness counters.

Deploy HTTP behind a reverse proxy such as nginx, Caddy or Traefik. Let the proxy handle TLS, rate limiting and host/origin filtering. Do not expose signing over HTTP unless you have deliberately enabled the unsafe trusted-deployment override described in write operations.

Connecting an MCP client

Remote-capable clients can use the hosted endpoint or your own /mcp URL directly.

Desktop clients that only support local commands can bridge the hosted endpoint with mcp-remote:

{
  "mcpServers": {
    "blurt": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.blurt-blockchain.com/mcp"]
    }
  }
}

For local stdio, use the package-bin example above. Logs go to stderr so they do not interfere with the MCP protocol on stdout.

Optional local signing

Local signing lets an AI assistant ask to claim rewards, vote, comment or perform other posting-key actions. It is off by default and uses a Blurt blockchain posting key only. Start with write operations before adding any key.