havona-mcp

MCP server for the Havona trade finance API. Connect any MCP-compatible AI assistant to live trade contracts, blockchain status, and document extraction.

Tools

Tool	Description
list_trades	List recent trade contracts
get_trade	Fetch a trade by ID
create_trade	Create a new trade contract
update_trade_status	Update status (DRAFT → ACTIVE → COMPLETED)
blockchain_status	Check chain connection + contract address
get_trade_blockchain_record	Get on-chain confirmation for a trade
list_agents	List registered ERC-8004 AI agents
get_agent_reputation	Get agent reputation score
list_supported_document_types	List extractable ETR document types
extract_trade_document	Extract fields from a PDF (AI, no persistence)
graphql_query	Raw GraphQL passthrough

Install

pip install havona-mcp

Or from source:

git clone https://github.com/havona-labs/havona-mcp
cd havona-mcp
pip install -e .

Configuration

Copy .env.example to .env:

HAVONA_API_URL=https://api.yourdomain.com
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_AUDIENCE=https://api.yourdomain.com
AUTH0_CLIENT_ID=your_client_id
HAVONA_EMAIL=trader@yourdomain.com
HAVONA_PASSWORD=your_password

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "havona": {
      "command": "python",
      "args": ["-m", "havona_mcp"],
      "env": {
        "HAVONA_API_URL": "https://api.yourdomain.com",
        "AUTH0_DOMAIN": "your-tenant.us.auth0.com",
        "AUTH0_AUDIENCE": "https://api.yourdomain.com",
        "AUTH0_CLIENT_ID": "your_client_id",
        "HAVONA_EMAIL": "trader@yourdomain.com",
        "HAVONA_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop. You can now ask:

"Show me my recent trades" "What's the blockchain status?" "Create a draft trade for 50,000 barrels of crude oil" "Extract the fields from this commercial invoice PDF"

Cursor / other MCP clients

python -m havona_mcp          # stdio (default)
python -m havona_mcp --sse    # SSE transport for web clients

Architecture

Claude Desktop / Cursor
        │  MCP protocol (stdio or SSE)
        ▼
  havona-mcp  (this repo)
        │  Python function calls
        ▼
  havona-sdk
        │  HTTPS + Bearer token
        ▼
  Havona API  →  DGraph + Confidential EVM

License

MIT — see LICENSE.