MCP protocol details

JSON-RPC 2.0 over Streamable HTTP. Spec: MCP 2025-03-26. This page documents every method Blue Hub MCP server supports.

Endpoint

POSThttps://blueagent.dev/api/mcp

Content-Type: application/json
Accept: application/json (default) or text/event-stream (SSE)
CORS: * — works from browsers
Rate limit: 100 req/min/IP
Auth: none for read methods · x402 USDC for paid tools/call

Envelope

Every request and response wraps a JSON-RPC 2.0 envelope.

Request envelope

{
  "jsonrpc": "2.0",
  "id":      <number | string>,
  "method":  "<method-name>",
  "params":  { ... }
}

Success response

{
  "jsonrpc": "2.0",
  "id":      <same id>,
  "result":  { ... }
}

Error response

{
  "jsonrpc": "2.0",
  "id":      <same id>,
  "error":   { "code": -32600, "message": "..." }
}

`initialize`

Handshake. Returns protocol version + server capabilities. Call first.

Request

{
  "jsonrpc": "2.0",
  "id":      1,
  "method":  "initialize",
  "params":  {
    "protocolVersion": "2024-11-05",
    "capabilities":    {}
  }
}

Response

{
  "jsonrpc": "2.0",
  "id":      1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities":    { "tools": {} },
    "serverInfo": {
      "name":    "blue-agent",
      "version": "1.0.0"
    }
  }
}

`notifications/initialized`

Fire-and-forget notification from client → server signalling the handshake completed. Server returns no body (just 202 Accepted).

Request (no id — notifications are one-way)

{
  "jsonrpc": "2.0",
  "method":  "notifications/initialized"
}

`tools/list`

Returns every API registered on Blue Agent — first-party + community submissions. AI clients call this once after initialize and re-call on user action.

Request

{
  "jsonrpc": "2.0",
  "id":      2,
  "method":  "tools/list"
}

Response (truncated to 1 tool)

{
  "jsonrpc": "2.0",
  "id":      2,
  "result": {
    "tools": [{
      "name":        "honeypot_check",
      "description": "Detect rug-pull / honeypot patterns before trade.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "token": { "type": "string", "description": "Token contract address on Base" }
        },
        "required": ["token"]
      }
    }]
  }
}

Naming: MCP tool names use snake_case (e.g. honeypot_check); marketplace slugs use kebab-case (honeypot-check). Same tool, two display conventions.

`tools/call`

Invoke a tool by name. Free tools return the result inline. Paid tools return an x402 payment-required envelope inside the result body — see x402 payment flow.

Request — free tool (blue_idea)

{
  "jsonrpc": "2.0",
  "id":      3,
  "method":  "tools/call",
  "params": {
    "name":      "blue_idea",
    "arguments": { "prompt": "USDC streaming payroll for Base DAOs" }
  }
}

Response — free tool

{
  "jsonrpc": "2.0",
  "id":      3,
  "result": {
    "content": [{
      "type": "text",
      "text": "# Blue Idea Brief\n\n## Problem\n..."
    }]
  }
}

For paid tools, the content[].text field contains the x402 instructions (JSON-encoded). MCP doesn't have a payment field, so we inline it. Client SDKs that wrap x402 will detect and surface this.

`ping`

Liveness check. Returns an empty result object.

Request

{
  "jsonrpc": "2.0",
  "id":      4,
  "method":  "ping"
}

Error codes

CODEJSON-RPC NAMEWHEN

-32700

Parse error

Request body wasn't valid JSON

-32600

Invalid request

Envelope missing jsonrpc / method

-32601

Method not found

Unknown method (typo in name)

-32602

Invalid params

Missing required argument (e.g. prompt)

-32603

Internal error

Upstream tool service failed — see HTTP body

Streamable HTTP (SSE)

For clients that want server-streamed responses (or use the legacy mcp-remote bridge), set the request Accept header:

SSE request

POST https://blueagent.dev/api/mcp
Accept: text/event-stream
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

SSE response

Content-Type: text/event-stream

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}

Server emits a single message event per JSON-RPC response. Connection closes after each request — no long-poll, no server-initiated messages yet.

SDK shortcuts

Most clients (Claude Desktop, Cursor, mcp-remote) handle all of this for you — just point them at the URL. The protocol details here are useful if you're building a custom MCP client or debugging.

← PREVIOUS

REST API reference