Aureon MCP

The Financial Intelligence Layer for Onchain AI Agents

Official Model Context Protocol server for the AUREON Financial Compass.
Exposes the full @buildaureon/sdk surface as tools for Cursor, Claude Desktop, and any MCP host on the Robinhood Chain.

# Hosted (no local process)
https://mcp.aureonlabs.network/mcp

# Or local stdio
npx -y @buildaureon/mcp

How to connect · Quickstart · Architecture · Authentication · Tool Surface · Agent Workflows · Docs

Table of Contents

1. What is AUREON MCP?

2. How to connect

3. Why AUREON MCP?

4. Requirements & Installation

5. Architecture

6. Quickstart

7. Authentication

8. Tool Surface

9. Agent Workflows

10. Sample Agent Prompts

11. Security Model

12. Development

13. Documentation Registry

14. FAQ

15. Community & License

Related MCP server: RailX MCP

What is AUREON MCP?

AUREON is a policy and execution layer for capital on Robinhood Chain. Agents register continuous financial rules (Financial Compass Objectives), monitor health, and restore allocations with clear settlement receipts.

@buildaureon/mcp is the agent adapter. It maps every public @buildaureon/sdk client method to a named tool (aureon_ping, aureon_create_objective, aureon_restore_objective, …). You can reach that same 66-tool surface in two ways:

The npm package is the stdio server. The official hosted process is Streamable HTTP at /mcp (see hostedMCP/ in this monorepo). Both call https://api.aureonlabs.network. Neither holds a wallet private key. Neither signs or broadcasts.

66 tools: one per public AureonClient method. Full schemas: docs/tools.md.

For scripts without MCP, use @buildaureon/sdk. The operator app at app.aureonlabs.network is the mainnet console and stays wallet-Bearer only. SDK and MCP default to mainnet.

How to connect

Hosted (recommended first use)

Paste this into Cursor .cursor/mcp.json. A user key is not required to connect.

{
  "mcpServers": {
    "aureon": {
      "url": "https://mcp.aureonlabs.network/mcp"
    }
  }
}

Open without a key: aureon_ping and aureon_validate_receipt. aureon_list_market_presets needs a key.

Wallet tools need your issued Developers key on the same URL:

{
  "mcpServers": {
    "aureon": {
      "url": "https://mcp.aureonlabs.network/mcp",
      "headers": {
        "X-Aureon-Api-Key": "<issued-developer-api-key>"
      }
    }
  }
}

Templates: examples/cursor.hosted.mcp.json, examples/cursor.hosted.user.mcp.json.

Confirm the host is up: https://mcp.aureonlabs.network/healthz.

Restart Cursor. Ask: “Ping AUREON with aureon_ping.” For aureon_me and the rest of your book, add the header or use stdio.

Local stdio (your key)

{
  "mcpServers": {
    "aureon": {
      "command": "npx",
      "args": ["-y", "@buildaureon/mcp"],
      "env": {
        "AUREON_API_KEY": "<issued-developer-api-key>"
      }
    }
  }
}

Issue the key at app.aureonlabs.network → Developers. Template: examples/cursor.mcp.json.

Why AUREON MCP?

Traditional AI trading scripts execute isolated market orders without context, forgetting target allocations as soon as a prompt ends. AUREON MCP provides a persistent financial compass for your AI agents:

• Continuous Rules vs. One-off Swaps: Instead of telling an agent to "buy 0.5 WETH," you register a Financial Compass Objective like "Maintain 20% WETH weight with 3% tolerance." The watchdog automatically monitors drift and plans restores when needed.

• Non-Custodial Architecture: Your private keys stay safely in your local wallet host. The MCP server generates unsigned transaction payloads that you review and sign.

• Two transports, one tool surface: Hosted HTTP at https://mcp.aureonlabs.network/mcp, or local stdio via npx -y @buildaureon/mcp. This build is the same 66 tools on both. The public host lists 66 after this build is deployed. No local database to run.

• Clear Settlement Receipts: Clearly distinguishes between on-chain smart vault settlements (vault) and ledger-local staged receipts (staged).

Requirements & Installation

Requirements

• Node.js: 20 or higher (ESM compatible)

• Developer API Key: Issued at app.aureonlabs.network → Developers. That app is the mainnet console. SDK and MCP default to mainnet.

• Network Access: Default official API https://api.aureonlabs.network on mainnet. Optional AUREON_NETWORK=testnet stays on testnet on the same host.

Installation

# Using pnpm
pnpm add @buildaureon/mcp

# Using npm
npm install @buildaureon/mcp

# Or run instantly via npx without installing
npx -y @buildaureon/mcp

You do not need to clone the AUREON monorepo: only the package and an issued key for the network you will call.

