Emerald Exchange - API | MCP | A2A

Version: 2.2.0

Documentation — Installation, deployment, usage across the API, CLI, and MCP interfaces, the A2A agent server, and the trading configuration schema are maintained in the official documentation.

Overview

Emerald Exchange is a unified Finance MCP Server providing fully abstracted exchange backends for equities, crypto, and derivatives trading. All trading feature is tool-driven via MCP, with built-in financial hardening controls (OS-5.1).

Key Features:

• 5 Exchange Backends: Paper (default), Alpaca (FREE), CCXT (100+ exchanges), Freqtrade
• 6 MCP Tool Domains: market-data, orders, portfolio, risk, signals, strategy
• Financial Hardening: Paper-first default, Kelly criterion position sizing, circuit breakers, kill switch
• Config-Driven: All settings via ~/.config/agent-connectors/config.json

Architecture

flowchart TB
    A["Agent / IDE"] --> B["emerald-exchange MCP"]
    B --> C["Risk Guard (OS-5.1)"]
    C --> D{"Exchange Router"}
    D --> E["Paper Backend (Default)"]
    D --> F["Alpaca Backend (FREE)"]
    D --> G["CCXT Backend (Binance/Coinbase/Kraken)"]
    D --> H["Freqtrade Backend"]

    style B fill:#10B981,stroke:#065F46,color:#fff
    style C fill:#EF4444,stroke:#991B1B,color:#fff
    style E fill:#6366F1,stroke:#4338CA,color:#fff

MCP Tools

Auto-generated from the live MCP server — do not edit by hand.

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

15 action-routed tool(s) · 9 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Exchange Backends

Financial Hardening (OS-5.1)

Usage

MCP Configuration

Install the slim [mcp] extra. The examples below install emerald-exchange[mcp] — the MCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-connector-sdk). It deliberately excludes the heavy agent-orchestration runtime (pydantic-ai, dspy, llama-index, tree-sitter and the agent frontends), so uvx/container installs stay smaller and faster — note the mandatory epistemic-graph[full] engine is still present either way, since it is a base dependency of agent-connector-sdk itself, not gated behind an extra. Use the full [agent] extra only when the operator need the integrated Pydantic AI agent (see Installation). Add trading-backend extras ([alpaca], [crypto], [prediction_markets], …) on top as needed.

stdio Mode

{
  "mcpServers": {
    "emerald-exchange": {
      "command": "uvx",
      "args": ["--from", "emerald-exchange[mcp]", "emerald-exchange-mcp"],
      "env": {}
    }
  }
}

Streamable HTTP Mode

emerald-exchange-mcp --transport streamable-http --port 8100

Configuration

All trading settings are configured via ~/.config/agent-connectors/config.json:

{
  "trading": {
    "default_mode": "paper",
    "default_exchange": "alpaca",
    "exchanges": {
      "alpaca": {
        "enabled": true,
        "api_key_env": "ALPACA_API_KEY",
        "api_secret_env": "ALPACA_SECRET_KEY",
        "base_url": "https://paper-api.alpaca.markets"
      }
    },
    "risk_limits": {
      "max_position_pct": 0.02,
      "max_portfolio_drawdown_pct": 0.10,
      "max_daily_loss_pct": 0.03,
      "require_human_approval_live": true
    }
  }
}

Additional Deployment Options

emerald-exchange can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

• Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
• Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

⚙️ Dynamic Tool Selection & Visibility

This MCP server supports dynamic toolset selection and visibility filtering at runtime. This allows the operator to restrict the set of exposed tools to prevent blowing up the LLM's context window.

The operator can configure tool filtering via multiple input channels:

• CLI Arguments: Pass --tools or --toolsets (or their disabled counterparts --disabled-tools and --disabled-toolsets) during startup.
• Environment Variables: Define standard environment variables:
  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS
  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS
• HTTP SSE Request Headers: Pass custom headers during transport initialization:
  • x-mcp-enabled-tools / x-mcp-disabled-tools
  • x-mcp-enabled-tags / x-mcp-disabled-tags
• HTTP SSE Request Query Parameters: Append query parameters directly to the operator's transport connection URL:
  • ?tools=tool1,tool2
  • ?tags=tag1

When query strings or parameters are provided, an LLM-free Knowledge Graph resolution layer (using DynamicToolOrchestrator) matches query intents against known tool tags, names, or descriptions, with safe fallback and automated 24-hour background cache refreshing.

Installation

Pick the extra that matches what the operator want to run, then layer trading-backend extras on top:

pip install "emerald-exchange[mcp]"                # MCP server only (slim deps)
pip install "emerald-exchange[agent]"              # Full agent runtime (Pydantic AI + engine)
pip install "emerald-exchange[mcp,alpaca]"         # + Alpaca equities
pip install "emerald-exchange[mcp,crypto]"         # + CCXT crypto
pip install "emerald-exchange[mcp,prediction_markets]"  # + Kalshi & Polymarket
pip install "emerald-exchange[all]"                # Everything

Docker

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

docker build --target mcp   -t knucklessg1/emerald-exchange:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/emerald-exchange:2.2.0 docker/   # full agent
docker compose -f docker/mcp.compose.yml up -d                               # run the slim :mcp server
docker compose -f docker/compose.yml up -d                                   # full stack

Knowledge-graph database (epistemic-graph)

Both [mcp] and [agent] carry the epistemic-graph engine through the required Agent Connector SDK core dependency (epistemic-graph[full]) — it is a mandatory base dependency of agent-connector-sdk, not gated behind an extra. The [mcp] extra keeps the server slim/connector-focused (no agent-orchestration stack); [agent] also enables Pydantic AI/DSPy model orchestration. Local deployments can use the bundled engine. For production — or to share one knowledge graph across multiple agents — run epistemic-graph as its own dedicated database service and point the runtime at it instead of embedding it. Deployment recipes (single-node + Raft HA), connection configuration, and the full database architecture (with diagrams) are documented in the epistemic-graph deployment guide.

Documentation

The complete documentation is published as the official documentation site and is the recommended reference for installation, deployment, and day-to-day operation.

AGENTS.md is the canonical contributor/agent guidance.

Deploy with agent-os-genesis

This package can be provisioned for you — skill-guided — by the agent-os-genesis universal skill (its single-package deploy mode): it picks your install method, seeds secrets to OpenBao/Vault (or .env), trusts your enterprise CA, registers the MCP server, and verifies it — the same machinery that stands up the whole Agent OS, narrowed to just this package. Ask your agent to "deploy emerald-exchange with agent-os-genesis".

Secrets are read-existing + seeded via vault_sync — you are only prompted for what's missing.

Single-package self-setup: deployment

For a tiny/single-node-prod profile scoped to just this package (no whole-homelab genesis), the deployment skill runs the equivalent install-mode/secrets/doctor/registration/observability/rollback sequence. Ask the operator's agent to "deploy emerald-exchange with deployment".

Either path: the repository embeds no deployment profile, credential value, certificate path, or environment-specific endpoint. Runtime secrets, TLS trust material, and endpoints come from AgentConfig / the configured secret provider (OpenBao or .env), never from a committed file.

Environment Variables

Package environment variables

Inherited agent-connector-sdk variables (apply to every connector)

24 package + 24 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.