WritersLogic AI Agents (x402)

@writerslogic/ai-agents-mcp

An MCP server that exposes the WritersLogic x402 agent hub as tools. Each hub agent becomes one tool. Calls are priced in USDC and paid over x402 on Base, with no gas needed from the buyer.

The server is a thin client: it fetches the hub catalog, registers a tool per agent, forwards calls over HTTPS, and signs a payment authorization when the hub asks for one and your spending cap allows it.

Install

Requires Node.js 20 or later. No global install is needed; MCP clients run it with npx, which builds it from this repository on first run.

{

"mcpServers": { "writerslogic-ai-agents": { "command": "npx", "args": ["-y", "@writerslogic/ai-agents-mcp"], "env": { "AGENT_PRIVATE_KEY": "0x...", "MAX_USDC_PER_CALL": "1.00" } } } }

Put that block in your client's MCP configuration:

Omit AGENT_PRIVATE_KEY to browse and to see prices: paid tools then return the payment instructions instead of paying.

Configuration

Tools

Tools are discovered from the hub catalog (GET /api/v1/catalog?view=tools) and package index (GET /api/v1/packages) when the server starts, and refreshed on tools/list after ten minutes, so the live list is authoritative. Tool names are the agent or package id with every character outside A-Za-z0-9_ replaced by _. Each agent tool takes the agent's own input schema.

Small single-purpose checks ($0.005 each) are grouped into one tool per package, such as money_math_kit, so the tool list stays short. A package tool takes one of:

• {"describe": true, "check": " "}: free. Returns the check's input schema and an example input, from GET /api/v1/packages/ . Without check it lists the package's checks.
• {"check": " ", "input": {...}}: runs one check at its own price.
• {"calls": [{"check": " ", "input": {...}}, ...]}: runs up to 20 checks from the package under one $0.02 payment through /api/v1/micro-batch. Stateful and network checks are rejected before payment.

Arguments are validated locally first, so a check outside the package or a malformed call never reaches the hub. A hub without a package index gets one tool per agent. Agents at the time of writing:

Also always available, and free:

A paid result is the hub's JSON response, returned unchanged as text content.

How payment works

1. The tool POSTs your arguments to the agent endpoint.
2. If the hub answers 402, it sends a base64 PAYMENT-REQUIRED header (x402 v2) listing an exact scheme requirement: network eip155:8453, USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, an atomic amount (6 decimals), payTo, and the token's EIP-712 name and version.
3. If AGENT_PRIVATE_KEY is set and amount is at most MAX_USDC_PER_CALL, the client signs an EIP-3009 TransferWithAuthorization (EIP-712, USDC domain on chain 8453) for exactly that amount to payTo, valid for the requirement's timeout, with a random nonce.
4. It retries the same request once with the base64 PAYMENT-SIGNATURE header. The hub's facilitator submits the transfer and pays the gas.
5. The result is returned. If the retry is not accepted, the error is returned and nothing further is sent.

If no key is configured, or the price is over the cap, the tool returns an error that states the price, network, asset and payTo, and no signature is produced.

Provenance

Paid results carry a _provenance record next to data. Pass the whole {data, _provenance} object to verify_provenance to check it against the hub. The request body is forwarded as given.

Security

• The key stays local. AGENT_PRIVATE_KEY is read once from the environment, used only to sign typed data, and never logged or sent anywhere. Authorizations are signatures; the client never broadcasts a transaction.
• The cap is per call, not per session. An agent that calls tools in a loop can spend MAX_USDC_PER_CALL each time. Fund the wallet with only what you are willing to lose, and lower the cap to the most expensive tool you actually want to allow.
• Only USDC on Base is signed for. Challenges naming another network, asset, or transfer method are refused, so a malicious or compromised hub cannot ask for a different token. Base Sepolia (eip155:84532) USDC is also accepted for testing.
• Catalog entries are untrusted. Endpoints must resolve to the hub's own origin, ids and prices are validated, and redirects are never followed, so credentials and signatures are not sent to other hosts.
• Bounds. Requests are limited to 1 MiB, responses to 2 MiB, and every request has a timeout.
• Stdout is the MCP stream. Logs go to stderr only; they include the paying address and each payment amount, never the key.
• Anyone who holds a signed authorization before it expires could submit it, up to the signed amount and to payTo only.

Development

npm install

npm run build npm test

Tests run against a local mock hub and verify the EIP-3009 signature by recovering the signer, the cap at limit-1, limit and limit+1, and an end-to-end stdio session against dist/index.js. No network access or funds are involved.

License

Apache-2.0. Copyright 2026 WritersLogic.