Connect AI agents (Claude, Cursor, etc.) to Herald docs via MCP for assisted integration. Also covers using the Herald CLI as a direct tool for LLM agents.

AI Agent MCP

Herald exposes a Model Context Protocol (MCP) endpoint that lets AI agents browse documentation, search for topics, and retrieve copy-paste ready code — making integration faster.

Endpoint

POST https://useherald.xyz/api/mcp

The endpoint implements the MCP Streamable HTTP transport (JSON-RPC 2.0). No authentication required.

Available Tools

Tool	Description
`get_herald_context`	Full protocol context — architecture, SDK, API, specs, integration patterns
`search_herald_docs`	Search documentation by keyword. Params: `query`, `maxResults`
`get_integration_example`	Copy-paste code. Params: `pattern` — see table below
`get_doc_page`	Read a doc page by slug. Params: `slug` (e.g. `quickstart/quickstart`, `cli/commands`)

`get_integration_example` patterns

Pattern	Description
`backend`	Express server with liquidation alerts
`serverless`	Next.js API route
`webhook`	Webhook receiver with HMAC signature verification
`batch`	Batch-send to 100 wallets
`registration-check`	React component to check wallet registration
`broadcast`	Broadcast to all subscribers
`subscribe`	Manage wallet subscriptions
`cli-send`	Herald CLI one-liner for terminal or CI/CD
`cli-agent`	Herald CLI agent tool-use pattern with `--json`, `--wait`, `--from-stdin`

Configuring in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "herald-docs": {
      "type": "url",
      "url": "https://useherald.xyz/api/mcp"
    }
  }
}

Configuring in Cursor

Go to Settings > Features > MCP Servers
Add a new MCP server with URL: https://useherald.xyz/api/mcp

Configuring in Claude Code (CLI)

claude mcp add herald-docs --transport http https://useherald.xyz/api/mcp

Testing via curl

# List tools
curl -X POST https://useherald.xyz/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Get full context
curl -X POST https://useherald.xyz/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_herald_context","arguments":{}}}'

# Search docs
curl -X POST https://useherald.xyz/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_herald_docs","arguments":{"query":"CLI idempotency"}}}'

# Get CLI send example
curl -X POST https://useherald.xyz/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_integration_example","arguments":{"pattern":"cli-send"}}}'

# Get CLI agent pattern
curl -X POST https://useherald.xyz/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_integration_example","arguments":{"pattern":"cli-agent"}}}'

Using the Herald CLI as an agent tool

Instead of calling the REST API directly, AI agents can invoke the Herald CLI as a shell tool. This is simpler to configure, produces structured JSON output, and handles auth, retries, and idempotency automatically.

Install once

npm install -g @herald-protocol/cli

Tool definition (OpenAI / Claude tool-use format)

{
  "name": "herald_notify",
  "description": "Send a notification to a Solana wallet via Herald Protocol. Use --wait to block until delivered. Use --idempotency-key to make retries safe.",
  "parameters": {
    "type": "object",
    "properties": {
      "wallet":          { "type": "string", "description": "Recipient Solana wallet address" },
      "subject":         { "type": "string", "description": "Subject line (max ~100 chars)" },
      "body":            { "type": "string", "description": "Body text (Markdown supported)" },
      "category":        { "type": "string", "enum": ["defi","governance","system","marketing","security"] },
      "idempotency_key": { "type": "string", "description": "Unique key to prevent duplicate sends on retry" },
      "wait":            { "type": "boolean", "description": "Block until delivered or failed (recommended for agents)" }
    },
    "required": ["wallet", "subject", "body", "category"]
  }
}

Shell invocation

herald notify send \
  --wallet "$wallet" \
  --subject "$subject" \
  --body "$body" \
  --category "$category" \
  --idempotency-key "$idempotency_key" \
  --wait \
  --json

Recommended agent workflow

Health check first — call herald doctor --json and halt if ok is false
Send with --wait — get confirmed delivery in a single call instead of send + poll loop
Always use --idempotency-key — pass a unique key derived from your job/run ID so retries don't duplicate
Read exit codes — 0 success, 4 auth error, 5 rate-limited, 6 network down

Batch sends for agents

echo '[{"wallet":"…","subject":"…","body":"…","category":"system"}]' \
  | herald notify batch \
    --from-stdin \
    --idempotency-key "$JOB_ID" \
    --yes \
    --json

See the full CLI agent guide for more patterns.

Protocol

The endpoint uses MCP Streamable HTTP transport:

Initialize: Send {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"client","version":"1.0"}}}
List tools: {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
Call tool: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tool_name","arguments":{...}}}

All responses follow standard JSON-RPC 2.0 format.

AI Agent MCP

On this page