MCP Tools

How available tools are generated from the live on-chain allow-list and each contract’s own spec — never a hardcoded list.

Generated, not hardcoded

Point stellar-agentgate at any passkey-kit wallet and agent-policy instance, and it exposes exactly the methods that wallet’s policy currently allows — no more, no less. This comes from two on-chain reads at server start, implemented in src/spec-to-tools.ts:

1. Read the policy's allow-list

   A read-only simulate of agent-policy.get_config(wallet) returns the configured Vec<AllowedCall> — each entry naming a {contract, fn_name, amount_arg_index}.

2. Fetch each target contract's own spec

   server.getContractWasmByContractId() + contract.Spec.fromWasm() gives the REAL parameter names and types for each allowed method — sourced from the contract’s own compiled spec, never guessed.

3. Build one MCP tool per allowed method

   A JSON Schema is generated from the real parameter types, and the tool’s description states its spend cap (or confirms it’s uncapped) in plain language.

If the wallet owner changes the allow-list on-chain — adds a method, tightens a cap — the next MCP server start reflects that immediately. There is no separate configuration file to keep in sync.

Address auto-fill

Every AllowedCall this project’s demo contract exposes takes the wallet’s own address as its primary parameter (deposit(from, amount), withdraw(to, amount)) — the overwhelmingly common shape for a policy-gated call. Rather than requiring an agent to know and pass a 56-character C.../G... address just to say “deposit 100,” any Address-typed parameter the caller omits defaults to the wallet’s own address:

src/mcp-server.ts

// Address-typed params an agent omits default to the wallet's own address --
// the overwhelmingly common case for a policy-gated call (the wallet acting
// on its own behalf), sparing the agent from having to know a 56-char C...
// address just to say "deposit 100".
function fillAddressDefaults(tool, args, walletId) { /* ... */ }

An agent can still pass an explicit address to override this — the default only fills gaps, it never overwrites a value the caller provided.

Spend-cap hints on the amount argument itself

Beyond the tool-level description ((spend-capped by argument index N) or (uncapped)), the JSON Schema property for that specific argument also carries the note — so an agent inspecting just that one field, not the whole tool description, still knows it’s the number that counts against the wallet’s rolling-window allowance:

"amount": {
  "type": "string",
  "description": "integer, as a decimal string (too large for a JSON number). Spend-capped: counts against this wallet's rolling-window allowance (see wallet_info for the current cap)."
}

Built by describeAmountArg in src/spec-to-tools.ts, keyed off the same amount_arg_index policy__ itself reads on-chain — the hint and the enforcement can never drift out of sync with each other.

Rejections are ordinary tool errors

When the policy rejects a call — cap exceeded, method not allowed — the MCP server does not crash or retry. It returns a normal MCP tool result with isError: true and the on-chain error surfaced in plain text:

{
  "content": [{ "type": "text", "text": "Rejected: simulation failed: HostError: Error(Auth, InvalidAction)" }],
  "isError": true
}

An agent (or the human watching it) sees a clean, expected failure — not an unhandled exception.

Try it directly

The policy-explain subcommand runs the same discovery logic and prints it in plain text, useful for a human auditing what an agent can currently do before trusting it:

stellar agentgate policy-explain

wallet:  C...
policy:  C...
agent:   G...

an agent holding this signer may currently do:
  - deposit(...) on C...  [uncapped]
  - withdraw(...) on C...  [spend-capped, arg #1]