BoundBound Docs
Integrations

AI Agent Integration

How AI agents interact with Bound via the MCP server and CLI — install, configure, and use all 18 protocol tools.

AI Agent Integration

CCP ships as an npm package (@iamnotdou/ccp) with two interfaces for AI agents:

  • MCP Server — 18 native tools over Model Context Protocol (recommended for AI agents)
  • CLI — ccp <command> for shell-based interaction

The MCP server exposes the same operations as the CLI but returns structured JSON — no parsing needed. AI agents like OpenClaw, Claude, and others can call tools directly.

Install

npm install -g @iamnotdou/ccp

Or run without installing:

npx @iamnotdou/ccp status
npx @iamnotdou/ccp mcp        # start MCP server

MCP Server Setup

The MCP server runs over stdio and exposes all CCP operations as tools. Add it to your agent's MCP configuration.

Minimum Config (Agent Only)

Only AGENT_PRIVATE_KEY is required. Contract addresses and RPC default to Hedera Testnet.

{
  "mcpServers": {
    "ccp": {
      "command": "npx",
      "args": ["@iamnotdou/ccp", "mcp"],
      "env": {
        "AGENT_PRIVATE_KEY": "0x..."
      }
    }
  }
}

This gives the agent access to all read tools (ccp_status, ccp_cert_verify, ccp_spending_status, ccp_hcs_timeline, etc.) and ccp_spending_pay for payments under $5,000.

Full Config (All Roles)

For operators who also need to publish certs, manage reserves, and cosign:

