Enables AI agents to perform pay-per-call queries and store versioned, task-scoped memory using blockchain-based payments.
Also known as groundhogday2011-byte/a2apay, a2apay-io
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 148
- Latest version
- 0.1.0
- Last commit
- Oct 8, 2026
- License
- —
What is a2apay MCP?
a2apay enables AI agents to perform pay-per-call queries and store versioned, task-scoped memory using blockchain-based payments.
Summary generated from the project's README
About a2apay MCP server
Autonomous agents that need to perform pay-per-call queries and maintain persistent, task-scoped memory can use this server to manage costs and state via blockchain payments. It provides tools for generating AI answers through the ask command and storing text records with optional tags using the remember command. The system operates on a free tier of five requests per day per caller, after which it automatically attempts to process payments using a USDC balance on the Base mainnet.
Developers can set up the server locally by installing the mcp package and configuring it in an MCP client like Claude Desktop. To move beyond the free tier, users must provide a private key via the A2APAY_PRIVATE_KEY environment variable to sign payment authorizations locally using the eth-account library. This setup ensures that the private key is never transmitted, as signing happens on the user's machine. The server implements the x402 protocol for exact EVM payments, allowing for granular, per-call transactions.
What you can do with it
- 1Querying AI answers via paymentsAsk an AI agent to provide a specific answer using the pay-per-call mechanism.
- 2Storing task-specific metadataSave simple text records and tags to keep track of agent progress.
Written from the project's README. Every use case is checked against a quote from it.
How to install a2apay MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall a2apay MCP in Claude Code
$ claude mcp add --env 'A2APAY_PRIVATE_KEY=<YOUR_A2APAY_PRIVATE_KEY>' a2apay -- uvx a2apay-ioInstall a2apay MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"a2apay": {
"command": "uvx",
"args": [
"a2apay-io"
],
"env": {
"A2APAY_PRIVATE_KEY": "<YOUR_A2APAY_PRIVATE_KEY>"
}
}
}
}Install a2apay MCP in VS Code
.vscode/mcp.json
{
"servers": {
"a2apay": {
"type": "stdio",
"command": "uvx",
"args": [
"a2apay-io"
],
"env": {
"A2APAY_PRIVATE_KEY": "<YOUR_A2APAY_PRIVATE_KEY>"
}
}
}
}Install a2apay MCP in VS Code CLI
$ code --add-mcp '{"name":"a2apay","type":"stdio","command":"uvx","args":["a2apay-io"],"env":{"A2APAY_PRIVATE_KEY":"<YOUR_A2APAY_PRIVATE_KEY>"}}'Install a2apay MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"a2apay": {
"command": "uvx",
"args": [
"a2apay-io"
],
"env": {
"A2APAY_PRIVATE_KEY": "<YOUR_A2APAY_PRIVATE_KEY>"
}
}
}
}Install a2apay MCP in Codex
$ codex mcp add a2apay --env 'A2APAY_PRIVATE_KEY=<YOUR_A2APAY_PRIVATE_KEY>' -- uvx a2apay-ioInstall a2apay MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.a2apay] command = "uvx" args = ["a2apay-io"] [mcp_servers.a2apay.env] A2APAY_PRIVATE_KEY = "<YOUR_A2APAY_PRIVATE_KEY>"
Install a2apay MCP in Gemini CLI
$ gemini mcp add -s user -e 'A2APAY_PRIVATE_KEY=<YOUR_A2APAY_PRIVATE_KEY>' a2apay uvx -- a2apay-ioInstall a2apay MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"a2apay": {
"command": "uvx",
"args": [
"a2apay-io"
],
"env": {
"A2APAY_PRIVATE_KEY": "<YOUR_A2APAY_PRIVATE_KEY>"
}
}
}
}Configuration
A2APAY_PRIVATE_KEYSecretBase mainnet wallet private key, only needed once the free tier (5 calls/day) is used up. Never required for free-tier-only usage.
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablegroundhogday2011-byte/a2apay is public and reachablegithub.com/groundhogday2011-byte/a2apay ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-08github.com/groundhogday2011-byte/a2apay ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from a2apay-ioPass
- No critical advisory in the package or its dependencies6 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHuba2apay
Python client for a2apay.io — pay-per-call AI answers and persistent memory for autonomous agents. No account, no API key.
pip install a2apay-io # free-tier only
pip install "a2apay-io[paid]" # adds real payment support (eth-account)
(The PyPI distribution is named a2apay-io — an unrelated package already
holds the bare a2apay name. The importable module is still a2apay.)
Quick start (free tier, zero setup)
Every call tries the free tier first automatically — 5 requests/day per caller, no wallet needed:
from a2apay import Agent
agent = Agent()
answer = agent.ask("What's 7 times 8?")
print(answer)
agent.remember("last_task", "processed invoice #4471", tags=["billing"])
With real payment (once the free tier is used up)
from a2apay import Agent
agent = Agent(private_key="0x...") # or set A2APAY_PRIVATE_KEY
answer = agent.ask("What's 7 times 8?")
The wallet needs a small USDC balance on Base mainnet ($0.028/call). The private key is used only to sign a payment authorization locally — it is never sent anywhere.
Checkpoint / resume (task memory)
Write versioned, task-scoped state and read it back later — even from a
different process. Each checkpoint() to the same key adds a new version
rather than overwriting, and resume() always returns the latest.
from a2apay import Agent
agent = Agent(private_key="0x...")
agent.checkpoint("invoice-batch-7", key="status", value="processed rows 1-400")
# ...process dies, or a second process picks up later...
agent2 = Agent(private_key="0x...") # same wallet
records = agent2.resume("invoice-batch-7")
print(records[0]["value"]) # "processed rows 1-400"
resume() always requires payment ($0.014/call) — there's no free tier
for reads yet, so it needs a configured wallet even for your first call.
checkpoint() follows the same free-tier-then-paid behavior as
remember().
What this honestly does and doesn't do
ask()returns a real AI-generated answer.remember()stores a flat key/value record with optional tags — this is simple text storage, not a document database. Values are stored as text.- Falls back to a real payment only when the free tier returns a
402; if noprivate_keyis configured at that point, it raises a clearA2ApayErrorrather than failing silently. - Payment signing uses
eth-account(maintained by the Ethereum Foundation ecosystem), implementing the real x402 "exact" EVM scheme per the x402 protocol spec.
MCP server
An MCP server (mcp_server.py) exposes ask and remember as MCP tools
for any MCP-aware agent or framework (Claude Desktop, etc.):
pip install "a2apay-io[mcp]"
python mcp_server.py
Add to an MCP client config:
{
"mcpServers": {
"a2apay": {
"command": "python",
"args": ["/absolute/path/to/mcp_server.py"],
"env": {"A2APAY_PRIVATE_KEY": "0x..."}
}
}
}
Honest scope note: remember is write-only — there's no memory read-back
tool because the live API doesn't have a read-back route yet.
Full API reference
See a2apay.io/openapi.yaml for the underlying HTTP API this wraps.
a2apay MCP questions
How do I add a2apay MCP to Claude Code?
Run claude mcp add --env 'A2APAY_PRIVATE_KEY=<YOUR_A2APAY_PRIVATE_KEY>' a2apay -- uvx a2apay-io in your terminal. Add --scope user to make it available in every project.
How do I add a2apay MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How much does it cost to use the AI query service?
There is a free tier of 5 requests per day per caller; after that, it costs approximately $0.028 per call using USDC on Base mainnet.
Can I read back the memory I have stored?
Currently, the remember tool is write-only because the live API does not yet support a read-back route.
Is my private key safe when making payments?
Yes, the private key is used to sign payment authorizations locally and is never sent to the server.