OpenClaw / MCP integration

OpenClaw MCP Integration: Complete Tool Discovery & Session Guide

Name: Delx Recovery Protocol
Author: Delx

Connect OpenClaw to any MCP-compliant server in four steps. This guide covers endpoint configuration, tool discovery, schema validation, session continuity, and DELX_META handling with copy-paste JSON-RPC examples you can use immediately.

OpenClaw + MCP architecture overview

OpenClaw communicates with MCP servers using JSON-RPC 2.0 over Streamable HTTP. Every tool call follows the same lifecycle: the agent discovers available tools, validates parameters against the published schema, sends the call, and parses the structured response including any DELX_META metadata.

Transport — Streamable HTTP (POST to the MCP endpoint). No WebSocket upgrade required.
Protocol — JSON-RPC 2.0. Every request carries jsonrpc, method, params, and id.
Discovery — tools/list returns all available tools with their input schemas.
Execution — tools/call invokes a specific tool with validated parameters.
Session — x-delx-session-id header persists state across calls.

Step 1: Configure the MCP endpoint

Point your OpenClaw agent at the MCP server by setting the endpoint URL and authentication headers. The config accepts any MCP-compliant server, not just Delx.

{
  "mcp": {
    "endpoint": "https://api.delx.ai/api/v1/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY",
      "x-delx-session-id": "session_abc123"
    },
    "timeout_ms": 15000
  }
}

endpoint — full URL to the MCP server. Must accept POST requests.
headers — include auth and session headers. The session ID is optional on the first call; the server returns one if omitted.
timeout_ms — max wait time per request. Default 15000 for tool calls, 5000 for discovery.

Step 2: Discover available tools

Before making any tool call, use tools/list to enumerate every tool the server exposes. The response includes tool names, descriptions, and full JSON Schema definitions for each input.

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

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "session-recap",
        "description": "Returns the current session state including health score and risk level.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "session_id": { "type": "string" }
          },
          "required": ["session_id"]
        }
      },
      {
        "name": "recovery-start",
        "description": "Initiates a structured recovery loop for a degraded agent.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "session_id": { "type": "string" },
            "incident_type": { "type": "string" }
          },
          "required": ["session_id", "incident_type"]
        }
      }
    ]
  }
}

Cache the tool list at agent startup. Re-fetch only when you receive a schema validation error or after a server version change.

Step 3: Make your first tool call

Use tools/call to invoke a specific tool. Include the session ID header to maintain continuity across requests.

// Request
POST /api/v1/mcp HTTP/1.1
Authorization: Bearer YOUR_API_KEY
x-delx-session-id: session_abc123
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "session-recap",
    "arguments": {
      "session_id": "session_abc123"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Session active. Score: 92. No incidents."
      }
    ],
    "DELX_META": {
      "session_id": "session_abc123",
      "score": 92,
      "risk_level": "low"
    }
  }
}

The params.name field must match a tool from the tools/list response exactly.
The params.arguments object is validated against the tool's inputSchema before sending.
The DELX_META block in the response carries session state you should persist.

Step 4: Handle DELX_META in responses

Every Delx MCP response includes a DELX_META object alongside the standard content array. Parse these fields to drive agent behavior:

session_id — the canonical session identifier. Store this and include it in subsequent x-delx-session-id headers.
score — agent health score from 0 to 100. Below 50 indicates degraded state.
risk_level — one of low, medium, or high. Use this to adjust heartbeat cadence or trigger recovery.

// Parsing DELX_META in your agent
const response = await fetch(MCP_ENDPOINT, { method: "POST", headers, body });
const json = await response.json();

const meta = json.result?.DELX_META;
if (meta) {
  agent.sessionId = meta.session_id;
  agent.healthScore = meta.score;

  if (meta.risk_level === "high") {
    agent.escalateHeartbeat();
  }
}

Schema validation

OpenClaw validates every tool call against the schema returned by tools/list before sending the request. This prevents malformed payloads from reaching the server and surfaces errors locally with clear messages.

Required fields — if a required parameter is missing, OpenClaw rejects the call before it leaves the agent.
Type checking — string, number, boolean, and object types are enforced. A string passed where a number is expected fails validation.
Enum constraints — if the schema defines allowed values, OpenClaw checks the argument against that set.
Nested objects — schemas with nested properties are validated recursively.

If validation fails, OpenClaw returns a structured error with the field name, expected type, and received value. No network request is made.

Session continuity across MCP calls

Session continuity ensures the MCP server maintains state between operations. Without it, every call is stateless and the server cannot track agent history, scores, or incident context.

First call — omit x-delx-session-id or send an empty value. The server creates a new session and returns the ID in DELX_META.session_id.
Subsequent calls — include the returned session ID in every request header. The server resumes the existing session.
After restart — if your agent restarts, call session-recap with the stored session ID to restore context without replaying previous calls.
Session expiry — sessions expire after 24 hours of inactivity by default. Heartbeat calls reset the TTL.

// Persist session ID across calls
let sessionId = loadFromStorage("delx_session_id");

const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  ...(sessionId && { "x-delx-session-id": sessionId })
};

const res = await mcpCall("session-recap", { session_id: sessionId });
sessionId = res.DELX_META?.session_id ?? sessionId;
saveToStorage("delx_session_id", sessionId);

Copy-paste JSON-RPC examples

Three ready-to-use examples. Replace YOUR_API_KEY and session_abc123 with your actual values.

Example 1: tools/list — discover available tools

curl -X POST https://api.delx.ai/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Example 2: tools/call — invoke session-recap

curl -X POST https://api.delx.ai/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-delx-session-id: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "session-recap",
      "arguments": {
        "session_id": "session_abc123"
      }
    }
  }'

Example 3: tools/call — start recovery

curl -X POST https://api.delx.ai/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-delx-session-id: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "recovery-start",
      "arguments": {
        "session_id": "session_abc123",
        "incident_type": "degraded_performance"
      }
    }
  }'

Troubleshooting MCP connection issues

Connection refused or timeout — verify the endpoint URL is correct and the server is running. Check firewall rules and ensure the port is open.
401 Unauthorized — confirm your API key is valid and included in the Authorization header. Keys expire; regenerate if needed.
Schema validation error on a previously working tool — the server may have updated its tool schemas. Re-run tools/list to refresh your cached schemas.
Session ID not recognized — the session may have expired after 24 hours of inactivity. Create a new session by omitting the x-delx-session-id header on your next call.
DELX_META missing from response — you may be connecting to a non-Delx MCP server. DELX_META is Delx-specific. Standard MCP servers return only the content array.

FAQ

What MCP servers can OpenClaw connect to?

Any MCP-compliant server including Delx, filesystem, GitHub, and databases. OpenClaw uses standard JSON-RPC 2.0 over Streamable HTTP, so any server that implements the MCP specification works out of the box.

Does OpenClaw validate MCP tool schemas?

Yes, OpenClaw validates input schemas before every tool call, preventing malformed payloads and reducing runtime errors. Schema mismatches are caught before the request leaves the agent.

How does session continuity work with MCP?

Include x-delx-session-id in every request header. OpenClaw persists this across calls so the server maintains state between operations. Use the session-recap endpoint to restore context after restarts.

Can I use multiple MCP servers with one OpenClaw agent?

Yes. Configure multiple endpoint entries and OpenClaw routes tool calls to the correct server based on tool name prefix or namespace. Each server maintains its own session independently.

Is MCP integration free?

Yes. MCP tool discovery and calls are free during campaign mode. Heartbeat monitoring is permanently free. Only recovery interventions use x402 micropayments.

Next: MCP + A2A explained MCP documentation