wmj/agent-configs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7289ebb73eee448664b2a0d15c10e0368cdd1aa3
agent-configs/mcp-integration-guide.md
T
wmj 9381ee0fe5 Add comprehensive MCP integration guide for AI agents 
Full registry of all 15 MCP servers with transport, auth, tool counts,
use cases, config patterns, pitfalls, and quick-start decision tree.
2026-08-09 11:18:51 +08:00

17 KiB
Raw Blame History

MCP Integration Guide for AI Agents

Purpose: This document is a full prompt/guide for any AI agent (Hermes, Claude Code, OpenCode, Codex, OpenClaude, etc.) to understand the Model Context Protocol (MCP) infrastructure at FalahOS and how to connect to and use every available MCP server.

What is MCP?

MCP (Model Context Protocol) is a standard that allows AI agents to discover and invoke tools from external servers. Instead of hardcoding tool definitions, an agent can query an MCP server for its available tools and their schemas, then call them dynamically.

This setup hosts 15 MCP servers across the FalahOS infrastructure, giving agents access to:

  • Geopolitical intelligence (63 tools)
  • Social media publishing (16 tools)
  • Codebase knowledge graphs
  • Financial data & analytics
  • Remote coding agents (Pi, JCode, CrewAI, OpenClaude)
  • Browser automation (HeadlessX, OpenHands)
  • Multi-agent gateway (OpenClaw)
  • 500+ app integrations (Composio)

Network Map

┌─────────────────────────────────────────────────────────────┐
│                    MacBook Air (THIS MACHINE)               │
│  ┌─────┐ ┌──────┐ ┌────────┐ ┌──────┐ ┌───────┐           │
│  │ Pi  │ │JCode │ │CrewAI  │ │Graph │ │Fincept│           │
│  │stdio│ │stdio │ │stdio   │ │:8089 │ │stdio  │           │
│  └─────┘ └──────┘ └────────┘ └──────┘ └───────┘           │
└─────────────────────────────────────────────────────────────┘
                        │ LAN
┌─────────────────────────────────────────────────────────────┐
│                    Mac Mini (192.168.0.10)                  │
│  ┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐         │
│  │Odysseus│ │OpenClaw  │ │HeadlessX│ │Mac-Mini  │         │
│  │:7100   │ │:4500     │ │:8000    │ │Bridge:5001│         │
│  └────────┘ └──────────┘ └─────────┘ └──────────┘         │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    MacBook Pro (192.168.0.27)               │
│  ┌───────────┐ ┌───────────┐                               │
│  │OpenHands  │ │MBP Bridge │                               │
│  │:3000      │ │:5002      │                               │
│  └───────────┘ └───────────┘                               │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│             Synology DSM7 (192.168.0.30)                    │
│  ┌───────────┐                                              │
│  │OpenClaude │                                              │
│  │Docker:4501│                                              │
│  └───────────┘                                              │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    Remote / Cloud                           │
│  ┌──────────┐ ┌───────────┐                                 │
│  │WorldMon  │ │Publora    │                                 │
│  │SaaS      │ │SaaS       │                                 │
│  └──────────┘ └───────────┘                                 │
└─────────────────────────────────────────────────────────────┘

Complete MCP Server Registry

🧠 Intelligence & Research

1. WorldMonitor (worldmonitor)

Property Value
Transport HTTP/SSE (SaaS)
URL https://worldmonitor.app/mcp
Tools 63
Auth Bearer token

Tool Categories:

  • Geopolitical analysis & situation briefings
  • Real-time market data (equities, commodities, gold)
  • Conflict/event tracking (UCDP, Iran)
  • News intelligence (GDELT, AI-classified)
  • Prediction markets & forecasts
  • Cyber threat intel (URLhaus, CVE tracking)
  • Maritime activity & chokepoint status
  • Climate & environmental data
  • Sanctions screening (OFAC SDN)
  • Military posture & escalation scores
  • Flight search & pricing
  • Company intelligence (SEC EDGAR)
  • Supply chain & tariff trends
  • Natural disasters (USGS earthquakes, NASA FIRMS wildfires)

When to use it: Geopolitical risk assessment, market research, country briefings, threat monitoring, competitive intel, travel planning.

2. Graphify (graphify)

Property Value
Transport HTTP (localhost)
URL http://127.0.0.1:8089/mcp
Tools Codebase knowledge graph

What it does: AST-based codebase knowledge graph. Use it to navigate any project's architecture, find god nodes, community structure, and file relationships. Before answering architecture questions, always read GRAPH_REPORT.md — it has the god nodes and community structure pre-computed.

When to use it: Codebase understanding, architecture questions, dependency analysis.

3. Fincept (fincept)

