> ## Documentation Index
> Fetch the complete documentation index at: https://acachete.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A stellar-cli plugin that lets an AI agent safely invoke Soroban contracts via MCP, gated by an on-chain policy signer instead of a trusted intermediary.

**Install:** `npm install -g stellar-agentgate` -- published on
[npm](https://www.npmjs.com/package/stellar-agentgate); source on
[GitHub](https://github.com/salazarsebas/teji).

## The problem

Most "an agent calls a smart contract" demos hand the agent a private key and hope the surrounding application code is careful. If that key leaks, or the application has a bug, the agent's blast radius is limited only by what the key can technically sign -- which, for a normal account, is everything.

**stellar-agentgate** takes a different position: the safety boundary belongs **on-chain**, as a real contract the agent's key cannot bypass, not in application code the agent (or an attacker who compromises it) could route around.

<Frame>
  <img src="https://mintcdn.com/acachete/KAJaZsJCqe34mxL9/images/diagrams/01-architecture.svg?fit=max&auto=format&n=KAJaZsJCqe34mxL9&q=85&s=08a4ecfd47bc0e74a5b1fbcf79e9288b" alt="stellar-agentgate system architecture: an AI agent talks to the MCP server off-chain, which submits a signed transaction to Stellar RPC; on-chain, the smart wallet requires the agent-policy contract to co-sign before any call reaches the target contract." width="1508" height="1931" data-path="images/diagrams/01-architecture.svg" />
</Frame>

## How it works, in one paragraph

An agent's Ed25519 key is registered on a [passkey-kit](https://github.com/stellar/passkey-kit) smart wallet with `SignerLimits` that make it powerless **alone** -- every call to a target contract additionally requires a Policy contract to co-sign. That Policy contract enforces a per-wallet, on-chain-configured allow-list (`{contract, method, capped argument}`) plus a cumulative rolling-window spend cap. An MCP server exposes exactly the methods the policy currently allows -- generated from the contract's own on-chain spec, not hardcoded -- so an agent's blast radius is bounded by the policy even if its key leaks in full.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build the contracts, run the test suite, and stand up a demo wallet in a few commands.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/concepts/architecture">
    The full call path from a natural-language request to an on-chain decision.
  </Card>

  <Card title="Security Model" icon="shield-halved" href="/concepts/security-model">
    Why the policy contract -- not the MCP server, not the agent's key -- is the real trust boundary.
  </Card>

  <Card title="MCP Tools" icon="wand-magic-sparkles" href="/concepts/mcp-tools">
    How available tools are generated from the live on-chain allow-list, not a static list.
  </Card>

  <Card title="Self-Service Onboarding" icon="user-plus" href="/guides/self-service-onboarding">
    Wire up your own wallet with one command -- `stellar agentgate init`.
  </Card>
</CardGroup>

## What's actually proven, not just claimed

Everything below runs against real Stellar testnet transactions -- nothing in this project is simulated or mocked at the integration layer.

<AccordionGroup>
  <Accordion title="An agent can invoke an allowed method">
    A restricted Ed25519 signer, holding no independent authority, deposits and withdraws through the smart wallet -- each call co-signed on-chain by the policy contract.
  </Accordion>

  <Accordion title="A call exceeding the spend cap is rejected on-chain">
    Not caught by application code -- the transaction itself fails with `Error(Auth, InvalidAction)` because `agent-policy`'s `policy__` rejected it during `__check_auth`.
  </Accordion>

  <Accordion title="A call to a disallowed method is rejected on-chain">
    Even a harmless, auth-satisfiable method call is denied if it isn't on the wallet's configured allow-list -- proving allow-list enforcement independent of any other failure mode.
  </Accordion>

  <Accordion title="The real, compiled MCP binary works end-to-end">
    A genuine `@modelcontextprotocol/sdk` client connects to the compiled `stellar-agentgate mcp` binary over stdio, lists the on-chain-generated tools, and drives the same allow/reject sequence through the actual plugin artifact -- not a dev-mode shortcut.
  </Accordion>
</AccordionGroup>

<Note>
  This documentation, and the diagrams throughout it, describe the exact code in this repository -- not an idealized or simplified version of it. Where a diagram references a specific error (`CallNotAllowed`, `ExceedsWindowCap`, `Error(Auth, InvalidAction)`), that error comes directly from `contracts/agent-policy/src/lib.rs`.
</Note>