wmj/agent-configs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive MCP integration guide for AI agents

Browse Source 
Full registry of all 15 MCP servers with transport, auth, tool counts,
use cases, config patterns, pitfalls, and quick-start decision tree.
This commit is contained in:
Wmj Ismail
2026-08-09 11:18:51 +08:00
parent 5c1e7ce188
commit 9381ee0fe5
1 changed files with 460 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mcp-integration-guide.md
+460
View File
@@ -0,0 +1,460 @@
# 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)
```yaml
mcp_servers:
service-name:
url: "https://mcp.example.com"
headers:
Authorization: "Bearer YOUR_TOKEN"
timeout: 60
tools: "{}" # Discover all tools
```
### HTTP Transport (LAN/localhost)
```yaml
mcp_servers:
service-name:
url: "http://192.168.0.X:PORT[/path]"
tools: "{}"
```
### Stdio Transport (local process)
```yaml
mcp_servers:
service-name:
command: "/path/to/binary"
args: ["arg1", "arg2"]
env:
API_KEY: "value"
timeout: 120
```
---
## Verification
### List all MCP servers and status
```bash
hermes mcp list
```
Expected output: All servers show `✓ enabled`.
### Test a specific MCP server with curl
```bash
# 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
```bash
/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:
```python
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:
```bash
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:
```bash
# 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:**
```javascript
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:
```javascript
const { execSync } = require('child_process');
// ... same HTTP server, but handleToolCall runs execSync
```
### Option C: Python FastMCP (simplest, when Python available)
```python
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:
```yaml
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.