Architecture

flowchart LR
  Host[Cursor / Claude / other MCP host]
  Host -->|Streamable HTTP| Hosted["https://mcp.aureonlabs.network/mcp"]
  Host -->|stdio| Local["npx @buildaureon/mcp"]
  Hosted --> SDK["@buildaureon/sdk"]
  Local --> SDK
  SDK -->|default| Official[api.aureonlabs.network / mainnet]
  SDK -->|AUREON_NETWORK=testnet| Test[api.aureonlabs.network / testnet]
  Official --> VaultMN[Smart Vault mainnet]
  Test --> VaultTN[Smart Vault testnet]

Surface & Ownership Breakdown

Layer Responsibilities

Trust boundary: The API monitors objectives and generates restore plans; private keys stay strictly on the host machine. MCP never signs chain transactions.

Deep dive: docs/architecture.md.

Quickstart

Fastest path: skip the key for now and use the hosted URL in How to connect. The steps below are for local stdio with your own issued key.

1. Create an issued API key

Issue the key on the same API this MCP process will call:

1. Open https://app.aureonlabs.network → Developers.

2. Create API Key → copy your key once.

That key identifies your wallet for control-plane tools. No Bearer token required. Issue the key on the official API this process will call.

2. Configure Cursor IDE (local stdio)

If you already added the hosted URL, you do not need this block. For your own key, copy examples/cursor.mcp.json into .cursor/mcp.json:

{
  "mcpServers": {
    "aureon": {
      "command": "npx",
      "args": ["-y", "@buildaureon/mcp"],
      "env": {
        "AUREON_API_KEY": "<issued-developer-api-key>"
      }
    }
  }
}

Restart Cursor. Open the AI chat panel and ask: “Ping AUREON and show my wallet with aureon_me.”

3. Configure Claude Desktop

Merge examples/claude-desktop.json into Claude Desktop's configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aureon": {
      "command": "npx",
      "args": ["-y", "@buildaureon/mcp"],
      "env": {
        "AUREON_API_KEY": "<issued-developer-api-key>"
      }
    }
  }
}

Restart Claude Desktop and test the connection.

4. From a local clone (maintainers)

pnpm install
pnpm --filter @buildaureon/mcp build
pnpm --filter @buildaureon/mcp start

Point the host command / args at the built dist/index.js. See docs/setup.md.

Authentication

Recommended: Issued API key

Private Key Boundary: Private keys are only needed outside MCP when signing and broadcasting deposit or withdrawal transactions. Prepare tools return unsigned transaction steps; the MCP server never signs.

Optional: Wallet Bearer session

Use aureon_get_auth_nonce → host wallet signs challenge → aureon_verify_wallet. Prefer issued keys for always-on agents.

Preview / Dev Mode only

aureon_dev_login works only when the API backend has AUREON_ALLOW_DEV_LOGIN=1 (it does not function on production).

Deep dive: docs/auth.md.

Tool Surface

AUREON MCP exposes 66 tools covering 100% of the AureonClient SDK surface:

Full argument schemas: docs/tools.md · Playbooks: docs/agent-guide.md.

Locked fields

• targetSymbol and automationMode are set at create time and cannot be modified via aureon_update_objective: recreate the objective instead.

• Default automationMode is "auto". Use "manual" only when a human must Approve changes inside the utility web app.

• hireLimitEth and hireApprovalRequired are set on create. aureon_check_policy reads them. The check does not sign or send.

Hire policy

aureon_check_policy takes agentId, taskId, objectiveId, and an action of type hire in ETH. The result is allow, refuse, or authorization_required. aureon_get_policy_check reads that decision by actionId. The caller uses an issued Developers key for the wallet that owns the objective. A hire equal to the cap is inside the limit. A hire above the cap is refused. Inside the cap, with approval required, the user decides.

Unsigned restoration

aureon_propose_restoration takes a sleeve id (weightBound: "ceiling", profitTakeRatio) and a reserve id (weightBound: "floor"). Both objectives are manual. The sleeve step sells the profit-take slice above the cap. The reserve step is added only when the floor is still short. transactionHash and sentBy stay null.

Agent Workflows

Agents perform best when following the Read → Decide → Act execution pattern:

flowchart TD
  subgraph Read Phase
    R1[1. aureon_ping] --> R2[2. aureon_me]
    R2 --> R3[3. aureon_sync_portfolio]
    R3 --> R4[4. aureon_get_health]
  end

  subgraph Decide Phase
    R4 --> D1{Policy Breached?}
  end

  subgraph Act Phase
    D1 -- Yes --> A1[aureon_get_restore_plan]
    A1 --> A2[aureon_restore_objective]
    A2 --> A3[aureon_list_timeline]
    D1 -- No --> A4[Maintain current positions]
  end

