home / mcp / maple mcp server

Maple MCP Server

Unified MCP server for agent observability, safety control, and behavior evolution with observability, guardrails, and learning from anonymized traces.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "alnosarus-copymaple": {
      "url": "http://localhost:3000",
      "headers": {
        "MCP_URL": "http://localhost:3000",
        "MAPLE_API_KEY": "your_long_random_key",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MAPLE_ALLOW_NO_AUTH": "false",
        "OPENCLAW_BRIDGE_URL": "http://localhost:8787",
        "OPENCLAW_BRIDGE_TOKEN": "your_token",
        "MAPLE_FIREWALL_ENABLED": "true",
        "MAPLE_FIREWALL_LOG_DIR": "~/.maple/firewall-logs",
        "MAPLE_LOCK_BRIDGE_TARGET": "true",
        "MAPLE_ALLOW_BRIDGE_OVERRIDE": "false",
        "MAPLE_FIREWALL_CHAT_PRIMARY": "openai",
        "MAPLE_FIREWALL_DEFAULT_ACTION": "deny"
      }
    }
  }
}

Maple is a unified MCP server focused on agent observability, safety control, and behavior evolution. It lets you watch every step, replay risky branches, intervene with guardrails, and learn from anonymized traces to improve safer skills. You interact with Maple through observable sessions, risk assessments, anomaly detection, and a secure firewall until you trust the evolving behavior of your agents.

How to use

You use Maple with an MCP client to observe, control, and improve agent behavior. Start sessions to capture an agent’s actions, replay any step to explore alternatives, and apply guardrails to block or quarantine risky steps. You can run anomaly detection on embeddings, anonymize traces for a shared pool, and generate evolved skill suggestions from community data. When you are ready, build and present narratives for moat, traction, and revenue.

Engage with the system through HTTP API endpoints to monitor health, inspect traces, and query community data. Use the inspector and judge interfaces to view live traces, run guided flows, and inspect firewall context. Use the guided demo controls to perform end-to-end flows without manual JSON input, or run a single stable trace and append agent actions for a repeatable demo.

How to install

Prerequisites: you need Node.js and npm installed on your machine. Ensure you have a recent stable version of Node.js and npm before proceeding.

npm install
npm run dev

Additional content

Environment variables provide configuration for the Maple server, security hardening, and optional AI-enabled firewall chat. You can enable key-based access, configure bridge routing, and tailor the firewall behavior. Here are common environment variables you will encounter and their purposes.

MCP_URL=http://localhost:3000
OPENCLAW_BRIDGE_URL=http://localhost:8787
OPENCLAW_BRIDGE_TOKEN=your_token
MAPLE_API_KEY=your_long_random_key
MAPLE_LOCK_BRIDGE_TARGET=true
MAPLE_ALLOW_NO_AUTH=true  # optional, not recommended for production
MAPLE_ALLOW_BRIDGE_OVERRIDE=true  # optional local override
MAPLE_FIREWALL_ENABLED=true
MAPLE_FIREWALL_DEFAULT_ACTION=allow
MAPLE_FIREWALL_LOG_DIR=~/.maple/firewall-logs
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MAPLE_FIREWALL_CHAT_PRIMARY=openai
MAPLE_FIREWALL_CHAT_OPENAI_MODEL=gpt-4o-mini
MAPLE_FIREWALL_CHAT_TIMEOUT_MS=15000

Security and deployment notes

Maple supports API key authentication and optional bridge lockdown to ensure all bridge traffic uses configured endpoints. The firewall enforces deterministic checks on every trace step, redacts secrets, and quarantines if a deny rule fires. Health checks remain publicly accessible to verify deployment status.

For production deployments, provide explicit MCP URL and bridge credentials. Do not rely on localhost when Maple runs behind a reverse proxy or in a remote environment. If bridge connectivity is unavailable during a demo, you can run with a mock source to keep the UI and guardrails flowing.

Troubleshooting and notes

If you encounter connectivity issues, verify MCP_URL and OPENCLAW_BRIDGE_URL are reachable from your deployment. Check firewall settings and ensure you have proper API keys in place. Use the Judge and Inspector interfaces to verify the trace flow and confirm that guard actions and replays behave as expected.

Available tools

observe_session

Capture and render a session timeline for agent activity to observe behavior step by step.

replay_fork

Create a fork from a specific step and simulate forward to explore alternatives without affecting the original trace.

audit_risk

Analyze traces against risk rules and anomalies, providing a risk dashboard view.

ml_anomaly_report

Produce embedding-based anomaly reports to identify unusual behavior patterns.

guard_action

Apply guardrails to agent actions with allow, block, or pending states and quarantine support.

ingest_session_event

Stream external bridge events into the active trace for real-time observability.

share_trace_anon

Anonymize and publish trace patterns to a shared community pool for collective learning.

suggest_evolved_skills

Generate evolved skill recommendations from shared traces and community data.

yc_app_brief

Build live YC-ready narratives focusing on moat, traction, and revenue.

list_traces

List available traces in the system for inspection.

export_trace

Export trace data for offline analysis or sharing.