@agenttrust-sdk/mcp 0.2.5 → 0.3.0

package/dist/embedded-docs/integration-guides/x402-facilitator.mdx

@@ -1,39 +1,46 @@
 ---
-title: x402 facilitator
-description: Add AgentTrust decisions to an x402 facilitator without coupling to one vendor.
+title: x402 facilitator (generic)
+description: Add AgentTrust decisions to any x402 facilitator without coupling to one vendor.
 ---
 
-This guide is for a facilitator that already accepts x402 payment requests and wants AgentTrust decisions before settlement. If you are using Pay.sh, start with the [Pay.sh adapter guide](/integration-guides/pay-sh-adapter). If you are adding a new facilitator, start with the [adapter pattern](/integration-guides/facilitator-adapters).
+If you already accept x402 payment requests and want AgentTrust decisions before settlement, this is the guide. Generic shape — facilitator-specific quirks live in the adapter, not in the route layer.
+
+If you're using Pay.sh, [start there](/integration-guides/pay-sh-adapter). If you're adding a new facilitator from scratch, [start with the adapter contract](/integration-guides/facilitator-adapters).
 
 ## Integration points
 
 | Step | Facilitator action | AgentTrust call |
-| --- | --- | --- |
+|---|---|---|
 | 1 | receive x402 request or retry proof | `FacilitatorAdapter.parseRequest` |
-| 2 | translate into payer, payee, mint, amount, and policy ID | `VerifyContext` |
-| 3 | check policy | `gate_payment` or `gatePayment()` |
+| 2 | translate into payer, payee, mint, amount, policy ID | `VerifyContext` |
+| 3 | check policy | `gate_payment` simulation or [`gatePayment()`](/sdk/gate-payment) |
 | 4 | return x402 denial or validation need | `adapter.formatChallenge` |
-| 5 | settle payment | one signed transaction path |
+| 5 | settle payment | one signed transaction (gate + transfer + feedback) |
 | 6 | emit feedback | `adapter.emitFeedback` |
 
 ## Minimal Express mount
 
+The published SDK is the easy path:
+
 ```ts
 import express from "express";
+import { Keypair } from "@solana/web3.js";
 import { mountTrustGate } from "@agenttrust-sdk/trustgate/express";
 
 const app = express();
 app.use(express.json());
 
 await mountTrustGate(app, {
-  rpcUrl: process.env.SOLANA_RPC_URL!,
-  facilitatorKeypair,
-  defaultPolicyId: 1,
-  network: "solana-devnet",
-  atomicityEnforced: true,
+  rpcUrl:             process.env.SOLANA_RPC_URL!,
+  facilitatorKeypair: Keypair.fromSecretKey(/* facilitator key */),
+  defaultPolicyId:    1,
+  network:            "solana-devnet",
+  atomicityEnforced:  true,
 });
 ```
 
+Routes added: `POST /verify`, `POST /settle`, `POST /dispute`, `GET /receipt/:hash`. Full reference: [SDK → mountTrustGate](/sdk/mount-trustgate).
+
 ## Verify request shape
 
 ```http
@@ -41,39 +48,63 @@ POST /verify
 Content-Type: application/json
 
 {
-  "payerAgentAsset": "payer-agent-asset-pubkey",
-  "payeeAgentAsset": "payee-agent-asset-pubkey",
-  "amount": "1000000",
-  "mint": "mint-pubkey",
-  "policyId": 1
+  "payerAgentAsset": "<base58 pubkey>",
+  "payeeAgentAsset": "<base58 pubkey>",
+  "amount":          "1000000",
+  "mint":            "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "policyId":        1
 }
 ```
 
-For Pay.sh, the adapter reads this context from `paymentRequirements.extra.agentTrust`, verifies `serviceSignature`, derives `paymentIdHash` from `extra.memo`, and rejects mismatched `payTo` / `payeeRecipient` values.
+For Pay.sh, the adapter reads this context from `paymentRequirements.extra.agentTrust`, verifies `serviceSignature`, derives `paymentIdHash` from `extra.memo`, and rejects mismatched `payTo` / `payeeRecipient`.
 
 ## Denial response
 
 ```http
 HTTP/1.1 402 Payment Required
-X-Payment-Network: solana-devnet
 X-Agent-Trust-Decision: Deny
 X-Payment-Required: denied
 X-Payment-Reason-Code: 6
 X-Payment-Reason-Name: CounterpartyTierBelowMin
+X-Payment-Network: solana-devnet
 ```
 
