---
name: mcp-delegation
description: "Delegating tasks to OpenClaw/FRIDAY via MCP (Model Context Protocol). Sets up MCP server connection, discovers tools, and sends tasks."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [MCP, Delegation, OpenClaw, FRIDAY, Agent-Coordination]
---

# MCP Delegation to OpenClaw (FRIDAY)

Use this skill when delegating tasks to OpenClaw/FRIDAY via the MCP protocol.

## Prerequisites

- OpenClaw (FRIDAY) must be running (check: `ps aux | grep openclaw`)
- MCP server configured in `~/.hermes/config.yaml`
- Gateway token in `~/.openclaw/gateway_token.txt`

## Configuration

In `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  openclaw:
    command: "openclaw"
    args: ["mcp", "serve", "--token-file", "/home/agent/.openclaw/gateway_token.txt"]
    timeout: 120
    connect_timeout: 60
```

## Available Tools (9 total)

| Tool | Description |
|------|-------------|
| `conversations_list` | List OpenClaw channel-backed conversations |
| `conversation_get` | Get one conversation by session key |
| `messages_read` | Read recent messages for a conversation |
| `attachments_fetch` | List non-text attachments for a message |
| `events_poll` | Poll queued conversation events |
| `events_wait` | Wait for next queued event |
| `messages_send` | Send a message back through the conversation |
| `permissions_list_open` | List open exec/plugin approval requests |
| `permissions_respond` | Allow/deny pending approval requests |

## Workflow

### Primary Method: MCP via `messages_send`

1. **Verify MCP connection:** `hermes mcp list` → should show `openclaw` as enabled
2. **Test connection:** `hermes mcp test openclaw` → should show "Connected" and "Tools discovered: 9"
3. **Discover conversations:** `conversations_list(limit=10)` → find the active session key (e.g., `agent:main:main`)
4. **Send task:** Use `messages_send(session_key="agent:main:main", text="<task>")`
5. **Monitor progress:** Use `events_poll` or `events_wait(timeout_ms=120000)` to check for FRIDAY's activity
6. **Read results:** `messages_read(session_key="agent:main:main")` → check for FRIDAY's completed response

### Secondary Method: CLI Delegation

If MCP messaging doesn't work:
1. `openclaw agent -m "<task>" --agent main` (agent name is "main", NOT "friday")
2. **CRITICAL:** Use `-m` flag, NOT `--to telegram:...` — der `--to` Parameter funktioniert NICHT und führt zu Timeouts
3. Note: CLI may time out after 60-120s even if FRIDAY is processing — don't assume failure
- **Shell quoting:** Avoid single quotes inside the prompt string — use double quotes for the outer shell and avoid nested quotes. Simple prompts work best.
- **Gateway restart instability:** After `openclaw gateway restart` or `openclaw gateway start`, the CLI agent command may hang. Run `openclaw sessions cleanup` then wait 3s before retrying.
- **Health data export:** FRIDAY manages health data at `~/Gesundheit/`. Use `openclaw agent -m "Exportiere ~/Gesundheit/ nach ~/.hermes/assets/Gesundheit/" --agent main` to copy data. FRIDAY's database is typically intact — verify before assuming data loss.
- **Health data management:** FRIDAY's health database uses different column names (`parameter_name` not `parameter`, `ermittlung_datum` not `datum`, no reference ranges). When querying FRIDAY data, adapt SQL queries accordingly. All health data is now managed by JARVIS — FRIDAY delegation for health tasks is deprecated.
6. **Verify gateway health first:** `curl -s http://127.0.0.1:18789/health` should return `{"ok":true,"status":"live"}`. If not, start gateway first.

## Pitfalls

- **Agent name is "main", not "friday":** The OpenClaw agent is configured as "main" in the agent directory (`~/.openclaw/agents/main/`). Using `--agent friday` will fail.
- **CLI timeout ≠ failure:** The `openclaw agent --agent main --message` command often times out after 60-120s even when FRIDAY is actively processing. Always verify via MCP events/messages instead of trusting CLI output.
- **FRIDAY may not respond immediately:** After sending a task, FRIDAY may take several minutes to complete research. Use `events_wait` with 60-120s timeout to poll for activity.
- **MCP tools not directly callable:** MCP tools are only available in the gateway context, not via direct terminal calls.
- **Session routing:** Always use `conversations_list` first to find the correct `session_key` before sending messages.
- **Gateway crashes:** If the gateway crashes during MCP operations, restart it and re-verify the MCP connection.
- **Token file security:** Always use `--token-file` instead of `--token` to avoid exposing the token in process listings.
- **Large message outputs:** `messages_read` can return very large outputs (100KB+). Use `offset` and `limit` parameters to read specific sections.
- **Gateway version mismatch:** If `openclaw gateway start` reports "service was installed by [older version]", the systemd service definition needs repair. `openclaw gateway start` auto-repairs this.
- **ACP scope approval:** `openclaw acp client` may fail with "scope upgrade pending approval". Check `openclaw approvals get` for pending requests.
- **Gateway port:** Default gateway port is 18789. Verify with `openclaw gateway status`.

## Related Skills

- `hermes-agent` — Configure Hermes Agent itself
- **ACP scope approval:** `openclaw acp client` may fail with "scope upgrade pending approval". Check `openclaw approvals get` for pending requests.
- **Gateway port:** Default gateway port is 18789. Verify with `openclaw gateway status`.

## Support Files

- `references/mcp-monitoring-patterns.md` — Patterns for monitoring FRIDAY's activity via MCP events and messages
- `references/gateway-troubleshooting.md` — Full diagnostic routine for OpenClaw gateway connectivity issues (step-by-step, error table)
- `references/health-data-export.md` — Workflow for exporting health data from FRIDAY to Hermes assets
- `references/gateway-diagnostic.md` — Step-by-step gateway diagnostic routine with error table