OpenWealth MCP

Three FastMCP servers that expose the OpenWealth APIs as MCP tools, so an AI assistant (Claude, Cursor, any MCP client) can read custody data, manage orders, and onboard customers through a typed, audited interface instead of raw HTTP.

All three ship in one Python package and speak MCP over stdio. OpenAPI specs are vendored from OpenWealth and served as sanitized MCP resources (server URLs and auth schemes are stripped before the spec is exposed to the LLM).

⚠️ Trading places real orders. create_order is a financially consequential tool. Read Safety model before pointing it at anything other than the sandbox.

Install

pip install openwealth-mcp

Requires Python ≥ 3.11 and a bearer token for an OpenWealth endpoint (sandbox or custodian).

To install from source for development:

git clone https://github.com/OpenWealth/OpenWealth-MCP.git
cd OpenWealth-MCP
pip install -e ".[dev]"    # or: uv sync --extra dev

Quickstart

Configure each server separately — each needs its own base URL and token.

Claude Desktop / Claude Code (claude_desktop_config.json):

{
  "mcpServers": {
    "openwealth-custody": {
      "command": "openwealth-custody-mcp",
      "env": {
        "OPENWEALTH_CUSTODY_BASE_URL": "<host>",
        "OPENWEALTH_BEARER_TOKEN": "<jwt>"
      }
    },
    "openwealth-trading": {
      "command": "openwealth-trading-mcp",
      "env": {
        "OPENWEALTH_TRADING_BASE_URL": "<host>",
        "OPENWEALTH_BEARER_TOKEN": "<jwt>"
      }
    },
    "openwealth-customer": {
      "command": "openwealth-customer-mcp",
      "env": {
        "OPENWEALTH_CUSTOMER_MANAGEMENT_BASE_URL": "<host>",
        "OPENWEALTH_BEARER_TOKEN": "<jwt>"
      }
    }
  }
}

Cursor (.cursor/mcp.json, or Settings → MCP for a global server):

{
  "mcpServers": {
    "openwealth-custody": {
      "command": "openwealth-custody-mcp",
      "env": {
        "OPENWEALTH_CUSTODY_BASE_URL": "<host>",
        "OPENWEALTH_BEARER_TOKEN": "<jwt>"
      }
    },
    "openwealth-trading": {
      "command": "openwealth-trading-mcp",
      "env": {
        "OPENWEALTH_TRADING_BASE_URL": "<host>",
        "OPENWEALTH_BEARER_TOKEN": "<jwt>"
      }
    },
    "openwealth-customer": {
      "command": "openwealth-customer-mcp",
      "env": {
        "OPENWEALTH_CUSTOMER_MANAGEMENT_BASE_URL": "<host>",
        "OPENWEALTH_BEARER_TOKEN": "<jwt>"
      }
    }
  }
}

Then run MCP: Restart Servers from the command palette and check that the server shows as connected. Configure only the domain you have access to.

Sandbox JWTs often expire in about 60 seconds — refresh from the portal and restart the server. Supply the token without the Bearer prefix; the client adds it.

Full client wiring, WSL specifics and troubleshooting live in docs/mcp-clients.md and docs/local-dev.md.

Configuration

All settings are environment variables prefixed OPENWEALTH_. A .env file in the working directory is loaded automatically (and is gitignored — never commit one). Host and credentials are never hard-coded.

Startup fails fast if neither OPENWEALTH_BEARER_TOKEN nor OPENWEALTH_AUTH_HEADER is set. The URL for each server is validated at startup — a missing URL prints a clear error and exits.

Transport is stdio only. HTTP transport and JWKS ingress are out of scope in favour of a smaller surface.

Tools

Every response is JSON with status_code, correlation_id and data (plus next_cursor on paginated GETs). Errors return {"error": true, "error_code": "...", "message": "...", "retryable": bool} — never a stack trace.

Custody — openwealth-custody-mcp

Listing positions and transactions requires a date (YYYY-MM-DD) — the OpenAPI spec makes it mandatory.

Trading — openwealth-trading-mcp

Customer Management — openwealth-customer-mcp

⚠️ marks tools that create regulatory or compliance-significant entities (customer, person, document, kyc) — records that are hard to reverse and carry KYC/AML implications. Write tools on softer, mutable data (contact, address, prospect_precheck) are not marked because they can be freely updated or deleted without compliance impact. All Customer Management write tools are still never retried regardless of the ⚠️ marker — see Safety model.

MCP resources

Safety model

• create_order is never retried. A duplicate order is a financial error, so a failed POST fails loudly rather than silently placing a second one.
• Customer Management write tools are never retried. create_customer, create_person, create_contact, create_address, create_document, create_kyc and create_prospect_precheck are not retried to avoid duplicate records at the custody bank.
• Idempotent writes are retried on 5xx: cancel_order, create_quote, update_contact, update_address, PUT and DELETE. GETs retry on 408, 429 and 5xx with exponential backoff and ±20% jitter. The Retry-After header is honoured.
• Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are set per tool, so MCP clients can require confirmation for writes.
• Tokens are never tool arguments. They come from the environment only, and are never echoed in tool results or logs.
• Custody is read-only by design. Only the Trading and Customer servers can mutate state.

Always confirm order details with a human before calling create_order.

Development

With uv (recommended):

uv sync --extra dev

uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy
uv run pytest -q

With pip:

pip install -e ".[dev]"

ruff check src tests
ruff format --check src tests
mypy
pytest -q

The same four gates run in CI on every push and pull request across Python 3.11, 3.12 and 3.13. pre-commit install wires ruff and mypy into your commits.

See CONTRIBUTING.md for full contribution guidelines.

Documentation

Scope

Custody is read-only (GET). Trading covers the full order lifecycle (GET, POST, PUT, DELETE). Customer Management covers the full customer onboarding and lifecycle (GET, POST, PUT, DELETE). HTTP transport, JWKS ingress and a central MCP gateway are out of scope.

License

Apache-2.0