​

MCP Integration

​

What is MCP?

​

Service Catalog (One-Click Connect)

• Pre-configured connection details (command, args, URL)
• Guided credential input with help links to the provider’s token page
• Keyless zero-config support for select services (e.g., Firecrawl free tier — no API key needed)
• Security scan before connecting (SSRF + malicious package detection)
• Bilingual descriptions (English and Chinese)

​

Cloud Storage & File Export

​

Integration Memory (Workspace Sync)

​

How It Works

1. Connect a service via the Service Catalog (e.g., Notion, GitHub, Gmail)
2. Click Sync All in the Integration Memory section
3. The system automatically:
   • Detects the best fetch tool from the MCP server’s catalog
   • Pulls data using incremental sync (detects since/after parameters)
   • Deduplicates by provider::external_id (idempotent re-sync safe)
   • Embeds content into the vector store
   • Builds a tree structure in the knowledge graph
   • Extracts high-value profile traits via MemoryExtractor

​

Key Features

​

Managing Synced Data

• Status overview: See total providers, indexed items, and tree count
• Per-tree controls: Sync or remove individual data trees
• Sync results: View created/updated/skipped/failed counts per provider

​

Adding Custom MCP Servers

​

From the GUI

1. Navigate to Settings > Tools > MCP
2. Click Add Server
3. Enter the server configuration:
   • Name: Display name for the server
   • Command: The command to start the server (e.g., npx @mcp/server-github)
   • Arguments: Command-line arguments
   • Environment Variables: Required environment variables (e.g., API keys)
4. Save — the server starts automatically and its tools become available to agents

​

From Configuration File

{
  "servers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["@mcp/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  ]
}

​

Building Custom MCP Servers (AI-Guided)

​

How to Use

1. Go to Settings > Agent > Skills and enable the mcp-builder skill
2. Start a conversation and describe what you need: “Build an MCP server that connects to Jira for project management”
3. The agent follows a structured 4-phase workflow:

​

Built-in Quality Guarantees

• Security annotations — Read-only operations get readOnlyHint: true (auto-approve), destructive operations get destructiveHint: true (warning badge)
• Error handling — All HTTP calls have timeouts, retries, and actionable error messages
• Pagination — Large result sets are paginated to prevent token explosion
• Environment variables — Secrets are never hardcoded

​

Schema Handling

​

Connection Management

​

Persistent Sessions

​

Execution Timeout Protection

• SDK layer — read_timeout_seconds is passed to the MCP SDK session, preventing hung responses at the transport level
• Wrapper layer — An independent asyncio.timeout wraps the entire execution (including response normalization), catching tools that stall after transport confirms receipt
• Per-server configurable — Each server can set its own connect_timeout (default 15s) and execute_timeout (default 120s, max 300s)
• Graceful degradation — On timeout, a descriptive error string is returned to the LLM (not an exception), allowing the agent to decide next steps
• Auto-retry on enumeration — Tool discovery retries up to 3 times with 300ms backoff on transient failures

​

Error Transparency

• Server-side error pass-through — The original error text from the MCP server is extracted and forwarded to the LLM exactly as reported
• Security sanitization — Credentials are redacted (redact_sensitive_text) and structural framing tokens are stripped (sanitize) to prevent prompt injection via error messages
• Error classification — Errors are categorized (network_blocked, timeout, sandbox_ro, etc.) enabling circuit-breaker patterns and targeted recovery
• Circuit breaker — Terminal errors (e.g. network permanently blocked) are registered; subsequent calls to the same category fail fast without retrying
• Structured diagnostics — Execution phase, tool name, output previews (head + tail truncation), and recovery hints are recorded for debugging
• Frontend display — Errors surface in the UI as structured progress steps with i18n messages, resolution steps, and recovery actions — not just raw text

​

Self-Healing Reconnection

• Bounded backoff — Up to 5 reconnect attempts with exponential backoff (0.5s to 8s cap)
• Budget refresh — A session that ran stable for 60+ seconds earns a fresh retry budget, so an unrelated blip hours later still gets full retries
• In-flight call fails explicitly — The call that hit the break is failed (no silent auto-retry of non-idempotent tools), but subsequent calls succeed on the fresh session
• Proxy stability — The tool objects held by the agent remain identical across reconnects, preserving prompt prefix cache hits

​

Transport-Aware Keepalive

​

Connection Pool

• Singleton per server — One warm connection per config-hash prevents resource leaks
• Loop-aware — Connections rebuild automatically on event-loop change
• TTL recycling — Long-idle connections are closed and recreated on demand
• Last-resort rebuild — The pool only rebuilds a connection when the actor’s internal reconnect budget is fully exhausted

​

CancelledError Protection

​

Metrics

​

Security

​

SSRF Prevention

• Resolved IPs are checked against private ranges (10.x, 172.16-31.x, 192.168.x)
• Localhost and link-local addresses are blocked by default
• URL validation prevents redirect-based SSRF attacks