Property Value
Transport Stdio (local Python)
Command python3 /Users/wanjauhari24/...
Tools 6

Tool Categories:

  • 230+ financial data connectors (Yahoo, FRED, IMF, AKShare, EIA)
  • Financial analysis (income, balance, cashflow, DCF)
  • Technical indicators
  • Quantitative analytics
  • AI agents for terminal analysis

When to use it: Stock research, economic indicator lookup, financial modeling, ETF analysis.

📱 Social Media Publishing

4. Publora (publora)

Property Value
Transport HTTP/SSE (SaaS)
URL https://mcp.publora.com
Tools 16
Auth Authorization: Bearer sk_mrs...1674

Tool Categories:

  • Create, update, schedule posts
  • Delete post groups
  • Upload media (presigned S3 URL → complete)
  • LinkedIn: comment, react, reshare
  • List connected accounts (Twitter, TikTok, YouTube, LinkedIn, Instagram)
  • List/manage scheduled posts

When to use it: Social media content scheduling, cross-platform posting, LinkedIn engagement.

🤖 Remote Agent Bridges

5. Mac Mini Bridge (mac-mini)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.10:5001
Auth Bearer token

Bridge to agents running on Mac Mini (192.168.0.10). Includes access to tools from Odysseus, OpenClaw, HeadlessX, and other Mac Mini services.

6. MacBook Pro Bridge (macbook-pro)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.27:5002
Auth Bearer token

Bridge to agents running on MacBook Pro (192.168.0.27). Includes OpenHands and other MBP services.

7. OpenClaw Gateway (openclaw)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.10:4500
Tools Gateway tools

OpenClaw is a multi-agent gateway. Tools include:

  • Gateway status
  • List agents
  • List channels
  • Send messages
  • Switch models

When to use it: Managing OpenClaw agent configurations, sending messages through OpenClaw channels.

8. Odysseus (odysseus)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.10:7100
Tools 67+

Odysseus is a FastAPI app with session-based auth. Tools cover:

  • Web search
  • Bash/terminal execution
  • Email/file operations
  • Research & memory
  • Knowledge retrieval

9. OpenHands (openhands)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.27:3000
Tools Browser automation

AI software development agent (by All-Hands-AI). Runs in Docker on MBP.

10. HeadlessX (headlessx)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.10:8000/mcp
Tools Browser automation

Self-hosted browser automation platform. Can control browsers programmatically.

11. OpenClaude (openclaude)

Property Value
Transport HTTP (LAN)
URL http://192.168.0.30:4501
Tools CLI bridge

OpenClaude CLI (@gitlawb/openclaude) running in a Docker container on Synology DSM7. The open-source Claude Code CLI bridge. Works with any OpenAI-compatible backend.

⚡ Local Coding Agents (Stdio)

12. Pi (pi)

Property Value
Transport Stdio (local)
Command node /Users/wanjauhari24/...

Pi coding agent. Use for delegated coding tasks — features, PRs, code review.

13. JCode (jcode)

Property Value
Transport Stdio (local)
Command node /Users/wanjauhari24/...

JCode agent. Use for delegated coding tasks.

14. CrewAI (crewai)

Property Value
Transport Stdio (local)
Command /Users/wanjauhari24/.venv/...
Tools Multi-agent orchestration

CrewAI multi-agent orchestration. Runs crews of AI agents for complex workflows.

When to use it: Multi-step research → content generation pipelines, complex automation with multiple AI actors.

15. Composio (composio)

Property Value
Transport HTTP (Session-based SaaS)
URL https://backend.composio.dev/tool_router/trs_jyF-kuZ62J-M/mcp
Tools 6 (500+ integrations)

Tool Categories:

  • Get tool schemas by slug
  • Manage connections to 500+ apps (Slack, Gmail, Notion, GitHub, etc.)
  • Multi-execute tools in parallel
  • Remote bash sandbox
  • Remote workbench for bulk executions
  • Search tools

When to use it: Connecting to third-party apps (Slack, GitHub, Gmail, Notion, etc.), remote file operations, bulk tool execution.

Configuration Pattern

For Hermes Agent, MCP servers are configured in ~/.hermes/config.yaml:

HTTP/SSE Transport (SaaS)

mcp_servers:
  service-name:
    url: "https://mcp.example.com"
    headers:
      Authorization: "Bearer YOUR_TOKEN"
    timeout: 60
    tools: "{}"    # Discover all tools

HTTP Transport (LAN/localhost)

mcp_servers:
  service-name:
    url: "http://192.168.0.X:PORT[/path]"
    tools: "{}"

Stdio Transport (local process)

mcp_servers:
  service-name:
    command: "/path/to/binary"
    args: ["arg1", "arg2"]
    env:
      API_KEY: "value"
    timeout: 120