+Reason codes are stable: 1..15. Full table: [Reference → DenyReason codes](/reference/deny-reason-codes).
+
 ## Validation response
 
 ```http
 HTTP/1.1 402 Payment Required
-X-Payment-Network: solana-devnet
 X-Agent-Trust-Decision: RequireValidation
 X-Payment-Required: validation
-X-Capability-Required: <32-byte-capability-hash>
+X-Capability-Required: 366c075140aa69746625d4b733b55e267fc5c28387fd6d1c24901976ee3ddc42
+X-Payment-Network: solana-devnet
 ```
 
-## Settlement rule
+The `X-Capability-Required` value is the 32-byte SHA-256 hash of the capability namespace name (e.g., `kyc.tier-1.v1`). Full lifecycle: [Capability namespaces](/integration-guides/capability-namespaces).
 
-The facilitator must keep the policy gate, token transfer, and feedback emission in one signed Solana path once the settlement builder is wired. The SDK makes that requirement explicit with `atomicityEnforced: true`.
+## Settlement rule
 
-Source: `trustgate/server/src/facilitators`, `trustgate/server/src/x402.ts`, `trustgate/sdk/src/express.ts`.
+The facilitator must keep the policy gate, token transfer, and feedback emission in **one** signed Solana transaction. The SDK enforces this via the `atomicityEnforced: true` literal-type guard. Splitting them silently corrupts `VelocityLedger` when a Token-2022 mint's `TransferHook` extension reverts the transfer. Full proof: [Verification → Atomic-tx invariant](/verification/atomic-tx-invariant).
+
+## Sources
+
+| File | Purpose |
+|---|---|
+| [`trustgate/server/src/x402.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/x402.ts) | x402 wire envelope helpers |
+| [`trustgate/sdk/src/express.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/sdk/src/express.ts) | Published Express middleware |
+| [`trustgate/server/src/facilitators/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators) | Per-facilitator adapter implementations |
+
+## Read next
+
+<Cards>
+  <Card title="Pay.sh adapter" href="/integration-guides/pay-sh-adapter">
+    The canonical implementation, end to end.
+  </Card>
+  <Card title="Facilitator adapters" href="/integration-guides/facilitator-adapters">
+    Five-method contract for new facilitators.
+  </Card>
+  <Card title="DenyReason codes" href="/reference/deny-reason-codes">
+    Complete table of reason codes 1..15 with remediation hints.
+  </Card>
+</Cards>

package/dist/embedded-docs/mcp/hosted-endpoint.mdx

@@ -0,0 +1,197 @@
+---
+title: Hosted HTTP endpoint
+description: The streamable-HTTP MCP transport at mcp.agenttrust.tech — semantics, healthz, session model, retry behaviour.
+---
+
+[`mcp.agenttrust.tech`](https://mcp.agenttrust.tech) is the hosted MCP HTTP endpoint. Always-on, devnet-bound, free to hit, no install required for clients that speak `StreamableHTTPServerTransport`.
+
+Hosted on Fly.io (Singapore region), `shared-cpu-1x@256MB`, two machines for HA, `min_machines_running = 1` so judges hitting the URL don't see a cold start. Source: [`mcp/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp). Deployed via `flyctl deploy --config mcp/fly.toml`.
+
+## Healthz
+
+```bash
+curl https://mcp.agenttrust.tech/healthz
+```
+
+Returns:
+
+```json
+{
+  "ok":             true,
+  "service":        "agenttrust-mcp",
+  "version":        "0.2.6",
+  "network":        "solana-devnet",
+  "rpcUrl":         "https://api.devnet.solana.com",
+  "uptimeSeconds":  60978,
+  "activeSessions": 0,
+  "toolCount":      18
+}
+```
+
+Health probes use this URL — Fly.io marks the machine healthy when it returns `ok: true`. Use it as a smoke check from CI.
+
+## Transport
+
+The endpoint speaks Model Context Protocol over `StreamableHTTPServerTransport`. The wire format is JSON-RPC 2.0; the MCP server uses HTTP POST for client-initiated messages and Server-Sent Events for server-initiated messages.
+
+### Initialize
+
+```http
+POST / HTTP/1.1
+Host: mcp.agenttrust.tech
+Content-Type: application/json
+
+{
+  "jsonrpc": "2.0",
+  "id":      1,
+  "method":  "initialize",
+  "params": {
+    "protocolVersion": "2025-03-26",
+    "capabilities":    {},
+    "clientInfo":      { "name": "my-client", "version": "0.1.0" }
+  }
+}
+```
+
+Response includes a `Mcp-Session-Id` header. Subsequent requests echo that header to bind the session.
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+Mcp-Session-Id: 9f3a…
+
+{
+  "jsonrpc": "2.0",
+  "id":      1,
+  "result": {
+    "protocolVersion": "2025-03-26",
+    "capabilities":    { "tools": {}, "resources": {}, "prompts": {} },
+    "serverInfo":      { "name": "agenttrust", "version": "0.2.6" }
+  }
+}
+```
+
+### Tools / call
+
+```http
+POST / HTTP/1.1
+Host: mcp.agenttrust.tech
+Content-Type: application/json
+Mcp-Session-Id: 9f3a…
+
+{
+  "jsonrpc": "2.0",
+  "id":      2,
+  "method":  "tools/call",
+  "params": {
+    "name":      "agenttrust_simulate_payment",
+    "arguments": {
+      "caller":      "4tSEHc2vCLqnYd8nK9jRa44vnn8JnPxUgxheEmhWQhRG",
+      "payer_agent": "5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y",
+      "payee_agent": "5PfaofvEUf3adtJwMho7zzbfvgxwxbvp2V5moqhtLK8y",
+      "amount":      "1000000",
+      "mint":        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "policy_id":   1
+    }
+  }
+}
+```
+
+Response (truncated):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id":      2,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{ \"kind\": \"Allow\" }"
+      }
+    ]
+  }
+}
+```
+
+Same wire shape as the stdio transport. Same 18 tools, same Zod schemas, same response format.
+
+## Session model — current quirk
+
+The hosted MCP wraps `StreamableHTTPServerTransport` in a singleton: one transport per Node process. The first connection establishes a session and is served normally; a second connection without `Mcp-Session-Id` (i.e., trying to start a parallel session) gets:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id":      <id>,
+  "error":   { "code": -32600, "message": "Server already initialized" }
+}
+```
+
+Real MCP clients pass `Mcp-Session-Id` and reuse a session — this is mostly invisible during normal use. It surfaces as soon as a second client connects without coordinating session IDs.
+
+Phase M flagged this as Bug #4. Fixing it requires restructuring the transport instantiation around a per-session map; tracked but not v1-blocking. Workaround: restart the Fly machine (`flyctl machines list --app agenttrust-mcp` → `flyctl machines restart …`) or wait for session timeout.
+
+## Auth
+
+The hosted endpoint has no authentication for read tools. Write tools require a `KEYPAIR_B58` environment variable on the *server*; the hosted instance doesn't have one set, so write tools surface the standard `signer required` error.
+
+For write-tool access from a hosted MCP context, run your own instance with your own keypair:
+
+```bash
+flyctl deploy --config mcp/fly.toml --remote-only --app my-mcp \
+  --env RPC_URL=https://api.devnet.solana.com \
+  --env NETWORK=solana-devnet
+flyctl secrets set KEYPAIR_B58=<base58-key> --app my-mcp
+```
+
+## RPC backend
+
+The hosted MCP queries Solana via `https://api.devnet.solana.com` by default. For mainnet (when AgentTrust deploys there), set `RPC_URL` and `NETWORK=solana-mainnet` on the Fly app via `flyctl secrets set`.
+
+For lower-latency setups, point at a private RPC (Helius, QuickNode, Triton):
+
+```bash
+flyctl secrets set RPC_URL=https://devnet.helius-rpc.com/?api-key=… --app agenttrust-mcp
+```
+
+## CORS
+
+The hosted endpoint accepts cross-origin requests from any origin (no auth, no cookies, public devnet data). The MCP wire format uses application/json POSTs which trigger preflight; the server returns the standard `Access-Control-Allow-*` headers.
+
+## Self-host
+
+Run your own HTTP transport locally:
+
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=8765 node ./mcp/dist/index.js
+```
+
+Behind any reverse proxy (Caddy, nginx, Vercel, Fly.io) this surfaces as a public hosted endpoint. Same Zod schemas, same tool catalog. Caddyfile example:
+
+```
+mcp.your-domain.tld {
+  reverse_proxy localhost:8765
+}
+```
+
+## Validation
+
+Phase M end-to-end test against the hosted endpoint:
+
+| Check | Result |
+|---|---|
+| `GET /healthz` | 200, returns `version: "0.2.6"`, `toolCount: 18` |
+| `POST /` initialize | 200, returns matching `serverInfo`, `Mcp-Session-Id` header set |
+| `tools/list` | 18 tools, exact match with stdio |
+| `tools/call agenttrust_simulate_payment` | `{ kind: "Allow" }` for the tier-3 demo agent |
+| `tools/call agenttrust_get_policy` | matching PDA `975DgYCY…` between stdio and HTTP |
+
+Full report: [`docs/proofs/phase-m-mcp-e2e.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-m-mcp-e2e.md) §M2.
+
+## Source
+
+- Server entry: [`mcp/src/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/index.ts)
+- HTTP transport: [`mcp/src/server.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/src/server.ts)
+- Fly config: [`mcp/fly.toml`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/fly.toml)
+- Dockerfile: [`mcp/Dockerfile`](https://github.com/agenttrust-labs/agenttrust/blob/main/mcp/Dockerfile)

package/dist/embedded-docs/mcp/index.mdx

@@ -0,0 +1,108 @@
+---
+title: MCP server
+description: Drop @agenttrust-sdk/mcp into Claude Desktop or Cursor and query the deployed AgentTrust programs in natural language. Eighteen tools, four resources, three prompts.
+---
+
+`@agenttrust-sdk/mcp@0.2.6` is the Model Context Protocol server for AgentTrust. Stdio binary published on npm; hosted HTTP transport at [`mcp.agenttrust.tech`](https://mcp.agenttrust.tech). Eighteen tools split into ten read-only, five write (require a signing keypair), and three discovery / docs-search.
+
+The MCP server is a thin façade over [`@agenttrust-sdk/trustgate`](/sdk). PDA derivation, IDL loading, and `gate_payment` simulation live in the SDK; the MCP server exposes them with stable Zod schemas to LLM clients.
+
+Source: [`mcp/`](https://github.com/agenttrust-labs/agenttrust/tree/main/mcp). License: MIT.
+
+## What you get
+
+| | Count | Where |
+|---|---:|---|
+| Tools | 18 | 10 read · 5 write · 3 discovery |
+| Resources | 4 | devnet program manifest, docs corpus, demo source files |
+| Prompts | 3 | `agenttrust_audit_payment`, `agenttrust_setup_agent`, `agenttrust_explain_failure` |
+| Transports | 2 | stdio (default) · streamable HTTP |
+| Networks | 2 | `solana-devnet` (default) · `solana-mainnet` (when deployed) |
+
+## Quick start — Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL": "https://api.devnet.solana.com",
+        "NETWORK": "solana-devnet"
+      }
+    }
+  }
+}
+```
+
+Drop into `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Restart Claude Desktop. Eighteen tools become available in chat. Full setup including write-tool keypair, Cursor config, and HTTP transport: [Install](/mcp/install).
+
+## What it looks like in use
+
+Once installed, ask Claude Desktop:
+
+- *"What demo agents are available on AgentTrust?"* → `agenttrust_demo_state` returns three pre-warmed counterparties with asset pubkeys + Explorer URLs.
+- *"Simulate a 5-USDC payment from the tier-3 demo agent to the tier-0 demo agent against policy 1. What does the gate decide?"* → `agenttrust_simulate_payment` returns `Deny / SpendingPerTxExceeded` with the decoded reason.
+- *"Pull the policy for agent <asset> ID 1 and tell me the spending caps."* → `agenttrust_get_policy` returns the decoded `PolicyAccount` PDA — every spending cap, velocity threshold, counterparty tier requirement, and required capability hash.
+- *"Why would a payment with reason code 6 fail, and how do I fix it?"* → `agenttrust_explain_decision` returns `CounterpartyTierBelowMin` with remediation hint.
+- *"Search the AgentTrust docs for the validation registry data flow."* → `agenttrust_docs` returns ranked hits with excerpts.
+- *"Walk me through adding a new x402 facilitator adapter."* → `agenttrust_facilitator_walkthrough` returns the canonical guide.
+
+Phase P validated all 10 scenarios with a real LLM client (Claude `sonnet` via the official `claude` CLI) — 7/10 strict pass, 3 false negatives that the LLM recovered from via context-gathering. Full report: [`docs/proofs/phase-p-llm-routing.md`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/phase-p-llm-routing.md).
+
+## Hosted vs stdio
+
+| Mode | When | Setup |
+|---|---|---|
+| **Stdio** (default) | Claude Desktop, Cursor, any local MCP client | `npx -y @agenttrust-sdk/mcp` — no install, no clone |
+| **Hosted HTTP** | Cloud agents, OpenAI Agents SDK, any `StreamableHTTPServerTransport` client | `https://mcp.agenttrust.tech` — Fly.io, always-on, 0 cold starts |
+
+Health check the hosted endpoint:
+
+```bash
+curl https://mcp.agenttrust.tech/healthz
+# → {"ok":true,"service":"agenttrust-mcp","version":"0.2.6","network":"solana-devnet","toolCount":18,…}
+```
+
+Full hosted-endpoint reference: [Hosted endpoint](/mcp/hosted-endpoint).
+
+## Architecture
+
+```
+mcp/src/
+├── index.ts        — entry point + transport selector
+├── server.ts       — MCP Server with tools/resources/prompts wired up
+├── config.ts       — env parsing
+├── chain.ts        — thin façade over @agenttrust-sdk/trustgate
+├── tools/
+│   ├── read/        — 10 read tools
+│   ├── write/       — 5 write tools
+│   └── discovery/   — 3 discovery tools
+├── resources/
+│   ├── docs.ts      — MDX corpus indexer (path-traversal-safe)
+│   └── programs.ts  — devnet program manifest as JSON resource
+└── prompts/
+    ├── audit-payment.ts
+    ├── setup-agent.ts
+    └── explain-failure.ts
+```
+
+Chain logic — PDA derivation, IDL loading, `gate_payment` simulation — lives in `@agenttrust-sdk/trustgate`. The MCP server is a façade. If a helper is missing in the SDK, it lands in the SDK and re-exports through the MCP — never forks chain logic into `mcp/`.
+
+## Read next
+
+<Cards>
+  <Card title="Install" href="/mcp/install">
+    Claude Desktop, Cursor, hosted HTTP, env vars, write-tool keypair.
+  </Card>
+  <Card title="Tools" href="/mcp/tools">
+    All 18 tools — 10 read, 5 write, 3 discovery — with input/output shape.
+  </Card>
+  <Card title="Resources" href="/mcp/resources">
+    Four MCP resource URIs — devnet program manifest, docs corpus mirror.
+  </Card>
+  <Card title="Prompts" href="/mcp/prompts">
+    Three guided workflows — audit a payment, set up an agent, explain a failure.
+  </Card>
+</Cards>