​

Malicious Package Detection

​

Runtime Prompt Injection Protection

• Server instructions for embedded directives that could hijack agent behavior
• Tool names for deceptive names mimicking built-in tools
• Tool descriptions for injected prompt manipulation patterns

​

Tool Approval

• Read-only tools execute automatically
• Write/destructive tools require user approval (unless in YOLO mode)
• Custom approval policies can be configured per MCP server

​

Per-Tool Filtering

​

How to Use

1. Go to Agent Config (click the agent avatar in chat)
2. Under MCP Servers, each enabled server shows a Tool Filter toggle
3. Expand it to see all available tools with risk annotations
4. Toggle individual tools on/off using checkboxes

​

Risk Annotations

​

Auto-Disable Dangerous Tools

​

Filter Summary

​

Multimodal Tool Results

​

Image Content

• Base64 image data flows through the streaming pipeline and renders in the Tool Image Gallery
• Multiple images per tool result are supported (grid layout with lightbox preview)
• For models that don’t support vision, images are automatically stripped by the media filter — no configuration needed

​

Structured Content

​

Tool Filtering

• Include list — Only specified tools are registered (whitelist)
• Exclude list — Specified tools are hidden (blacklist)
• Per-agent granularity — Different agents can enable different tools from the same MCP server (e.g., a “Code Reviewer” agent sees only read-only GitHub tools, while a “DevOps” agent sees all)
• Configure via the GUI in the Agent Config Panel > MCP > Tool Selection

​

Safety Annotations

​

Default Safe Set

• All readOnlyHint tools are enabled
• Tools with destructiveHint are disabled and flagged with a warning banner (“N destructive tools disabled by default”)
• You can always override the defaults in the Tool Selection GUI

​

Tool Name Isolation

mcp__{server}__{tool}

• Double-underscore delimiters — Unlike single-underscore schemes (which are ambiguous when server names contain underscores), the __ delimiter allows unambiguous parsing back to (server, tool) pairs
• Permission safety — Prefixed names never collide with built-in tool names, preventing accidental permission bypass
• Audit traceability — Every tool invocation log entry clearly shows which MCP server the tool belongs to
• Transparent to users — The GUI always displays the friendly original tool name; prefixing is internal to the engine

​

Dynamic Tool Discovery

• Zero-downtime refresh — The session actor re-fetches the tool list and updates the execution layer without interrupting in-flight calls (serialized through the internal queue, no locks)
• Prompt cache stability — The prompt-facing proxy tools remain frozen; only the internal execution map is updated, so prompt prefix cache hits are never compromised
• Timeout protection — The refresh re-fetch is bounded by the same connect timeout as session initialization, so a hung MCP server cannot deadlock the owner task
• Change logging — Added and removed tools are logged at WARNING level for visibility; no-op refreshes are logged at INFO level
• Transparent to agents — Agents continue using their existing tool references; new tools become callable immediately, removed tools fail explicitly on next invocation

​

Deferred Loading

• Tools are registered but not included in the initial prompt
• When the agent needs a specific capability, the tool is loaded on demand
• This keeps the system prompt compact and cache-friendly

​

Reverse MCP Server (Connect)

​

How It Works

1. Choose your Myrm Agent — Select which Agent Profile the external tool should bind to. The external tool will read/write that agent’s memory space, including any shared contexts bound to it.
2. Choose your IDE — Select from 5 supported MCP clients
3. Generate config — One click generates a Bearer token (carrying the agent scope) and a ready-to-paste config snippet
4. Paste into your IDE — Copy the snippet into your IDE’s MCP settings file
5. Done — Your external agent now has scoped access to the selected Myrm Agent’s memory

​

Exposed Tools

​

Security

• Bearer Token authentication — Each connector gets a unique myrm_mcp_* token scoped to a specific Agent Profile
• Per-agent memory isolation — External tools only access the bound agent’s memory and shared contexts, not other agents’ data
• One-click revoke — Instantly invalidate a connector’s access without affecting others
• HTTP transport — Works over the network (not limited to local stdio)
• Doctor health check — Verify connectivity from the GUI at any time

​

Supported Clients

​

Why This Matters

​

Enterprise Org MCP (Cloud SaaS)

1. Navigate to Settings → Enterprise → Org MCP (owner/admin only)
2. Add HTTP/SSE MCP servers with name, URL, and optional auth headers
3. Changes are pushed automatically to every member sandbox via the control plane
4. If a sandbox is sleeping, delivery is queued and replayed on wake (up to 3 retries)
5. Employees see org-managed MCP servers as read-only under Settings → MCP — they cannot edit or remove IT-managed entries
6. stdio MCP is blocked in cloud sandboxes for security (local process servers are not allowed)

​

Troubleshooting

​

Server Won’t Start

