OpenClaw Integration Guide

Prerequisites

• OpenClaw installed (npm install openclaw or equivalent)
• Node.js 18+ or Python 3.10+ (depending on your OpenClaw implementation)
• MCPulse account with API key (sign up at /signup)
• At least 2 monitored MCP servers registered in MCPulse
• Basic understanding of OpenClaw agent configuration

Step 1: Install Required Packages

Install both MCPulse monitor and the API client:

Node.js/TypeScript:

npm install mcpulse-monitor axios

Python:

pip install mcpulse httpx

Step 2: Monitor Your MCP Servers

First, wrap your MCP servers with monitoring (same as other platforms):

// weather-server.js
import { McpServer } from '@modelcontextprotocol/sdk';
import { wrapMcpServer } from 'mcpulse-monitor';

const server = new McpServer({
  name: 'weather-api',
  version: '1.0.0'
});

server.tool('get_weather', async ({ location }) => {
  // Weather API logic
  return { temperature: 72, conditions: 'sunny' };
});

const monitored = wrapMcpServer(server, {
  serverId: 'weather-server-id',
  reportInterval: 60000,
  batchSize: 50
});

monitored.start();

Repeat this for all MCP servers your OpenClaw agents might use.

Step 3: Build a Server Selection Module

Create a module that queries MCPulse and selects the best server:

reliability-selector.js

import axios from 'axios';

export class ReliabilitySelector {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://stacks.polsia.app/api';
  }

  async selectBestServer(serverIds, options = {}) {
    const {
      minReliability = 95.0,
      maxLatency = 500,
      window = '24h'
    } = options;

    try {
      // Query MCPulse API for reliability scores
      const response = await axios.get(`${this.baseUrl}/reliability`, {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`
        },
        params: {
          server_ids: serverIds.join(','),
          window
        }
      });

      // Filter by requirements
      const eligible = response.data.servers.filter(s =>
        s.reliability_score >= minReliability &&
        s.avg_response_time <= maxLatency &&
        s.status === 'healthy'
      );

      if (eligible.length === 0) {
        throw new Error('No servers meet reliability requirements');
      }

      // Sort by composite score: reliability (70%) + speed (30%)
      eligible.sort((a, b) => {
        const scoreA = (a.reliability_score * 0.7) +
                      ((1000 - a.avg_response_time) / 1000 * 100 * 0.3);
        const scoreB = (b.reliability_score * 0.7) +
                      ((1000 - b.avg_response_time) / 1000 * 100 * 0.3);
        return scoreB - scoreA;
      });

      return eligible[0];
    } catch (error) {
      console.error('Reliability check failed:', error.message);
      // Fallback: return first server
      return { server_id: serverIds[0] };
    }
  }

  async getServerHealth(serverId) {
    const response = await axios.get(
      `${this.baseUrl}/reliability/${serverId}`,
      {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      }
    );
    return response.data;
  }
}

Step 4: Use in Your OpenClaw Agent

Integrate the selector into your agent's server selection logic:

agent.js

import { Agent } from 'openclaw';
import { ReliabilitySelector } from './reliability-selector.js';

const selector = new ReliabilitySelector(process.env.MCPULSE_API_KEY);

const agent = new Agent({
  name: 'WeatherAssistant',
  description: 'Provides weather information using reliable MCP servers',

  // Define available servers
  mcpServers: {
    weatherApi1: 'weather-server-id-1',
    weatherApi2: 'weather-server-id-2',
    weatherApi3: 'weather-server-id-3'
  },

  // Custom server selection before each task
  async selectServer(task) {
    const serverIds = Object.values(this.mcpServers);

    // Let MCPulse choose the most reliable server
    const best = await selector.selectBestServer(serverIds, {
      minReliability: 95.0,
      maxLatency: 500,
      window: '24h'
    });

    console.log(
      `Selected ${best.name} (${best.reliability_score}% reliable, ` +
      `${best.avg_response_time}ms avg latency)`
    );

    return best.server_id;
  },

  async execute(task) {
    // Select best server for this execution
    const serverId = await this.selectServer(task);

    // Call the selected server's tool
    const result = await this.callTool(serverId, 'get_weather', {
      location: task.location
    });

    return result;
  }
});

// Run the agent
agent.start();

Advanced: Failover & Retry Logic

Build resilient agents with automatic failover to backup servers:

export class ResilientAgent extends Agent {
  constructor(config) {
    super(config);
    this.selector = new ReliabilitySelector(config.apiKey);
  }

  async executeWithFailover(task, maxRetries = 3) {
    const serverIds = Object.values(this.mcpServers);

    // Get ranked list of servers
    const ranked = await this.selector.selectBestServer(serverIds);

    for (let i = 0; i < Math.min(maxRetries, serverIds.length); i++) {
      const serverId = serverIds[i];

      try {
        const result = await this.callTool(
          serverId,
          task.tool,
          task.params
        );

        // Success! Log and return
        console.log(`✓ ${serverId} succeeded on attempt ${i + 1}`);
        return result;
      } catch (error) {
        console.warn(
          `✗ ${serverId} failed (attempt ${i + 1}): ${error.message}`
        );

        // Try next server if available
        if (i < serverIds.length - 1) {
          console.log(`→ Failing over to ${serverIds[i + 1]}...`);
          await new Promise(r => setTimeout(r, 1000)); // Brief delay
        }
      }
    }

    throw new Error('All servers failed after retries');
  }
}

Step 6: Monitor Agent-Level Metrics

Track which servers your agents prefer over time:

export class MetricsCollector {
  constructor() {
    this.selections = {};
    this.successes = {};
    this.failures = {};
  }

  recordSelection(serverId) {
    this.selections[serverId] = (this.selections[serverId] || 0) + 1;
  }

  recordSuccess(serverId) {
    this.successes[serverId] = (this.successes[serverId] || 0) + 1;
  }

  recordFailure(serverId) {
    this.failures[serverId] = (this.failures[serverId] || 0) + 1;
  }

  getReport() {
    const report = [];

    for (const serverId in this.selections) {
      const total = this.selections[serverId];
      const success = this.successes[serverId] || 0;
      const failure = this.failures[serverId] || 0;

      report.push({
        serverId,
        selections: total,
        successRate: (success / total * 100).toFixed(1) + '%',
        failures: failure
      });
    }

    return report.sort((a, b) => b.selections - a.selections);
  }
}

// Usage in agent:
const metrics = new MetricsCollector();

async function executeTask(task) {
  const serverId = await selector.selectBestServer(serverIds);
  metrics.recordSelection(serverId);

  try {
    const result = await callTool(serverId, task);
    metrics.recordSuccess(serverId);
    return result;
  } catch (error) {
    metrics.recordFailure(serverId);
    throw error;
  }
}

// Periodic reporting
setInterval(() => {
  console.table(metrics.getReport());
}, 3600000); // Every hour

Expected Results

After integration, you should see:

Troubleshooting

Example Use Cases

Full API Reference

For complete API documentation including all endpoints, authentication, rate limits, and response schemas:

Other Integration Guides