1. Control-Plane Routine (API Key Only)

1. aureon_ping → aureon_me (Verify connection and wallet identity)

2. aureon_sync_portfolio → aureon_get_vault_status (Fetch marks and check vault readiness)

3. If the vault is empty: aureon_restore_objective returns 409. Call aureon_prepare_vault_deposit, return unsigned steps, and wait for the user or host wallet to broadcast. Agents do not fund the vault.

4. aureon_create_objective (auto) (Register continuous financial objective)

5. aureon_refresh_watchdog / aureon_get_health (Check health score and drift)

6. On violation after the vault is funded → aureon_get_restore_plan → aureon_restore_objective (maintain: sell overweight → buy underweight inside the vault)

7. Prove with aureon_get_execution_settlement / aureon_validate_receipt, then aureon_list_timeline

2. Vault Deposit Path (API Key + External Signer)

1. aureon_prepare_vault_deposit → returns unsigned steps

2. Host wallet signs and broadcasts transaction on Robinhood Chain

3. aureon_sync_portfolio / aureon_get_vault (Re-sync marks to reflect new deposit)

More playbooks: docs/agent-guide.md.

Sample Agent Prompts

Copy and paste these example prompts into Cursor or Claude Desktop:

Portfolio Audit

"Ping AUREON, verify my wallet address with aureon_me, sync my portfolio, and give me a summary of total AUM and active objective health."

Setting a Compass Objective

"Create an automatic Financial Compass Objective named 'Maintain 20% WETH' targeting symbol WETH with weight 0.20 and tolerance 0.03."

Monitoring & Drift Restoration

"Refresh the watchdog and inspect my AUREON health. If any objective is in breach, show me the restore plan and run aureon_restore_objective."

Deposit Preparation

"Prepare an unsigned vault deposit for 0.1 ETH. Return the exact step payload so I can review and sign it in my wallet."

Security Model

• Official hosted vs your own process: Use https://mcp.aureonlabs.network/mcp for the official Streamable HTTP host. Local stdio is a child process of Cursor or Claude — do not publish your stdio server as an open internet socket. Do not put a wallet private key in either transport.

• API Key Protection: Treat AUREON_API_KEY like a password. Pause, revoke, or rotate keys in the Developer dashboard if compromised.

• Environment Hygiene: Never commit keys to version control. Never put wallet private keys into MCP environment variables.

• Prompt Safety: Review agent prompts before enabling write tools in untrusted or multi-user chat channels.

Deep dive details: docs/security.md.

Development

To build and test @buildaureon/mcp locally:

pnpm install
pnpm --filter @buildaureon/mcp build
pnpm --filter @buildaureon/mcp test
pnpm --filter @buildaureon/mcp typecheck

Script Reference

Documentation Registry

FAQ

Do I need a private key in Cursor or Claude env?
No. You only need an issued AUREON_API_KEY. Private keys stay in your host wallet when signing prepare steps.

Is there only stdio?
No. Official hosted MCP is https://mcp.aureonlabs.network/mcp (Streamable HTTP). This build is 66 tools. The public host lists 66 after this build is deployed. Connect with the URL alone for aureon_ping and aureon_validate_receipt. Add X-Aureon-Api-Key for your wallet tools. Local stdio is npx -y @buildaureon/mcp with your issued AUREON_API_KEY.

Does MCP talk to a local backend server?
No. Both transports call the official API https://api.aureonlabs.network on mainnet by default. Set AUREON_NETWORK=testnet on a stdio process to stay on testnet on that same host.

Why did my restore receipt say staged?
staged is a ledger-local receipt, not an on-chain vault settlement. Always describe settlement receipts accurately in agent responses.

Can agents use Manual automation mode?
Automatic is the default for a keeper restore. A sleeve and a reserve for aureon_propose_restoration are manual, so the proposal stays unsigned.

What happens if an objective breaches its drift tolerance?
The watchdog marks health as breached. Agents call aureon_get_restore_plan to inspect the rebalancing steps, then aureon_restore_objective to execute the restore.

How does MCP handle network errors or disconnects?
The underlying @buildaureon/sdk handles HTTP retries and reports structured error objects with stable error codes back to the MCP host.

Community

• Website: https://www.aureonlabs.network

• Hosted MCP: https://mcp.aureonlabs.network/mcp

• Hosted health: https://mcp.aureonlabs.network/healthz

• X (Twitter): https://x.com/buildaureon

• App Utility: https://app.aureonlabs.network

• MCP repo: https://github.com/buildaureon/aureon-mcp

• SDK repo: https://github.com/buildaureon/aureon-sdk

License

MIT (see LICENSE).