1. Check the command path is correct and accessible
2. Verify required environment variables are set
3. Check server logs in Settings > Tools > MCP > Logs

​

Tools Not Appearing

1. Wait 5-10 seconds after server start for tool discovery
2. Click Refresh in the MCP settings panel
3. Check if the server’s tool list response is valid JSON Schema

​

Connection Drops

• Network connectivity to the MCP server
• Server process health (may need restart)
• Resource limits (file descriptors, memory)

​

Local Editor MCP Probe Diagnostics

• If shouldBlockConnect=true, Myrm stops the connect chain immediately (no scan/verify fan-out), reducing noisy failures.
• The UI maps reasonCode to localized operator-facing messages, so infra and app teams can triage from the same signal.
• recommendedMode is actionable in one click: start_local_editor_mcp / verify_local_network_and_editor trigger a probe retry and auto-continue connect on success, while local_or_tauri opens local deployment guidance directly.
• Compared to competitors that surface generic network errors only, Myrm provides machine-readable diagnostics that can be automated in CI checks and onboarding scripts.

​

Why this migration path is smoother than CLI-first flows

• In-product remediation, not terminal handoff: Operators can recover from local MCP failures inside the same Connect dialog. In contrast, OpenClaw’s MCP page is explicitly an operator view and asks users to run terminal probe commands (openclaw mcp doctor --probe) for live proof.
• Actionable contract instead of boolean pass/fail: Myrm returns reasonCode + recommendedMode + shouldBlockConnect, so frontend behavior is deterministic (block fan-out, show localized cause, and provide one-click action). Hermes’ /api/mcp/servers/{name}/test style response is primarily ok/error/tools, which is useful for diagnostics but less expressive for guided onboarding UX.
• Noise reduction by design: When the probe says block, Myrm stops scan/verify fan-out immediately. This prevents avoidable downstream failures and reduces “retry blindly” behavior during migration from legacy MCP setups.
• Unknown-failure safety: Unexpected probe failures return a sanitized operator message while server logs retain debuggable details, avoiding accidental leak of low-level exception internals to end users.

​

OAuth Token Expiry

1. Instant detection — When a tool call receives an HTTP 401 from the MCP server, the error is caught immediately (no need to exhaust reconnect retries first)
2. User notification — A toast appears: ” requires re-authorization” with a one-click “Reauthorize” button
3. One-click fix — Click the button to jump directly to Settings → Extensions where you can re-authorize with OAuth
4. Token hot-update — After re-authorization, active sessions automatically pick up the fresh token via the connection pool — no page reload or session rebuild needed. The very next tool call uses the new credentials

​

Enterprise Private MCP Tunnel (Cloud Only)

​

How It Works

1. Deploy tunnel-agent — Install the open-source myrm-tunnel-agent on any machine inside your private network
2. Register tunnel — The agent registers with the control plane and receives a secure token
3. Outbound-only connection — The tunnel-agent initiates an outbound long-poll connection to the control plane relay — no inbound ports required
4. Transparent relay — When your cloud Myrm agent calls an internal MCP tool, the request is relayed through the tunnel to the internal MCP server and the response is returned transparently

​

Security

​

Architecture

┌─ Enterprise Network ──────────┐     ┌─ Myrm Cloud ─────────────────┐
│                                │     │                               │
│  Internal MCP Server           │     │  CP Tunnel Relay (in-memory)  │
│       ↑                        │     │       ↑                       │
│  myrm-tunnel-agent ─── outbound ───→ │  org MCP → streamable_http    │
│  (open-source)         HTTPS   │     │       ↓                       │
│                                │     │  Cloud Agent (sandbox)        │
└────────────────────────────────┘     └───────────────────────────────┘

​

Setting Up

1. Register a tunnel in the org admin panel (Settings → Organization → MCP → Add Tunnel)
2. Deploy myrm-tunnel-agent with the provided token and internal MCP server endpoint
3. The tunnel appears as an org-level MCP server — assign it to agents like any other MCP server

​

Enterprise Managed Auth — IdP Group-Based MCP Access (Cloud Only)

​

How It Works

1. OIDC groups claim — When a user logs in via SSO, Myrm extracts the groups claim from the OIDC response and stores it on the user’s org membership record
2. Per-MCP group whitelist — Org admins configure an optional acl_groups list on each org MCP server (empty = visible to all members)
3. Automatic filtering — When MCP configurations are pushed to a user’s sandbox, only servers where the user’s IdP groups intersect with the server’s ACL groups are included
4. Login refresh — Group memberships are automatically refreshed on every OIDC login — no manual sync needed

​

Configuring Group-Based Access

1. Navigate to Settings → Organization → MCP Servers
2. When creating or editing an MCP server, enter IdP group names in the Access Groups field (comma-separated)
3. Leave the field empty to make the server visible to all organization members
4. Members whose IdP groups match at least one configured group will see and use the server

​

Offboarding

​

Security