package/dist/embedded-docs/mcp/install.mdx

@@ -0,0 +1,183 @@
+---
+title: Install
+description: Wire @agenttrust-sdk/mcp into Claude Desktop, Cursor, or any MCP-capable client — stdio or hosted HTTP.
+---
+
+Three install paths: Claude Desktop (one command), Cursor, or any generic stdio MCP client. Plus the always-on hosted HTTP endpoint at [`mcp.agenttrust.tech`](https://mcp.agenttrust.tech) for cloud agents.
+
+## Claude Desktop (recommended)
+
+Add to your config — `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL": "https://api.devnet.solana.com",
+        "NETWORK": "solana-devnet"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Eighteen tools are now available in chat. No clone, no local build.
+
+### Local clone (for development)
+
+If you want to iterate on the MCP server's source, swap the `command`/`args`:
+
+```json
+"command": "node",
+"args": ["/absolute/path/to/agenttrust/mcp/dist/index.js"]
+```
+
+Or run the helper that wires the local path automatically:
+
+```bash
+mcp/scripts/install-claude-desktop.sh
+```
+
+The script edits the Claude Desktop config in place. It backs up the prior config to `claude_desktop_config.json.bak.<timestamp>` so you can revert.
+
+## Cursor
+
+Cursor's MCP config lives at `~/.cursor/mcp.json` (or per-workspace `.cursor/mcp.json`). Same shape as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"]
+    }
+  }
+}
+```
+
+## Generic stdio MCP client
+
+The package ships a binary entry point. Once installed:
+
+```bash
+pnpm add @agenttrust-sdk/mcp
+node ./node_modules/@agenttrust-sdk/mcp/dist/index.js   # stdio transport, default
+```
+
+The server speaks MCP over stdin/stdout. Any compliant MCP client attaches by spawning this command.
+
+## Hosted HTTP endpoint
+
+The public hosted MCP HTTP endpoint is **already live**:
+
+```
+https://mcp.agenttrust.tech
+```
+
+Health check:
+
+```bash
+curl https://mcp.agenttrust.tech/healthz
+# → {"ok":true,"service":"agenttrust-mcp","version":"0.2.6","network":"solana-devnet","toolCount":18,…}
+```
+
+Hosted on Fly.io (Singapore region, shared-cpu-1x@256MB, always-on with auto-resume on idle). Use this URL in any MCP client that speaks `StreamableHTTPServerTransport` — no local install required. Full hosted-endpoint reference: [Hosted endpoint](/mcp/hosted-endpoint).
+
+To run your own HTTP transport locally:
+
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=8765 node ./mcp/dist/index.js
+```
+
+Behind any reverse proxy (Caddy, nginx, Vercel, Fly.io) this surfaces as a public hosted endpoint.
+
+## Write tools — adding a keypair
+
+The five write tools (`agenttrust_init_policy`, `agenttrust_set_killswitch`, `agenttrust_request_validation`, `agenttrust_respond_to_validation`, `agenttrust_emit_feedback`) require a signing keypair. Add `KEYPAIR_B58` to the `env` block:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL":     "https://api.devnet.solana.com",
+        "NETWORK":     "solana-devnet",
+        "KEYPAIR_B58": "<base58-encoded 64-byte secret key>"
+      }
+    }
+  }
+}
+```
+
+Without `KEYPAIR_B58`, write tools surface a clear `signer required` error. Read and discovery tools never need it.
+
+Convert a Solana CLI keypair to base58:
+
+```bash
+solana-keygen recover --output-format json -k ~/.config/solana/id.json | jq -r '.privateKey' \
+  | python3 -c "import sys, base58, json; print(base58.b58encode(bytes(json.loads(sys.stdin.read()))).decode())"
+```
+
+Or use the `bs58` CLI:
+
+```bash
+cat ~/.config/solana/id.json | jq -r '.[0:64]' | npx bs58 encode
+```
+
+## Environment variables
+
+| Var | Default | Effect |
+|---|---|---|
+| `RPC_URL` | devnet RPC | Solana RPC endpoint |
+| `NETWORK` | `solana-devnet` | `solana-devnet` or `solana-mainnet`. Drives Quantu program IDs. |
+| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. Required for write tools. |
+| `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `MCP_HTTP_PORT` | `8765` | Port for HTTP transport |
+| `POLICY_VAULT_PROGRAM_ID` | devnet ID | Override `policy_vault` program ID |
+| `TRUSTGATE_PROGRAM_ID` | devnet ID | Override `trustgate` program ID |
+| `VALIDATION_REGISTRY_PROGRAM_ID` | devnet ID | Override `validation_registry` program ID |
+| `MCP_DEFAULT_FACILITATOR` | unset | Default facilitator name in tool replies |
+| `MCP_DOCS_DIR` | repo `docs-site/content/docs` | Override the docs corpus root (tests) |
+| `PAY_SH_DEMO_STATE_FILE` | bundled demo state | Override the demo state file |
+
+## Build + test from source
+
+```bash
+git clone https://github.com/agenttrust-labs/agenttrust && cd agenttrust
+pnpm install
+pnpm --filter ./trustgate/sdk run build   # MCP depends on the SDK build output
+pnpm --filter ./mcp run build
+pnpm --filter ./mcp test                  # 76 unit tests, no chain access
+INTEGRATION=1 pnpm --filter ./mcp test:integration   # devnet round-trip
+```
+
+## IDL fetch (verify on-chain truth)
+
+All three Anchor IDLs are published on devnet:
+
+```bash
+anchor idl fetch 8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR --provider.cluster devnet  # policy_vault
+anchor idl fetch HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N --provider.cluster devnet  # trustgate
+anchor idl fetch Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv --provider.cluster devnet  # validation_registry
+```
+
+The MCP server bundles snapshots at `mcp/src/idl/*.json` as a defensive fallback (saves an RPC round-trip on cold start; keeps the server bootable in offline / air-gapped harnesses). Latest evidence snapshot: [`docs/proofs/idl-on-chain.json`](https://github.com/agenttrust-labs/agenttrust/blob/main/docs/proofs/idl-on-chain.json).
+
+## Read next
+
+<Cards>
+  <Card title="Tools" href="/mcp/tools">
+    Eighteen tools with input/output shape.
+  </Card>
+  <Card title="Hosted endpoint" href="/mcp/hosted-endpoint">
+    HTTP transport semantics, sessions, healthz schema.
+  </Card>
+  <Card title="Prompts" href="/mcp/prompts">
+    Three guided workflows for LLM clients.
+  </Card>
+</Cards>