Skip to main content

​
The layers

Vertical architecture diagram: AI Agent to MCP Server (off-chain, untrusted) down through Stellar RPC to the Smart Wallet, which requires the Agent Policy Contract to co-sign before invoking the Target Contract (on-chain, the only place authority lives).
Read this diagram as a trust gradient, not just a call sequence: everything above the “On-chain” boundary can be fully compromised — the agent, the MCP server process, the machine running it — without an attacker gaining any authority beyond what the policy contract already permits.

​
AI Agent

Any MCP-compatible client. It never sees a raw Stellar address it has to get right by hand — see MCP Tools for how tool schemas are generated and how missing addresses default sensibly.

​
stellar-agentgate MCP Server

A thin, replaceable layer (src/mcp-server.ts) that:
  1. Discovers the wallet’s current on-chain allow-list (agent-policy.get_config) and turns it into MCP tool definitions.
  2. Signs the resulting transaction with the agent’s own, independently powerless Ed25519 key.
  3. Surfaces on-chain rejections as ordinary MCP tool errors — never crashes, never retries around a rejection.
This process holds real key material (the agent’s signer), which is why it’s still worth protecting in the ordinary ways — but its compromise alone cannot move funds outside what the policy already allows.

​
Stellar RPC

Standard simulateTransaction → sign → sendTransaction → getTransaction flow, with one non-obvious wrinkle specific to this project’s custom-account wallet — see Signing Flow.

​
Smart Wallet (passkey-kit custom account)

The wallet’s own __check_auth decides, for every requested context, which registered signer(s) may authorize it. The agent’s signer is registered with SignerLimits that require the policy contract as a required co-signer for the target contract — not SignerLimits(None) (unlimited), which would let the agent’s signature alone satisfy auth with the policy never consulted at all. Getting this exactly backwards was a real bug caught during development; see the Security Model page for the full story.

​
Agent Policy Contract

The actual security boundary. See Security Model for the full decision logic.

​
Target Contract

Any Soroban contract the wallet owner chooses to expose — example-vault in this repository’s demo, but the pattern generalizes to any contract whose methods make sense to gate this way.

​
Why this shape, not a simpler one

Because the MCP server is exactly the thing that can be compromised, misconfigured, or have a bug. An off-chain check is advisory; an on-chain check enforced by the wallet’s own __check_auth cannot be skipped by anything that isn’t a registered, sufficiently-authorized signer.
A signer with SignerLimits(None) is unlimited — its own signature is sufficient for anything, and the wallet’s __check_auth never needs to consult any other signer. Scoping the agent’s signer to require the policy as a co-signer for the target contract is what actually forces every call through the policy’s allow-list and spend-cap logic.
Two wallets with different policies should expose different tools automatically. Reading agent-policy.get_config live means the MCP server’s tool list is always exactly what the current on-chain configuration allows — see MCP Tools.