Content
# Axiom Agentic Tools
> Five JSON-output MCP tools for builders shipping agentic services on Base.
> x402-paid, no API keys, no accounts.
[](https://registry.modelcontextprotocol.io/v0/servers?search=axiom-agentic-tools)
[](https://smithery.ai/server/axiombot/axiom-agentic-tools)
[](https://github.com/coinbase/x402)
[](https://base.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
**Live deployment:** [`agentic.clawbots.org`](https://agentic.clawbots.org) · **MCP endpoint:** [`/api/agentic/mcp`](https://agentic.clawbots.org/api/agentic/mcp) · **OpenAPI:** [`/api/agentic/openapi.json`](https://agentic.clawbots.org/api/agentic/openapi.json)
---
## Overview
`axiom-agentic-tools` is a tiny, deterministic MCP server. Each of its five
tools answers one focused question for an autonomous agent or its builder:
- *"Where is this x402 endpoint leaking revenue?"*
- *"What does a deployable token spec look like for my agent?"*
- *"Which sequence of paid tools fits this budget?"*
- *"Is my repo ready for agent marketplaces?"*
- *"Which Base grant should I apply to next?"*
The server is callable three ways:
- **MCP** — streamable-HTTP, current protocol `2025-11-25`. Works in Claude
Code, Cursor, Cline, Windsurf, OpenAI Agent Builder, Smithery Toolbox.
- **HTTP + x402** — `POST /api/agentic/tools/<slug>` with an EIP-3009
`transferWithAuthorization` in the `X-PAYMENT` header.
- **A2A** — discoverable via `/.well-known/agent-card.json` on the parent.
Payments settle in USDC on Base through the Coinbase CDP facilitator (the
indexer source for [agentic.market](https://agentic.market) and the
[Coinbase Bazaar](https://github.com/coinbase/x402/tree/main/specs/extensions)).
## Features
- ✅ **x402 v2 envelope** — top-level `resource`, `extensions.bazaar`,
`PAYMENT-REQUIRED` response header per
[`specs/transports-v2/http.md`](https://github.com/coinbase/x402/blob/main/specs/transports-v2/http.md).
- ✅ **MCP `2025-11-25`** — `initialize`, `tools/list`, `tools/call`. Tool
call dispatches in-process; payment runs once, not twice.
- ✅ **Bazaar-ready** — `extensions.bazaar.info.input.type: "http"`,
output schema + example, route template, JSON Schema all in the 402.
- ✅ **GET discovery** — unauthenticated `GET` returns a 402 with the
envelope, so validators can introspect without a body.
- ✅ **Deterministic** — closed-vocabulary JSON outputs, schema-validated
on every response. No "the model said…" drift.
- ✅ **Free tier** — `repo-health-for-agents` runs at 50/day per IP with
no payment.
- ✅ **Rate-limited** — 60/hr per IP on paid tools, 10/hr on `?preview=1`.
## Tools
| Slug | Price | Returns |
|---|---|---|
| [`agent-revenue-optimizer`](tools/agent-revenue-optimizer) | $0.10 | Probes any x402 endpoint → closed-vocab verdict + 3–7 scored recommendations across pricing, bundling, discoverability, envelope, rate-limit, facilitator. |
| [`agent-token-strategy`](tools/agent-token-strategy) | $0.15 | Token spec for an autonomous agent: symbol, allocations, OZ template, fair-launch checklist, deploy cost estimate, risk list. |
| [`multi-agent-workflow-designer`](tools/multi-agent-workflow-designer) | $0.10 | DAG of public x402/MCP/REST tools that hits a goal under a USD budget, with per-step cost + latency + runnable curl. |
| [`base-builder-grant-finder`](tools/base-builder-grant-finder) | $0.05 | Ranked, deadline-aware list of open Base ecosystem grants / accelerators / hackathons / retro-funding. |
| [`repo-health-for-agents`](tools/repo-health-for-agents) | free* | 15-check 0–100 marketplace-readiness audit of a public GitHub repo. Each check carries pass/fail + URL evidence. |
*free at 50 calls/day/IP, then 402.*
## Quick start
### From an MCP-aware editor
Add this server to your MCP client config and `axiom-*` tools appear in
your tool palette immediately. No install, no auth.
#### Claude Code
```bash
claude mcp add --transport http axiom https://agentic.clawbots.org/api/agentic/mcp
```
#### Cursor
`Cursor → Settings → MCP → New MCP server`:
```json
{
"name": "axiom",
"type": "http",
"url": "https://agentic.clawbots.org/api/agentic/mcp"
}
```
#### Cline
`Cline → Settings → MCP servers → Configure MCP servers`:
```json
{
"mcpServers": {
"axiom": {
"type": "streamableHttp",
"url": "https://agentic.clawbots.org/api/agentic/mcp"
}
}
}
```
#### Windsurf
`Windsurf → Settings → MCP → Add server`:
```json
{
"mcpServers": {
"axiom": {
"serverUrl": "https://agentic.clawbots.org/api/agentic/mcp"
}
}
}
```
#### Smithery Toolbox
Install [from Smithery](https://smithery.ai/server/axiombot/axiom-agentic-tools)
with one click.
### From raw HTTP
```bash
# 1. Discovery — what does this endpoint cost?
curl -sX GET https://agentic.clawbots.org/api/agentic/tools/agent-revenue-optimizer \
-D /tmp/h | head -10
# HTTP/2 402
# PAYMENT-REQUIRED: <base64 envelope>
# 2. Decode the envelope:
grep -i payment-required: /tmp/h | cut -d' ' -f2- | tr -d '\r' | base64 -d | jq .
# 3. Sign + retry (@x402/fetch v2 handles this for you):
# npm i @x402/fetch @x402/evm viem
node -e "
import('@x402/fetch').then(async ({ wrapFetchWithPayment, x402Client }) => {
const { privateKeyToAccount } = await import('viem/accounts');
const { ExactEvmScheme } = await import('@x402/evm/exact/client');
const account = privateKeyToAccount(process.env.X402_PRIVATE_KEY);
const client = new x402Client().register('eip155:8453', new ExactEvmScheme(account));
const fetch = wrapFetchWithPayment(globalThis.fetch, client);
const r = await fetch('https://agentic.clawbots.org/api/agentic/tools/agent-revenue-optimizer', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ endpoint_url: 'https://example.com/api/probe' }),
});
console.log(await r.json());
});
"
```
## Installation (self-host)
You can host your own deployment — the only deploy target supported
today is Vercel.
```bash
git clone https://github.com/0xAxiom/axiom-agentic-tools.git
cd axiom-agentic-tools
npm install
cp .env.example .env.local # fill X402_PAY_TO + CDP_API_KEY_* (see Configuration)
npm run dev # vercel dev on :3000
```
Deploy:
```bash
vercel link # one-time
vercel --prod
```
Production smoke:
```bash
BASE=https://your-deployment.example npm test
```
## Configuration
All configuration is via environment variables. Copy `.env.example` and fill
in the blanks.
| Variable | Required | Default | Purpose |
|---|---|---|---|
| `X402_PAY_TO` | ✅ | — | Your wallet address for paid tool revenue (USDC on Base). |
| `X402_FACILITATOR_URL` | — | `https://api.cdp.coinbase.com/platform/v2/x402` | Facilitator endpoint. CDP is what Bazaar indexes. |
| `CDP_API_KEY_ID` | ✅ (if CDP) | — | CDP server-side credentials. Get them at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com). |
| `CDP_API_KEY_SECRET` | ✅ (if CDP) | — | — |
| `X402_NETWORK` | — | `base` | `base` or `base-sepolia`. |
| `BASE_RPC_URL` | — | `https://mainnet.base.org` | Base mainnet RPC. Use a private RPC in production. |
| `PUBLIC_BASE_URL` | — | (Vercel default) | Absolute base URL of your deployment. Populates manifest/OpenAPI/discovery links. |
| `GITHUB_TOKEN` | — | — | Lifts the rate limit on tools that read public GitHub repos. |
## Usage examples
### MCP `tools/list`
```bash
curl -s -X POST https://agentic.clawbots.org/api/agentic/mcp \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'
```
### MCP `tools/call`
```bash
curl -s -X POST https://agentic.clawbots.org/api/agentic/mcp \
-H 'content-type: application/json' \
-H "x-payment: $X_PAYMENT_BASE64" \
-d '{
"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"agent-revenue-optimizer","arguments":{"endpoint_url":"https://example.com/api/probe"}}
}'
```
### Free tier — `repo-health-for-agents`
```bash
curl -s -X POST https://agentic.clawbots.org/api/agentic/tools/repo-health-for-agents \
-H 'content-type: application/json' \
-d '{"repo":"your-org/your-repo"}'
```
50/day/IP free; over the limit returns the standard 402.
## Architecture
```
Client (Claude / Cursor / curl)
│
▼ POST /api/agentic/tools/<slug>
┌─────────────────────────────────────────────────┐
│ createAgenticRoute(spec, handler) │
│ ├─ CORS + OPTIONS │
│ ├─ Rate limit (per-IP, 3 buckets) │
│ ├─ Input validation (spec.inputSchema) │
│ ├─ checkAccess(req) ──► gate.mjs ──► x402 │
│ │ verify+settle through CDP facilitator │
│ ├─ tool handler({ input, payment }) │
│ └─ Output validation (spec.outputSchema) │
└─────────────────────────────────────────────────┘
│
▼ JSON result + X-PAYMENT-RESPONSE header
```
- **`api/agentic/mcp.mjs`** is an MCP transport. `tools/call` dispatches the
same registry → x402 → handler pipeline in-process — payment runs once,
never twice.
- **`api/_lib/x402.mjs`** builds the v2 envelope (`buildPaymentRequired`)
and shells out to the facilitator for verify/settle.
- **`tools/<slug>/spec.mjs`** is the single source of truth for each tool:
input/output schemas, price, examples, marketplace metadata, the bazaar
extension block. Validated at boot and at prebuild.
- **`scripts/generate-manifest.mjs`** regenerates `/api/agentic/manifest`,
`/api/agentic/openapi.json`, `/.well-known/agentic/tools/*.json`, and the
`/.well-known/mcp.json` server card from the registry.
Full reference: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md),
[`docs/DESCRIPTOR.md`](docs/DESCRIPTOR.md),
[`docs/DISCOVERY.md`](docs/DISCOVERY.md).
## Development
```bash
npm install
npm run prebuild # regenerate manifest + OpenAPI + .well-known
npm run dev # vercel dev on :3000
npm test # smoke (BASE=http://localhost:3000 by default)
npm run validate # surface-consistency check
```
To add a tool, follow [`CONTRIBUTING.md`](CONTRIBUTING.md) §"Adding a new tool".
### Verifying x402 v2 compliance
```bash
curl -sD- -X GET https://agentic.clawbots.org/api/agentic/tools/agent-revenue-optimizer \
| head -20
# Expect:
# HTTP/2 402
# PAYMENT-REQUIRED: <base64>
# Body:
# { "x402Version": 2, "resource": {…}, "accepts": [{ "amount": "100000", … }], "extensions": { "bazaar": {…} } }
```
The full compliance matrix lives in
[`docs/X402_V2_COMPLIANCE_REPORT.md`](docs/X402_V2_COMPLIANCE_REPORT.md).
## Discovery surfaces
| Surface | URL |
|---|---|
| MCP endpoint | `https://agentic.clawbots.org/api/agentic/mcp` |
| Tool manifest | `https://agentic.clawbots.org/api/agentic/manifest` |
| OpenAPI 3.1 | `https://agentic.clawbots.org/api/agentic/openapi.json` |
| Health probe | `https://agentic.clawbots.org/api/agentic/health` |
| `.well-known/agentic/tools/<slug>.json` | Per-tool descriptor (cached) |
| Bazaar extension schema | `https://agentic.clawbots.org/.well-known/schemas/x402-extension-bazaar-v2.json` |
## Security
See [SECURITY.md](SECURITY.md) for the disclosure process. Report
vulnerabilities privately via
[GitHub Private Vulnerability Reporting](https://github.com/0xAxiom/axiom-agentic-tools/security/advisories/new)
or email — **do not open public issues** for security findings.
## Contributing
Pull requests welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first — it's
short, and it'll save you a round trip on style and surface conventions.
## License
[MIT](LICENSE).
