@agenttrust-sdk/mcp 0.2.6 → 0.3.0

package/dist/embedded-docs/integration-guides/pay-sh-adapter.mdx

@@ -1,33 +1,52 @@
 ---
 title: Pay.sh adapter
-description: The live Pay.sh + AgentTrust integration path.
+description: Walk the live Pay.sh + AgentTrust integration end to end — challenge, retry, settle, feedback, with hosted-demo paths and the SERVICE-signed envelope contract.
 ---
 
-Pay.sh is the first concrete AgentTrust facilitator adapter. It translates Pay.sh's x402 headers and `PaymentRequirements` body into the `VerifyContext` that the on-chain policy path understands.
-
-Pay.sh launch reference: [Solana Foundation launch note](https://solana.com/news/solana-foundation-launches-pay-sh-in-collaboration-with-google-cloud).
+Pay.sh is the Solana Foundation's first x402 facilitator, [launched 2026-05-05 with Google Cloud](https://solana.com/news/solana-foundation-launches-pay-sh-in-collaboration-with-google-cloud). AgentTrust ships day-one Pay.sh integration as the canonical `FacilitatorAdapter` implementation. Source: [`trustgate/server/src/facilitators/pay-sh/`](https://github.com/agenttrust-labs/agenttrust/tree/main/trustgate/server/src/facilitators/pay-sh).
 
 ## What the adapter does
 
-| Stage | Pay.sh / x402 surface | AgentTrust action |
-| --- | --- | --- |
+| Stage | x402 / Pay.sh wire shape | AgentTrust action |
+|---|---|---|
 | Initial request | no payment proof | emit `402 Payment Required` with a base64 x402 v2 envelope |
-| Challenge | `paymentRequirements.extra.agentTrust` | include payer agent, payee agent, payee recipient, policy ID, `issuedAt`, and `serviceSignature` |
-| Retry | `PAYMENT-SIGNATURE` or `X-PAYMENT` | parse proof and rebuild `VerifyContext` |
-| Policy | `VerifyContext` | run the gate decision |
+| Challenge | `paymentRequirements.extra.agentTrust` | include payer agent, payee agent, payee recipient, policy ID, `issuedAt`, `serviceSignature` |
+| Retry | `PAYMENT-SIGNATURE` or `X-PAYMENT` header | parse proof, rebuild `VerifyContext` |
+| Policy | `VerifyContext` | run `gate_payment` decision |
 | Allow | signed payment proof | validate transfer fields, emit feedback, forward resource |
-| Deny | gate decision | return `402` with reason code and reason name |
+| Deny | gate decision | return `402` with reason code + reason name |
 
-## Files to read
+## Hit the live demo
 
-| File | Purpose |
-| --- | --- |
-| `trustgate/server/src/facilitators/pay-sh/index.ts` | the five-method `PaySh` class |
-| `trustgate/server/src/facilitators/pay-sh/schemas.ts` | strict Zod wire schemas |
-| `trustgate/server/src/facilitators/pay-sh/sig.ts` | SERVICE challenge signature helpers |
-| `trustgate/server/src/facilitators/pay-sh/proof-validator.ts` | replay, self-pay, amount, mint, recipient checks |
-| `trustgate/server/src/facilitators/pay-sh/feedback.ts` | idempotent feedback emission |
-| `examples/pay-sh-demo/src/middleware.ts` | Express route bridge from Pay.sh retry to AgentTrust |
+[`demo.agenttrust.tech`](https://demo.agenttrust.tech) runs the full Pay.sh + AgentTrust pipeline against deployed devnet programs. With no payment proof:
+
+```bash
+curl -i https://demo.agenttrust.tech/protected
+```
+
+Returns `HTTP/2 402` with a SERVICE-signed `payment-required` envelope. With Pay.sh installed, let the CLI pay and retry:
+
+```bash
+pay --sandbox curl https://demo.agenttrust.tech/protected
+```
+
+The demo seeds three deterministic counterparties. Drive each branch by passing the matching `X-Demo-Payer-Agent` header:
+
+```bash
+# Allow path (tier 3)
+PAYER=$(curl -s https://demo.agenttrust.tech/health | jq -r '.counterparties[2].agent')
+pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" https://demo.agenttrust.tech/protected
+
+# Deny path (tier 0)
+PAYER=$(curl -s https://demo.agenttrust.tech/health | jq -r '.counterparties[0].agent')
+pay --sandbox curl -H "X-Demo-Payer-Agent: $PAYER" https://demo.agenttrust.tech/protected
+```
+
+| Counterparty tier | Decision |
+|---:|---|
+| 0 | `402 Deny — CounterpartyTierBelowMin` |
+| 1 | `402 Deny — CounterpartyTierBelowMin` |
+| 3 | `200 Allow + X-Payment-Receipt` |
 
 ## SERVICE-signed challenge
 
@@ -44,58 +63,49 @@ The SERVICE emits a signed challenge when it returns the Pay.sh `402` response.
 - policy ID
 - payment ID hash
 
-`PaySh.parseRequest()` verifies that signature against the facilitator public key before it accepts the request. This closes the race window where a forged `paymentRequirements` envelope could be raced against the legitimate one.
-
-## Run the demo
+`PaySh.parseRequest()` verifies that signature against the facilitator public key before accepting the request. This closes the race window where a forged `paymentRequirements` envelope could race a legitimate one.
 
-```bash
-pnpm --filter ./examples/pay-sh-demo dev
-```
+## Files to read in repo
 
-```bash
-pay --sandbox curl https://demo.agenttrust.tech/protected
-```
-
-The demo uses three deterministic counterparties:
-
-| Counterparty tier | Expected result |
-| --- | --- |
-| 0 | `402 Deny` with `CounterpartyTierBelowMin` |
-| 1 | `402 Deny` with `CounterpartyTierBelowMin` |
-| 3 | `200 Allow` with `X-Payment-Receipt` |
-
-Get the exact payer agent keys:
-
-```bash
-curl -s https://demo.agenttrust.tech/health | jq '.counterparties'
-```
+| File | Purpose |
+|---|---|
+| [`facilitators/pay-sh/index.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/index.ts) | The five-method `PaySh` class |
+| [`facilitators/pay-sh/schemas.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/schemas.ts) | Strict Zod wire schemas |
+| [`facilitators/pay-sh/sig.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/sig.ts) | SERVICE challenge signature helpers |
+| [`facilitators/pay-sh/proof-validator.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/proof-validator.ts) | Replay, self-pay, amount, mint, recipient checks |
+| [`facilitators/pay-sh/feedback.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/feedback.ts) | Idempotent feedback emission |
+| [`examples/pay-sh-demo/src/middleware.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/examples/pay-sh-demo/src/middleware.ts) | Express bridge from Pay.sh retry to AgentTrust |
 
 ## Production wiring
 
-The demo proves the pipeline without requiring devnet RPC in CI. The server package carries the real devnet Anchor route: `trustgate/server/src/chain.ts` loads deployed program IDLs, `/verify` simulates `gate_payment`, and `/settle` delegates proof validation plus feedback emission through the active adapter.
+The demo proves the pipeline without requiring devnet RPC in CI. The server package carries the real devnet path: [`trustgate/server/src/chain.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/chain.ts) loads deployed program IDLs, `/verify` simulates `gate_payment`, and `/settle` delegates proof validation plus feedback emission through the active adapter.
 
-Production swaps three dependency seams:
+Production swaps three dependency seams the demo stubs:
 
 ```ts
+import { PaySh } from "./facilitators/pay-sh";
+
 const adapter = new PaySh({
   signingNetwork: "solana-devnet",
-  feePayer: facilitator.publicKey,
-  validateOnChainTx,
-  emitFeedbackCpi,
-  priorEmissionLookup,
-  replayCache,
-  signDecision,
+  feePayer:       facilitator.publicKey,
+  validateOnChainTx,        // makeValidateOnChainTx({ connection, … })
+  emitFeedbackCpi,          // makeEmitFeedbackCpi({ connection, programIds, … })
+  priorEmissionLookup,      // makePriorEmissionLookup({ connection, programId })
+  replayCache,              // ReplayCache (in-memory by default)
+  signDecision,             // signs canonical decision bytes with facilitator key
 });
 ```
 
 | Dependency | Production implementation |
-| --- | --- |
+|---|---|
 | `validateOnChainTx` | parse the confirmed SPL transfer transaction from RPC |
 | `emitFeedbackCpi` | build and send `trustgate::emit_feedback` through Anchor |
 | `priorEmissionLookup` | read the `FeedbackEmissionLog` PDA by payment hash |
 | `signDecision` | sign canonical decision bytes with the facilitator key |
 
-## Failure cases to keep
+The factories (`makeValidateOnChainTx`, `makeEmitFeedbackCpi`, `makePriorEmissionLookup`) are SDK exports — see [SDK → Exports reference](/sdk/exports-reference).
+
+## Failure cases the adapter must keep
 
 Do not remove these checks when adapting Pay.sh into a production server:
 
@@ -105,6 +115,32 @@ Do not remove these checks when adapting Pay.sh into a production server:
 - reject `payTo` / `payeeRecipient` mismatch
 - reject expired challenges
 - reject replayed proof bindings
-- reject transfer authority equal to facilitator fee payer
+- reject transfer authority equal to facilitator fee payer (self-pay defense)
+
+These are part of the adapter, not the route layer. The Pay.sh adapter's [`proof-validator.ts`](https://github.com/agenttrust-labs/agenttrust/blob/main/trustgate/server/src/facilitators/pay-sh/proof-validator.ts) is the reference implementation.
+
+## Live evidence
+
+Real atomic-settlement trace on devnet (2026-05-06):
+
+| Step | Tx |
+|---|---|
+| Signed SPL `transferChecked` | [`5iV8EYmJh9XS…`](https://explorer.solana.com/tx/5iV8EYmJh9XSXkBQrrbQ5L9kmBQabD3G3RXVPsHn9PkWceTFoeRsUV4g5aLLzZyRjeBoFvK3Woxr2cZa5xeUwhVD?cluster=devnet) |
+| `emit_feedback` PDA-signed CPI | [`jMobmWJUAXuL8…`](https://explorer.solana.com/tx/jMobmWJUAXuL8FmQujfxW9NmeMbzADUoABzqjiMeuc5m3YXyeuZeUw1ZJc29JGsqyWQGDY8q3vrtBdamhKXraag?cluster=devnet) |
+| `FeedbackEmissionLog` PDA | [`HB4BBi9j…`](https://explorer.solana.com/address/HB4BBi9jaD3VPcZkQQaH3DxukSqBiXfW8RejtaLa8bF3?cluster=devnet) |
+
+Full trace + reproduction commands: [Verification → Devnet smoke](/verification/devnet-smoke).
+
+## Read next
 
-These checks are part of the adapter, not the route layer.
+<Cards>
+  <Card title="Facilitator adapters" href="/integration-guides/facilitator-adapters">
+    The five-method contract every adapter satisfies. Build your own.
+  </Card>
+  <Card title="Atomic-tx invariant" href="/verification/atomic-tx-invariant">
+    Why the gate, transfer, and feedback must execute as one Solana tx.
+  </Card>
+  <Card title="mountTrustGate" href="/sdk/mount-trustgate">
+    The SDK middleware that backs the adapter dispatch.
+  </Card>
+</Cards>

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>