Quickstart Guide

1 Install via npx

# One-line install — no global packages needed
npx @openclaw/financeos-mcp --help

Or add to your Claude Desktop config:

{
  "mcpServers": {
    "financeos": {
      "command": "npx",
      "args": ["-y", "@openclaw/financeos-mcp"],
      "env": {
        "FINANCE_AUTH_TOKEN": "your-token-here",
        "PG_HOST": "your-postgres-host"
      }
    }
  }
}

2 Check Health

# Verify the server is running
curl http://localhost:18811/health

Expected response:

{
  "ok": true,
  "service": "finance-mcp-server",
  "version": "2.2.0",
  "capabilities": ["account_overview", "cashflow_analysis", ...],
  "stripe": "live",
  "scalekit": "configured"
}

3 Discover Capabilities

# List all MCP capabilities (no auth required)
curl http://localhost:18811/mcp/capabilities

Returns 6 capabilities:

4 Call a Capability

# Get account overview (requires auth)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:18811/capabilities/account_overview

5 MCP Streamable HTTP (for AI agents)

# Initialize MCP session
curl -X POST http://localhost:18811/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    },
    "id": 1
  }'

# List available tools
curl -X POST http://localhost:18811/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

# Call a tool
curl -X POST http://localhost:18811/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "finance.account_overview",
      "arguments": {}
    },
    "id": 3
  }'

Architecture

Client (Claude / Agent / curl)
    |
    v
[FinanceOS MCP Server :18811]
    |--- /mcp            (Streamable HTTP, JSON-RPC 2.0)
    |--- /capabilities/* (REST endpoints, Bearer auth)
    |--- /webhook/stripe (Stripe signature verified)
    |
    +--- Auth Middleware (hybrid: JWT via Scalekit + Bearer)
    +--- 6 Capabilities (account, cashflow, spend, payment, compliance, audit)
    +--- Stripe Integration (Payment Intents, webhooks, refunds)
    +--- PostgreSQL (11 tables, 5 FinanceOS + 3 council + 3 schema)
    |
[Case Orchestrator :18812]
    +--- 7-State Machine (draft->pending->review->approved->executed)
    +--- Policy Engine (29 rules, Constitution + Finance Extension)
    +--- Escalation Cron (24h warn, 48h auto-escalate)
    +--- Duplicate Invoice Detection (SHA256 hash, 48h window)
    +--- Chainlog v2 (Five-layer audit, hash chain, replay)