{
  "mcpServers": {
    "ccp": {
      "command": "npx",
      "args": ["@iamnotdou/ccp", "mcp"],
      "env": {
        "AGENT_PRIVATE_KEY": "0x...",
        "OPERATOR_PRIVATE_KEY": "0x...",
        "AUDITOR_PRIVATE_KEY": "0x...",
        "LEDGER_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Key Permissions

KeyRequired For
AGENT_PRIVATE_KEYccp_spending_pay, ccp_spending_pay_cosign
LEDGER_PRIVATE_KEYccp_spending_pay_cosign, ccp_cert_publish
OPERATOR_PRIVATE_KEYccp_cert_publish, ccp_cert_revoke, ccp_reserve_deposit, ccp_reserve_lock
AUDITOR_PRIVATE_KEYccp_cert_publish, ccp_auditor_audit

All read-only tools (ccp_status, ccp_cert_verify, ccp_cert_get, ccp_reserve_status, ccp_spending_status, ccp_hcs_timeline, etc.) work without any key.

OpenClaw / Custom Agents

Any MCP-compatible agent can connect to the server via stdio:

# The server communicates over stdin/stdout using the MCP protocol
npx @iamnotdou/ccp mcp

Or programmatically:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["@iamnotdou/ccp", "mcp"],
});
const client = new Client({ name: "my-agent", version: "1.0" });
await client.connect(transport);

// List all 18 tools
const { tools } = await client.listTools();

// Call any tool
const result = await client.callTool({
  name: "ccp_status",
  arguments: {},
});
console.log(result.content[0].text);

MCP Tools Reference

All tools return structured JSON. Write operations submit on-chain transactions to Hedera Testnet.

Overview Tools

ToolDescriptionParameters
ccp_statusFull system overview: spending limits, reserve vault, balances, active certificateNone
ccp_addressesAll contract addresses, network config, and actor addressesNone

Certificate Tools

ToolDescriptionParameters
ccp_cert_verifyVerify agent meets containment requirementsagentAddress, minClass? (1-3), maxLoss? (USDC)
ccp_cert_getGet full certificate details by hashcertHash
ccp_cert_lookupFind active certificate for an agentagentAddress
ccp_cert_publishPublish new certificate (full flow: audit + stake + sign + publish)None
ccp_cert_revokeRevoke a certificate (operator only)certHash

Reserve Tools

ToolDescriptionParameters
ccp_reserve_statusBalance, lock status, C2/C3 adequacyNone
ccp_reserve_depositDeposit USDC into vault (operator)amount (USDC string)
ccp_reserve_lockLock vault for N days (operator)days (number)

Spending Tools

ToolDescriptionParameters
ccp_spending_statusConfig, period tracking, enforcement rulesNone
ccp_spending_payPay below $5k (agent-only signature)to, amount (USDC string)
ccp_spending_pay_cosignPay 5k−5k-10k (Ledger co-signature)to, amount (USDC string)

Auditor Tools

ToolDescriptionParameters
ccp_auditor_statusAttestation count, active stake, challengesaddress?
ccp_auditor_auditRead-only containment auditNone

Challenge Tools

ToolDescriptionParameters
ccp_challenge_getGet challenge detailschallengeId
ccp_challenge_listList challenges for a certificatecertHash

Event Tools

ToolDescriptionParameters
ccp_hcs_timelineFull HCS event timeline from Hedera Consensus ServiceNone

Spending Rules

The SpendingLimit contract enforces these absolute limits — even Ledger co-signature cannot bypass them:

Amount RangeSignature RequiredOutcome
0–0 – 5,000Agent onlyUse ccp_spending_pay
5,001–5,001 – 10,000Agent + LedgerUse ccp_spending_pay_cosign
> $10,000N/ABLOCKED — exceeds maxSingleAction
Period total > $50,000N/ABLOCKED — exceeds maxPeriodicLoss

These limits are agent-independent. The smart contract enforces them regardless of who signs the transaction. This is the core CCP thesis: the cage holds because the agent cannot modify it.

Example: Agent Workflow

A typical AI agent interaction with CCP follows this pattern:

1. Check System Status

Tool: ccp_status
→ Returns spending limits, reserve balance, active certificate, all balances

2. Verify Before Transacting

Tool: ccp_cert_verify
Args: { "agentAddress": "0x89cFD052..." }
→ { "acceptable": true, "result": "VERIFICATION PASSED" }

3. Make a Payment

Tool: ccp_spending_pay
Args: { "to": "0xRecipient...", "amount": "500" }
→ { "txHash": "0x...", "periodSpent": "$500 / $50000 USDC" }

4. Make a Larger Payment (Ledger Co-Sign)

Tool: ccp_spending_pay_cosign
Args: { "to": "0xRecipient...", "amount": "7000" }
→ { "txHash": "0x...", "cosigned": true, "periodSpent": "$7500 / $50000 USDC" }

5. Attempt Over-Limit (Blocked)

Tool: ccp_spending_pay_cosign
Args: { "to": "0xRecipient...", "amount": "45000" }
→ { "error": "TRANSACTION_BLOCKED", "containmentHeld": true }

6. Review Event History

Tool: ccp_hcs_timeline
→ Chronological list of all protocol events with timestamps

CLI Quick Reference

For shell-based interaction, the ccp command maps 1:1 to the MCP tools:

ccp status                                    # ccp_status
ccp cert:verify 0x89cFD052...                 # ccp_cert_verify
ccp cert:get <certHash>                       # ccp_cert_get
ccp cert:lookup <agentAddress>                # ccp_cert_lookup
ccp cert:publish                              # ccp_cert_publish
ccp cert:revoke <certHash>                    # ccp_cert_revoke
ccp reserve:status                            # ccp_reserve_status
ccp reserve:deposit 150000                    # ccp_reserve_deposit
ccp reserve:lock 90                           # ccp_reserve_lock
ccp spending:status                           # ccp_spending_status
ccp spending:pay <to> 500                     # ccp_spending_pay
ccp spending:pay:cosign <to> 7000             # ccp_spending_pay_cosign
ccp auditor:status                            # ccp_auditor_status
ccp auditor:audit                             # ccp_auditor_audit
ccp challenge:get <id>                        # ccp_challenge_get
ccp challenge:list <certHash>                 # ccp_challenge_list
ccp hcs:timeline                              # ccp_hcs_timeline

Live Contracts (Hedera Testnet)

All contracts are deployed and verified on Hedera Testnet (chain ID 296):

ContractAddress
CCPRegistry0x776CAbA2d5E63F96358f1624976D6Aaa6b780ed1
SpendingLimit0x530ecF8Afddb752748aCE1Ece90e34FD1ca7eE6C
ReserveVault0xb2fFaf44Ae415b0e1dFc99c8E07dfDE2a5369Aa6
AuditorStaking0xe786eB0F88b8A30e0ABf4C634fc414084b2134eC
FeeEscrow0xe619F278352B4eED4465a176Df0B2A2F2CAf3557
ChallengeManager0x6238a4f9ad158dA64a4478FE64Ba0416b176cFC7
HCS Topic0.0.8510266

Error Handling

MCP tools return isError: true when a transaction is blocked or fails. The agent should check this field:

ErrorMeaningAgent Action
TRANSACTION_BLOCKEDContainment limit enforcedReduce amount or wait for period reset
TRANSACTION_FAILEDReverted (e.g. CosignRequired)Use ccp_spending_pay_cosign instead
VERIFICATION FAILEDAgent lacks valid certificateCheck cert status with ccp_cert_lookup

The containmentHeld: true field confirms the protocol worked as designed — the agent was prevented from exceeding its bounds.

Auditor Workflow

How independent auditors verify containment architectures and co-sign certificates.

Transaction Scenarios

Real-world examples of how Bound verification works in agent-to-service and agent-to-agent transactions.

On this page

AI Agent IntegrationInstallMCP Server SetupMinimum Config (Agent Only)Full Config (All Roles)Key PermissionsOpenClaw / Custom AgentsMCP Tools ReferenceOverview ToolsCertificate ToolsReserve ToolsSpending ToolsAuditor ToolsChallenge ToolsEvent ToolsSpending RulesExample: Agent Workflow1. Check System Status2. Verify Before Transacting3. Make a Payment4. Make a Larger Payment (Ledger Co-Sign)5. Attempt Over-Limit (Blocked)6. Review Event HistoryCLI Quick ReferenceLive Contracts (Hedera Testnet)Error Handling