Section 5
MCP tools
Five tools in front of an agent wallet. The model pays for what it uses and never holds the key.
5.1The five tools
| Tool | Sends a payment | What it does |
|---|---|---|
doei_balance | No | Read the wallet's private balance, what is left of the 24-hour budget, and the limits the owner set. Sends nothing. |
doei_quote | No | Price a payment (amount, protocol fee, total) and ask the owner's policy whether it would be allowed. Sends nothing. |
doei_pay | Yes | Send a confidential payment from the private balance. The owner's policy is enforced first; a refusal is returned as an error and nothing is sent. Returns a receipt. |
doei_fetch | Yes | HTTP request that settles a 402 Payment Required challenge: pays the stated price (within the policy and max_amount), retries with proof, and returns the response. |
doei_receipts | No | The payments this wallet made, newest first, with their amounts. Sends nothing. |
The descriptions above are the ones the model reads. This table and the server are generated from the same object, DOEI_TOOLS.
5.2Inputs
doei_balance
Takes no input.
doei_quote
| Input | Type | Meaning |
|---|---|---|
to | string | Solana address of the payee, base58. |
amount | string | Decimal amount in the wallet's asset, for example "0.004". |
doei_pay
| Input | Type | Meaning |
|---|---|---|
to | string | Solana address of the payee, base58. |
amount | string | Decimal amount in the wallet's asset, for example "0.004". |
memooptional | string | What the payment is for. Stored in the receipt only. |
doei_fetch
| Input | Type | Meaning |
|---|---|---|
url | string | The resource to request. https only. |
methodoptional | enum | Default GET. One of GET, POST, PUT, PATCH, DELETE. |
headersoptional | object | Request headers, name to value. |
bodyoptional | string | Request body, sent as is. |
max_amountoptional | string | Refuse a price above this. |
memooptional | string | What the payment is for. Stored in the receipt only. |
doei_receipts
| Input | Type | Meaning |
|---|---|---|
limitoptional | integer | How many to return, 1 to 100. Default 20. |
Amounts are decimal strings in the wallet's asset. The tools never accept a number, so nothing is rounded.
5.3A paid call
One doei_fetch call. The handler ran while this page was built, so the result is what a model receives. The signature is an example value.
{
"name": "doei_fetch",
"arguments": {
"url": "https://search.example/v1/search?q=gpu+spot+price",
"max_amount": "0.01",
"memo": "search: gpu spot price"
}
}{
"status": 200,
"content_type": "application/json",
"body": "{\"results\":3,\"top\":\"gpu spot pricing, november\"}",
"truncated": false,
"paid": {
"id": "aRzPKykodnPk-1",
"at": "2026-11-13T09:30:02.000Z",
"payee": "BAmBVKM2H2V6H3MxiGBpQmdVqz3vACgqUGUhJXnLti6z",
"payee_label": "search api",
"asset": "USDC",
"amount": "0.0042",
"fee": "0.000042",
"total": "0.004242",
"signature": "aRzPKykodnPkvP9Vntx7dwUXXf2nRmJECQDc3LsBPVskVQ54hPeMxA13xquzrJN5eQtE7HYiPVDrAEPpBY6c5w1",
"memo": "search: gpu spot price",
"resource": "https://search.example/v1/search?q=gpu+spot+price"
}
}5.4A refused call
When the policy says no, the tool returns an error result with the rule that refused it. The model can read the reason and change its plan. It cannot change the policy.
{
"name": "doei_pay",
"arguments": {
"to": "9uANPEJx6DrfqtjA29AkmgkDCd6v3HWrcsfukHhdg4iM",
"amount": "0.25",
"memo": "buy: gpu index, 30 days"
}
}{
"error": "POLICY_DENIED",
"message": "9uANPEJx6DrfqtjA29AkmgkDCd6v3HWrcsfukHhdg4iM is not on the allow-list.",
"rule": "PAYEE_NOT_ALLOWED"
}5.5Run the server
The server speaks MCP over stdio. Any MCP client that launches local servers can run it. It reads its configuration from the environment.
{
"mcpServers": {
"doei": {
"command": "node",
"args": ["packages/sdk/src/mcp/server.ts"],
"env": {
"DOEI_POLICY": "./doei.policy.json",
"DOEI_STATE": "./.doei/state.json",
"DOEI_RAIL": "memory"
}
}
}
}| Variable | Default | Meaning |
|---|---|---|
DOEI_POLICY | required | Path to the policy JSON file. Read again whenever it changes: new limits apply from the next payment. |
DOEI_STOP | next to the policy | Path of the owner's stop file. While it exists every payment is refused. doei stop and doei resume make and remove it, and so does the wallet page. |
DOEI_RAIL | memory | memory is a dry run with a simulated balance of 25. rings uses Privacy Rings. |
DOEI_STATE | none | Path to a JSON file for the spend ledger and receipts. Without it a restart resets the budget. |
DOEI_FEE_BPS | 100 on mainnet | Protocol fee in basis points. |
DOEI_FEE_COLLECTOR | the collector | Address the fee is paid to. |
DOEI_NETWORK | solana-devnet | With rings: solana-devnet or solana-mainnet. |
DOEI_KEYFILE | none | With rings: path to the agent's keypair file. |
DOEI_RPC_URL | none | With rings: Helius RPC endpoint. Required. |
DOEI_AUTO_DEPOSIT | on | With rings: the wallet moves what is sent to its address into the private balance by itself. off leaves it in public. |
DOEI_INDEXER_URL | none | With rings: indexer, if it is not the RPC provider's. |
DOEI_PROVER_URL | none | With rings: prover, if it is not the RPC provider's. |
5.6Embed it
If you already build the wallet in code, create the server from it and connect any transport.
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import type { AgentWallet } from "@doei/sdk";
import { createDoeiMcpServer } from "@doei/sdk/mcp";
declare const wallet: AgentWallet; // built with your rail and your policy
const server = createDoeiMcpServer(wallet);
await server.connect(new StdioServerTransport());5.7What the model cannot do
- It cannot read the key. The key is in the server process and no tool returns it.
- It cannot change the policy, revive a killed wallet, deposit or withdraw. Those are owner actions and are not tools.
- It cannot pay an address outside the allow-list, or go over a cap, by rephrasing the request.
- It can read the wallet's receipts, amounts included. Anything a tool returns enters the model's context, and from there your model provider's logs.