​

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_..."
      }
    }
  ]
}

​

Agent Plugins 1.0.0 Standard Plugins

​

Import a bundle

1. Go to Settings > Skills and open the plugin manager
2. Import a standard Agent Plugins bundle (.zip or directory)
3. Myrm parses the manifest, persists the bundled file tree, and registers the plugin’s MCP servers automatically

​

Manage plugin MCP servers (enabled state)

• Runtime filtering — Only enabled servers are loaded during tool discovery. A disabled (or broken) server never enters the agent’s tool set, so one bad server cannot take down the rest of the plugin or block agent startup.
• Per-server control — Enable one server and leave another off, and flip any server on/off at any time without re-importing the plugin.

​

Runtime: PLUGIN_ROOT / PLUGIN_DATA (spec §9)

• PLUGIN_ROOT — the plugin’s install directory (where bundled executables live)
• PLUGIN_DATA — the plugin’s persistent data directory, which survives updates

import os

root = os.environ["PLUGIN_ROOT"]
data = os.environ["PLUGIN_DATA"]

​

Uninstall

​

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

​

OpenAPI Bridge (Connect Any REST API)

​

How It Works

1. Add a service — provide the OpenAPI spec URL (or Swagger 2.0 doc)
2. Auto tool generation — every endpoint becomes an agent tool with a complete, LLM-readable parameter schema
3. Connect & use — the agent calls your API with correct types, correct routing, and lossless numeric precision

​

Built-in Guarantees

​

Why This Matters

​

Connection Management

​

Persistent Sessions

​

Stateless HTTP & Cloud Load Balancing

• Round-robin load balancing works out of the box with no session affinity required
• Protocol auto-negotiation via server/discover probe detects server capabilities automatically
• Routing headers (Mcp-Method, Mcp-Name, MCP-Protocol-Version) are injected on every request, enabling intelligent request routing at the gateway layer
• Local/desktop sessions continue to use persistent warm connections for optimal performance (best of both worlds)

​

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

​

Connection Reliability (Real Protocol Verification)

• Zero leak on failure paths — every exit path (connect failure, reconnect failure, clean shutdown) releases the transport HTTP client, so memory stays flat across hours of work
• Self-heal regression — a crashed server is rebuilt in place and keeps serving, with the same resource safety on fresh connections
• Full-suite verification — 720 MCP tests passing, 94.3% coverage

​

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

​

MCP Server Elicitation (User Confirmation)

• The server’s confirmation message
• A 60-second countdown timer
• Approve / Reject buttons

​

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. Optional: Expose Desktop Control Tools — If the selected agent has Computer Use enabled and the deployment environment supports desktop automation, toggle Expose Desktop Control Tools. This expands the server capabilities from memory-only to full Semantic Desktop Control (SDC).
4. Generate config — One click generates a Bearer token (carrying both agent scope and desktop exposure state) and a ready-to-paste config snippet. The server key dynamically adapts to "myrm" (full capabilities) or "myrm-memory" (memory-only).
5. Paste into your IDE — Copy the snippet into your IDE’s MCP settings file.
6. Done — Your external agent now has scoped access to Myrm’s memory and optionally desktop control.

​

Exposed Tools

​

Memory Tools (Standard)

​

Semantic Desktop Control Tools (When Desktop Exposure Enabled)

​

Security & Scope Isolation

• Bearer Token authentication — Each connector gets a unique myrm_mcp_* token scoped to a specific Agent Profile and desktop capability flag.
• Request-Level ContextVar Scoping — Desktop sessions and memory managers are bound per request context (set_request_desktop_session and set_request_memory_manager). External agents cannot access desktop tools if the token or agent configuration does not permit it.
• Per-agent memory isolation — External tools only access the bound agent’s memory and shared contexts, not other agents’ data.
• Dynamic Tool Masking — If desktop exposure is disabled, desktop tools are omitted from the MCP tools/list response for that request.
• One-click revoke — Instantly invalidate a connector’s access without affecting others.
• Stateless HTTP transport — Each request is self-contained (no Mcp-Session-Id tracking needed); works over the network with any MCP-compatible client.
• Doctor health check — Verify connectivity from the GUI at any time, supporting both myrm and myrm-memory server declarations.

​

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 (source: myrm-control-plane/clients/myrm-tunnel-agent/)
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