Verification

List all MCP servers and status

hermes mcp list

Expected output: All servers show ✓ enabled.

Test a specific MCP server with curl

# Initialize
curl -s -X POST http://HOST:PORT/ \
  -H "Content-Type: application/json" \
  -d '{"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

# List tools
curl -s -X POST http://HOST:PORT/ \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list","id":1}'

Note: hermes mcp test is broken for HTTP transport (missing streamable_http module). Use hermes mcp list + curl instead.

Reload MCP after config changes

/reload-mcp    # Hot reload (preferred)
/reset         # Full session restart

Known Pitfalls & Workarounds

hermes mcp test broken

The test command fails with streamable_http is not available for ALL HTTP MCP servers. This is a known limitation. Servers still work during normal agent operation. Use hermes mcp list (showing ✓ enabled) or direct curl to verify.

Config YAML nesting issue

hermes config set mcp_servers.X.Y key:value creates a flat key, not nested YAML. Fix manually:

import yaml
with open('~/.hermes/config.yaml') as f:
    cfg = yaml.safe_load(f)
cfg['mcp_servers']['new-server'] = {'url': 'http://host:port', 'tools': '{}'}
with open('~/.hermes/config.yaml', 'w') as f:
    yaml.dump(cfg, f, default_flow_style=False)

Stdio MCP servers with dependent backends

Some stdio servers (like OpenClaw MCP) are proxies to a daemon that must be running first. If you see connect ECONNREFUSED 127.0.0.1:PORT, the backend isn't up. Start it first:

nohup openclaw gateway --port 18789 > /tmp/gateway.log 2>&1 &
# Verify: curl -s http://localhost:18789/health

macOS Firewall blocks Node.js MCP servers

If Node.js MCP bridges get "Empty reply from server" from LAN clients, the Application Firewall is blocking them. Workaround: run a Python TCP relay on a different port, or use Docker (Colima auto-forwards ports through SSH multiplexer which bypasses the firewall).

nvm PATH not available via SSH

Non-interactive SSH sessions don't have node on PATH. Use full paths:

# Homebrew: /usr/local/bin/node
# nvm: ~/.nvm/versions/node/v22.23.1/bin/node
# fnm: ~/.local/share/fnm/node-versions/v20.20.2/installation/bin/node

Adding New MCP Servers

Option A: HTTP API Bridge

Create a lightweight Node.js server (zero npm deps) that proxies MCP calls to an HTTP API.

Template:

const http = require('http');
const PORT = 4500;
const TOOLS = [{ name, description, inputSchema }];

http.createServer((req, res) => {
  let body = '';
  req.on('data', c => body += c);
  req.on('end', () => {
    const { method, params, id } = JSON.parse(body);
    handleMCP(method, params, id).then(result => {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(result));
    });
  });
}).listen(PORT, '0.0.0.0');

Option B: CLI Tool Bridge

Wrap a CLI tool (like OpenClaude, Claude Code) as an MCP server:

const { execSync } = require('child_process');
// ... same HTTP server, but handleToolCall runs execSync

Option C: Python FastMCP (simplest, when Python available)

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """Description for the LLM."""
    return f"Result: {param}"

mcp.run(transport="stdio")

Register in Hermes:

mcp_servers:
  my-server:
    command: "/path/to/python3"
    args: ["/path/to/server.py"]
    timeout: 120

Infrastructure Summary

Machine IP Services
MacBook Air (this) localhost Pi, JCode, CrewAI, Graphify, Fincept (stdio)
Mac Mini 192.168.0.10 Odysseus:7100, OpenClaw:4500, HeadlessX:8000, Bridge:5001
MacBook Pro 192.168.0.27 OpenHands:3000, Bridge:5002
Synology DSM7 192.168.0.30 OpenClaude Docker:4501
Cloud/SaaS worldmonitor.app WorldMonitor (63 tools)
Cloud/SaaS mcp.publora.com Publora (16 tools)
Cloud/SaaS backend.composio.dev Composio (500+ integrations)

Quick-Start for AI Agents

When you need a capability, follow this decision tree:

  1. Geopolitical/market intel? → Use worldmonitor tools
  2. Codebase architecture? → Use graphify
  3. Financial data/analysis? → Use fincept
  4. Post to social media? → Use publora tools
  5. Connect to Slack/Gmail/GitHub? → Use composio tools
  6. Need a browser automated? → Use headlessx or openhands
  7. Delegate to other AI agents? → Use pi, jcode, crewai, openclaude
  8. Manage OpenClaw agents/channels? → Use openclaw
  9. Research/search on remote machine? → Use odysseus

All 15 servers are pre-configured and active. Just invoke the tools by name.

Reference in New Issue View Git Blame Copy Permalink