Skip to main content

​
Overview

The MCP server exposes the canonical CAW runtime toolkit via the Model Context Protocol (MCP) stdio transport, powered by FastMCP. It can be used with Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients. By default it exposes the full toolkit. For production runtimes, you can narrow the tool surface with include_tools / exclude_tools in code or with environment variables.

​
Running the Server

python -m cobo_agentic_wallet.mcp
Or programmatically: 
from cobo_agentic_wallet.mcp.server import MCPServerConfig, create_server

server = create_server(
    config=MCPServerConfig(
        include_tools=("submit_pact", "get_pact", "contract_call", "get_transaction_record_by_request_id"),
    )
)
server.run()  # starts stdio transport

​
Tool Surface

The MCP server exposes 20 tools grouped around the real developer workflow:

​
Wallet context

ToolDescription
list_walletsDiscover wallets accessible to the caller.
get_walletInspect wallet metadata and status.
list_wallet_addressesList on-chain addresses derived for a wallet.
get_balanceGet wallet token balances, optionally filtered by chain or token.

​
Scoped authority

ToolDescription
submit_pactSubmit a pact for owner approval so the runtime can obtain scoped authority.
get_pactFetch the latest state of a pact.
list_pactsList pacts visible to the caller.
create_delegationCreate a delegation directly when you need owner-side provisioning flows.

​
Onchain and payment actions

ToolDescription
transfer_tokensSubmit a token transfer subject to policy enforcement.
contract_callSubmit a smart-contract call subject to policy enforcement.
message_signSign a message or typed data without broadcasting a transaction.
paymentSubmit a payment request such as x402 or MPP.
estimate_transfer_feeEstimate the fee for a transfer before submitting it.
estimate_contract_call_feeEstimate the fee for a contract call before submitting it.

​
Tracking and audit

ToolDescription
list_transactionsList live transactions associated with a wallet.
list_transaction_recordsList persisted transaction records across transfers, calls, deposits, and payments.
get_transaction_recordFetch a transaction record by record UUID.
get_transaction_record_by_request_idLook up a transaction record by idempotency request ID.
list_recent_addressesList recently used destination addresses.
get_audit_logsQuery the audit trail of actions, decisions, and denials.

​
Claude Desktop Configuration

Add this to your Claude Desktop claude_desktop_config.json: 
{
  "mcpServers": {
    "cobo-agent-wallet": {
      "command": "python",
      "args": ["-m", "cobo_agentic_wallet.mcp"],
      "env": {
        "AGENT_WALLET_API_URL": "https://api.agenticwallet.cobo.com",
        "AGENT_WALLET_API_KEY": "your-api-key"
      }
    }
  }
}

​
Environment Variables

VariableDefaultDescription
AGENT_WALLET_API_URL'http://localhost:8000'API base URL
AGENT_WALLET_API_KEY—API key (required)
AGENT_WALLET_TIMEOUT30.0Request timeout in seconds
AGENT_WALLET_INCLUDE_TOOLS—include_tools
AGENT_WALLET_EXCLUDE_TOOLS()exclude_tools
Example: 
export AGENT_WALLET_INCLUDE_TOOLS=submit_pact,get_pact,contract_call,get_transaction_record_by_request_id,get_audit_logs
python -m cobo_agentic_wallet.mcp
For real developer workflows, the canonical MCP sequence is:
  1. list_wallets and get_wallet
  2. submit_pact, then poll get_pact until the owner activates it
  3. estimate_transfer_fee or estimate_contract_call_fee
  4. transfer_tokens, contract_call, message_sign, or payment
  5. get_transaction_record_by_request_id or list_transaction_records
  6. get_audit_logs

​
Error Contract

The MCP server handles errors with the following semantics:
  • Policy denials — Returned as normal tool content, not protocol errors. The payload includes error, status_code, message, code, reason, details, suggestion, formatted, and retryable.
  • API errors — Raised as RuntimeError with JSON payload containing status_code, message, and response. These become MCP protocol errors (isError: true).
  • Missing API key — Raises RuntimeError at tool invocation time with a descriptive message.
{
  "error": "POLICY_DENIED",
  "code": "TRANSFER_LIMIT_EXCEEDED",
  "reason": "max_per_tx",
  "details": {"limit_value": 100, "requested": 1000},
  "suggestion": "Retry with amount <= 100.",
  "formatted": "Policy Denied [TRANSFER_LIMIT_EXCEEDED]: max_per_tx\n  limit_value: 100\n  requested: 1000\nSuggestion: Retry with amount <= 100.",
  "retryable": true
}

​
Server Configuration

from cobo_agentic_wallet.mcp.server import MCPServerConfig, create_server

config = MCPServerConfig(
    api_url="https://api.agenticwallet.cobo.com",
    api_key="your-api-key",
    timeout=30.0,
    include_tools=("submit_pact", "get_pact", "contract_call", "get_transaction_record_by_request_id"),
    exclude_tools=("create_delegation",),
)

server = create_server(config=config)
server.run()