ClawDeFi MCP Gateway

Internal MCP-facing gateway service that translates tool-style calls into clawdefi-core API requests.

Current Mode

• Runs as an internal HTTP gateway for tool calls.
• Keeps MCP auth token checks (x-mcp-token) at gateway boundary.
• Uses service token (x-service-token) when calling clawdefi-core.
• Derives a stable internal x-agent-id server-side from caller IP for core rate-limit isolation.
• x-agent-id is never accepted from MCP clients directly.
• Emits per-tool analytics events to core internal ingestion API.
• Exposes health and readiness endpoints for orchestration.

Available Tool Endpoints

Implemented:

• POST /tools/get_protocol_profile
• POST /tools/list_protocols
• POST /tools/query_chain_registry
• POST /tools/evaluate_risk
• POST /tools/get_action_spec
• POST /tools/get_integration_endpoint
• POST /tools/build_unwind_plan
• POST /tools/list_providers_by_category
• POST /tools/simulate_transaction
• POST /tools/create_wallet (supports signer import flows; walletAddress=auto|generate|generated|new creates a key-backed wallet inside signer boundary; plugin boundary rejects raw privateKey inputs and only forwards sanitized payloads)
• POST /tools/list_wallets
• POST /tools/rotate_wallet_secret
• POST /tools/get_policy
• POST /tools/update_policy
• POST /tools/sign_intent
• POST /tools/perps_fetch_open_positions (adapter-backed read path; protocolSlug=avantis implemented)
• POST /tools/perps_fetch_pending_orders (adapter-backed read path; protocolSlug=avantis implemented)
• POST /tools/perps_fetch_market_state (adapter-backed read path; protocolSlug=avantis implemented)
• POST /tools/perps_build_open_order (canonical unsigned intent builder; can auto-hydrate transactionRequest via core action-spec tx-builder endpoint)
• POST /tools/perps_build_close_order (canonical unsigned intent builder; can auto-hydrate transactionRequest via core action-spec tx-builder endpoint)
• POST /tools/perps_build_cancel_order (canonical unsigned intent builder; can auto-hydrate transactionRequest via core action-spec tx-builder endpoint)
• POST /tools/perps_set_risk_orders (canonical unsigned intent builder; can auto-hydrate transactionRequest via core action-spec tx-builder endpoint)
• POST /tools/perps_simulate_intent (intent validation + optional risk/market checks; emits simulationToken)
• POST /tools/perps_execute_intent (requires simulationToken; enforces signer-runtime signing path before submit)
• POST /tools/subscribe_alerts
• POST /tools/poll_alert_events
• POST /tools/close_alert_subscription

MVP Limitations

• subscribe_alerts is poll-mode MVP. WebSocket/SSE transport is not shipped yet.
• build_unwind_plan is position-aware only when a matching wallet-scoped position snapshot exists in core.
• If no snapshot is available, unwind planning degrades to curated fallback with explicit warnings.

Required Environment

• CORE_API_BASE_URL
• INTERNAL_SERVICE_TOKEN
• MCP_AUTH_TOKEN
• MCP_TRUST_PROXY (0 by default; set to trusted proxy CIDRs/hops if MCP is behind a reverse proxy)
• MCP_ANALYTICS_ENABLED (true by default; set false in integration tests to avoid external analytics noise)
• MCP_CONTRACT_STRICT (true by default; strict envelope mode)
• SIGNER_RUNTIME_BASE_URL (default http://127.0.0.1:8091)
• SIGNER_RUNTIME_MODE (http for the intended local signer-runtime path; embedded allowed for local/test)
• SIGNER_RUNTIME_AUTH_TOKEN (dedicated auth token for MCP -> signer-runtime calls)
• AVANTIS_CORE_API_BASE_URL (default https://core.avantisfi.com)
• AVANTIS_SOCKET_API_URL (default https://socket-api-pub.avantisfi.com/socket-api/v1/data)
• AVANTIS_TIMEOUT_MS (default 10000)
• PERPS_SIMULATION_TTL_MS (default 300000; required simulate→execute artifact window)
• PERPS_SIGNED_ONLY_FALLBACK_ENABLED (default false; production open/close execute is fail-closed without transactionRequest unless this explicit override is true)
• SIGNER_KEYSTORE_BACKEND (file_encrypted default; memory only for local/test)
• SIGNER_MASTER_KEY (32-byte base64/hex master key for encrypted keystore at rest)
• SIGNER_MASTER_KEY_NEXT (optional next master key used for rotation workflow)
• SIGNER_KEYSTORE_DIR (encrypted secret file directory)
• SIGNER_STATE_PATH (persisted signer runtime metadata/policy state)
• SIGNER_WALLETS_JSON_PATH (default ./state/wallets.json; signer-runtime projection file for multi-wallet public metadata)
• SIGNER_AUDIT_LOG_PATH (default ./state/signer-audit.jsonl; durable JSONL audit log for policy updates/sign attempts/keystore events)

Security Notes

• Keep this service private by default.
• Do not expose MCP gateway publicly without additional controls (allowlist, mTLS, WAF).
• Signing is mediated via dedicated signer-runtime service boundary.
• Use a dedicated SIGNER_RUNTIME_AUTH_TOKEN (do not reuse INTERNAL_SERVICE_TOKEN).
• Keep signer seed material in signer-runtime only (MCP_SIGNER_SEED), not MCP.
• Use encrypted keystore backend in non-test deployments (SIGNER_KEYSTORE_BACKEND=file_encrypted) and rotate SIGNER_MASTER_KEY operationally.
• If deployed behind a proxy, set MCP_TRUST_PROXY correctly or per-client IP-derived rate-limit identity may collapse to proxy IP.

Perps Preflight / Release-Gate Runbook

• Detailed checklist: docs/perps-preflight-runbook.md
• Automated preflight script: scripts/perps-preflight.sh

Example:

MCP_URL="http://127.0.0.1:8090" \
MCP_TOKEN="${MCP_AUTH_TOKEN}" \
PROTOCOL_SLUG="avantis" \
CHAIN_SLUG="base-mainnet" \
bash scripts/perps-preflight.sh

The preflight checks:

• MCP health/readiness
• broadcast chain/rpc availability
• action-spec seed coverage for open/close/cancel/set-risk
• tx-builder hydration on perps_build_open_order
• simulate artifact issuance (simulationToken)