AgentKeeper-MCP is a non-custodial MCP server that gives AI agents a guarded execution gateway to EVM networks and HTTP 402 paywalled APIs.
Execute on-chain transactions safely (keeper_execute_tx): Send EVM transactions with validation, gas optimization, and idempotency protection, while keeping private keys isolated from the agent.
Autonomously settle HTTP 402 micropayments (keeper_x402_settle): Parse paywall challenges, generate EIP-712 permit signatures with daily spend limits, and retry the request to unlock paid data.
Verify transaction audit trails (keeper_audit_verify): Cryptographically check Merkle proof, inclusion block, and execution receipt for any prior agent transaction or task.
Inspect agent treasury balances (keeper_agent_balance): Query live multi-chain balances, spent budget, and remaining limits for a given address.
Additional advanced features (per README, not exposed in current schema): Plan multi-step workflows with dry-run validation (keeper_plan_workflow), and settle Creditcoin attestcoin intents with Merkle-based escrow release (keeper_creditcoin_settle).
Enables onchain interactions on Ethereum Mainnet via KeeperHub, including transaction execution, x402 micro-payment settlement, and cryptographic audit verification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AgentKeeper-MCP settle the HTTP 402 micro-payment for the latest API request"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A non-custodial Model Context Protocol (MCP) server that gives autonomous AI agents a safe execution gateway to EVM networks and HTTP 402 paywalled APIs.
1-Second Instant Demo:
make demo
If you give an autonomous agent (Claude, Gemini, Cursor) direct access to an RPC or raw private key, three critical failures happen:
Context Credential Leaks: The moment an execution errors out, the model includes raw private keys or RPC URLs in its chat history or debug prompts.
Nonce Collisions & Gas Drain: High-frequency agents retry transactions without tracking mempool states, burning capital on stuck nonces during fee spikes.
The Paywall Dead-End: When an agent queries paid data services returning HTTP 402 Payment Required, it has no standardized way to sign a micro-payment and continue execution.
Related MCP server: @arispay/payagent-mcp
AgentKeeper sits as a local middleware between the LLM runtime and blockchain networks. Private keys stay isolated in local memory, while the agent interacts solely through five bounded tools:
┌────────────────────────────────────────────────────────┐
│ AI Agent (Claude / Cursor / IDE) │
└──────────────────────────┬─────────────────────────────┘
│ (stdio / FastMCP)
▼
┌────────────────────────────────────────────────────────┐
│ AgentKeeper-MCP │
│ │
│ [1] keeper_execute_tx ───► Local Key Sandbox │
│ [2] keeper_x402_settle ───► EIP-712 Spend Budget │
│ [3] keeper_audit_verify ───► Merkle Proof Engine │
│ [4] keeper_agent_balance ───► Multi-Chain Balances │
│ [5] keeper_creditcoin_settle ► Attestcoin L1 Escrow │
└──────────────┬───────────────────────────┬─────────────┘
│ │
▼ ▼
EVM / L2 Networks x402 Paywalled APIs
(Arc / Base / Arb / Mantle) (Per-token Data Feeds)keeper_execute_tx)Validates target contracts, calldata schemas, and gas parameters before signing.
Implements an in-memory FIFO idempotency cache (cap = 1024, Keccak256 deduplication) to prevent duplicate execution during network latency.
Supports deterministic pre-flight simulation (dry_run=True) without state mutation or network broadcast.
Never passes raw cryptographic keys to the LLM context.
keeper_plan_workflow)Composes multi-step agent workflows across execution, micropayments, and settlements into a single verified plan.
Pre-flight validates all step schemas and calculates aggregate gas, native value, and USDC budget requirements.
Bounded to a maximum of 16 steps per workflow to eliminate non-deterministic loop reinterpretation.
keeper_x402_settle)Parses RFC-7231 WWW-Authenticate and 402 Payment Required headers.
Generates localized EIP-712 permit signatures within a hard daily allowance (e.g. $10/day spend limit).
Automatically retries the paywalled request and returns clean data to the agent.
keeper_audit_verify)Builds cryptographic inclusion proofs for all relay actions using a flat array Merkle heap.
Allows agents to independently audit state proofs before triggering downstream dependent actions.
keeper_agent_balance)Real-time multi-chain RPC balance queries across Base, Arbitrum, Ethereum, and Creditcoin.
keeper_creditcoin_settle)Cryptographically verifies source-chain fulfillment receipts against on-chain Merkle roots using FlatMerkleTree in $\mathcal{O}(\log N)$ time.
Releases locked Creditcoin CTC escrow collateral directly to solvers upon valid cryptographic proof.
Real-time balance and gas headroom tracking across EVM chains (Arbitrum, Base, Mantle, Creditcoin).
Add this entry to your mcp_config.json:
{
"mcpServers": {
"agent-keeper": {
"command": "python3",
"args": ["-m", "agent_keeper.server"]
}
}
}git clone https://github.com/Ishant5436/agent-keeper-mcp.git
cd agent-keeper-mcp
# Setup environment
uv venv --python python3.12
source .venv/bin/activate
pip install -e .
# Run test suite
pytest============================== test session starts ==============================
platform darwin -- Python 3.12.13, pytest-9.1.1, pluggy-1.6.0
collected 106 items
tests/test_audit.py .... [ 3%]
tests/test_blackbox.py ................. [ 19%]
tests/test_creditcoin.py ..................................... [ 54%]
tests/test_fuzz_merkle.py .... [ 58%]
tests/test_merkle_tree.py .. [ 60%]
tests/test_relay.py .... [ 64%]
tests/test_schemas.py .......... [ 73%]
tests/test_server.py ....... [ 80%]
tests/test_whitebox.py ........... [ 90%]
tests/test_workflow.py ...... [ 96%]
tests/test_x402.py .... [100%]
============================= 106 passed in 13.38s =============================Deterministic Invariants: Bounded retry loops, minimum 2 runtime assertions per function, zero dynamic heap allocations on execution path.
Security Constraints: Enforces parameter bounds and rejects transactions exceeding pre-set gas ceilings.
KeeperHub PR #2188: https://github.com/KeeperHub/keeperhub/pull/2188
DoraHacks BUIDL #48196: https://dorahacks.io/buidl/48196
MIT License. Free for developers and autonomous agent operators.
Inspect the AI agent's live multi-chain onchain treasury balances, spent budget, and remaining limits.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does add useful context: the balance is live, multi-chain, and onchain, and 'Inspect' implies a read-only operation. But it does not explicitly state that it never mutates state, how freshness is guaranteed, or what happens when the optional address is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. It leads with the verb and resource, and every word contributes meaning relative to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return-value details do not need to be in the description. For an optional-parameter inspection tool, the description is largely enough to select and call it; the only notable gap is the meaning of the optional address parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional 'address' parameter with 0% description coverage, and the tool description does not mention it at all. An agent cannot determine whether the address selects a different agent, filters a specific chain, or is required to override a default target.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb, 'Inspect', and a clear resource: the AI agent's live multi-chain onchain treasury balances, spent budget, and remaining limits. This distinguishes it well from the sibling tools, which are about auditing, settling, and executing transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Inspect' implies the obvious use case — checking balances and budget before taking keeper actions — and the sibling names reinforce the distinction. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cryptographically verify the Merkle proof, inclusion block, and execution receipt of an agent transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | No | ||
| tx_hash | No | ||
| chain_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It reveals that verification happens, but it does not state whether the operation is read-only, what happens on a failed proof, whether any state is written, or what authentication/context requirements exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence with no filler or redundancy. It loses a point because it is so minimal that it omits parameter and usage context that would make it genuinely helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a sparse schema with no required parameters, no annotations, and 0% schema coverage, this description is not complete enough. It does not say how to obtain or supply the Merkle proof, whether task_id or tx_hash is expected as the primary lookup key, or how chain_id factors in. The output schema covers return values but not invocation prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate by explaining task_id, tx_hash, or chain_id. It does not clarify which identifier is sufficient, why both are nullable, or how chain_id is used. An agent has almost no basis for choosing parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Cryptographically verify') and a specific resource ('Merkle proof, inclusion block, and execution receipt of an agent transaction'). This distinguishes it from the sibling operations like keeper_execute_tx, keeper_agent_balance, and keeper_x402_settle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool instead of its siblings, nor does it mention what prior step produces the proof or receipt. The agent must infer usage purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute an onchain transaction through KeeperHub's MEV-protected relay with automated gas optimization.
| Name | Required | Description | Default |
|---|---|---|---|
| chain_id | No | ||
| value_wei | No | ||
| calldata_hex | No | 0x | |
| target_address | Yes | ||
| idempotency_key | No | ||
| max_priority_fee_gwei | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions MEV protection and gas optimization, but it fails to disclose that executing a transaction is irreversible, consumes gas, may require signing or funded accounts, and can revert.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the main action front-loaded and no filler. It is appropriately sized for the limited content it intends to convey.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, but the tool has no annotations, six parameters, and zero schema description coverage. A transaction-relay tool needs at least some note about side effects, prerequisites, or sibling-tool routing; this description is too sparse to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-level meaning. It does not explain chain_id, value_wei, calldata_hex, target_address, idempotency_key, or max_priority_fee_gwei, leaving the agent dependent on raw parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: executing an onchain transaction through KeeperHub's MEV-protected relay. It is specific about the resource and adds useful context about gas optimization, but it does not explicitly differentiate from sibling tools like keeper_audit_verify or keeper_x402_settle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when you need to execute an onchain transaction via KeeperHub. However, there are no explicit when-to-use conditions, prerequisites, or exclusions directing the agent away from alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autonomously settle an HTTP 402 Payment Required challenge using EIP-712 payment permits.
| Name | Required | Description | Default |
|---|---|---|---|
| amount_usdc | Yes | ||
| resource_url | Yes | ||
| token_address | No | ||
| recipient_address | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full disclosure burden. It discloses autonomy ('Autonomously') and the mechanism ('EIP-712 payment permits'), but it never states that this tool submits an on-chain payment, transfers USDC, spends funds, or has irreversible side effects. For a payment tool, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. Every phrase contributes meaning: the action, the trigger, the autonomy, and the mechanism.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though an output schema exists and return values need not be described, the definition still omits essential invocation context: what each parameter means, what side effects occur (spending funds), and any prerequisites such as wallet funding or token configuration. For an autonomous payment tool without annotations, this is not complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning for any of the four parameters. The agent must infer the semantics of amount_usdc, resource_url, token_address, and recipient_address from their names alone, and the null default for token_address is entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('settle') with a clear resource ('HTTP 402 Payment Required challenge') and a defined mechanism ('EIP-712 payment permits'). This makes the tool's purpose recognizable and distinguishable from siblings like keeper_execute_tx or keeper_audit_verify without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the exact trigger condition: use this tool when an HTTP 402 Payment Required challenge needs to be resolved autonomously. It does not explicitly name alternatives or exclusions, but the contextual signal is clear enough for an agent to select it in the intended scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0keeper_agent_balancekeeper_audit_verifykeeper_execute_txkeeper_x402_settleScored across 4 tools
Each tool targets a distinct operation: verifying proofs, settling payment challenges, checking balances, and executing transactions. There is no meaningful overlap between any two tools.
All tools share the keeper_ prefix and use snake_case, which keeps the set coherent. However, the verb/noun order is not perfectly consistent: execute_tx is verb-first while audit_verify and x402_settle are verb-last, and agent_balance has no explicit action verb.
Four tools is a well-scoped set for an agent treasury/execution keeper. Each tool serves a distinct core capability without unnecessary bloat or obvious triviality.
The set covers a coherent workflow: check balances, execute transactions, settle payment challenges, and verify audit proofs. Minor gaps exist such as transaction history or simulation, but these are not blocking for the stated purpose.
Monetization and execution gateway for autonomous AI agents on Base Mainnet
Attribution and settlement infrastructure for AI agent content access over HTTP 402 and MCP.
AI agent infrastructure for discovery, authorization, execution, identity, and signed receipts.
Autonomous AI agent selling pay-per-call skills settled with x402 micropayments (USDC).
