Docs5MCP tools

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

ToolSends a paymentWhat it does
doei_balanceNoRead the wallet's private balance, what is left of the 24-hour budget, and the limits the owner set. Sends nothing.
doei_quoteNoPrice a payment (amount, protocol fee, total) and ask the owner's policy whether it would be allowed. Sends nothing.
doei_payYesSend 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_fetchYesHTTP 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_receiptsNoThe 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

InputTypeMeaning
tostringSolana address of the payee, base58.
amountstringDecimal amount in the wallet's asset, for example "0.004".

doei_pay

InputTypeMeaning
tostringSolana address of the payee, base58.
amountstringDecimal amount in the wallet's asset, for example "0.004".
memooptionalstringWhat the payment is for. Stored in the receipt only.

doei_fetch

InputTypeMeaning
urlstringThe resource to request. https only.
methodoptionalenumDefault GET. One of GET, POST, PUT, PATCH, DELETE.
headersoptionalobjectRequest headers, name to value.
bodyoptionalstringRequest body, sent as is.
max_amountoptionalstringRefuse a price above this.
memooptionalstringWhat the payment is for. Stored in the receipt only.

doei_receipts

InputTypeMeaning
limitoptionalintegerHow 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.

tools/call
{
  "name": "doei_fetch",
  "arguments": {
    "url": "https://search.example/v1/search?q=gpu+spot+price",
    "max_amount": "0.01",
    "memo": "search: gpu spot price"
  }
}
result
{
  "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.

tools/call
{
  "name": "doei_pay",
  "arguments": {
    "to": "9uANPEJx6DrfqtjA29AkmgkDCd6v3HWrcsfukHhdg4iM",
    "amount": "0.25",
    "memo": "buy: gpu index, 30 days"
  }
}
result, isError: true
{
  "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.

examples/mcp-config.json
{
  "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"
      }
    }
  }
}
VariableDefaultMeaning
DOEI_POLICYrequiredPath to the policy JSON file. Read again whenever it changes: new limits apply from the next payment.
DOEI_STOPnext to the policyPath 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_RAILmemorymemory is a dry run with a simulated balance of 25. rings uses Privacy Rings.
DOEI_STATEnonePath to a JSON file for the spend ledger and receipts. Without it a restart resets the budget.
DOEI_FEE_BPS100 on mainnetProtocol fee in basis points.
DOEI_FEE_COLLECTORthe collectorAddress the fee is paid to.
DOEI_NETWORKsolana-devnetWith rings: solana-devnet or solana-mainnet.
DOEI_KEYFILEnoneWith rings: path to the agent's keypair file.
DOEI_RPC_URLnoneWith rings: Helius RPC endpoint. Required.
DOEI_AUTO_DEPOSITonWith rings: the wallet moves what is sent to its address into the private balance by itself. off leaves it in public.
DOEI_INDEXER_URLnoneWith rings: indexer, if it is not the RPC provider's.
DOEI_PROVER_URLnoneWith 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.

examples/mcp-embed.ts
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.