@absol-labs/agent 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,1006 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { privateKeyToAccount } from "viem/accounts";
+import { http, isAddress, isHex, type Chain } from "viem";
+import { baseSepolia } from "viem/chains";
+import { z } from "zod";
+
+import {
+  discoverServices as defaultDiscoverServices,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "../discovery/registry.js";
+import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
+import {
+  parseServerMandateCapsEnv,
+  signServerMandate,
+  ServerMandateConfigError,
+} from "../mandates/env.js";
+import {
+  VerifiedStreamAgentClient,
+  type ReclaimAuthorizedStreamInput,
+  type ReclaimVerifiedStreamResult,
+  type StreamStatusView,
+  type VerifiedStreamAgentOpener,
+} from "../sdk/client.js";
+import {
+  createWalletBackedAgentClient,
+  parseAgentWalletEnv,
+  type AgentWalletInput,
+} from "../wallet/provider.js";
+import {
+  createReclaimConsumerProofServiceFromEnv,
+  type ConsumerDeliveryProofService,
+  type VerifiedConsumedHttpsResponseProof,
+} from "../zktls/reclaim.js";
+
+/**
+ * MCP server for the agent lane.
+ *
+ * The server exposes hire/status/reclaim/list tools over the MCP SDK while
+ * keeping all fund-moving operations fail-closed behind a signed spend mandate.
+ */
+
+const addressSchema = z
+  .string()
+  .refine((value) => isAddress(value), "must be an EVM address");
+const bytes32Schema = z
+  .string()
+  .refine(
+    (value) => isHex(value, { strict: true }) && value.length === 66,
+    "must be bytes32 hex",
+  );
+const decimalStringSchema = z
+  .string()
+  .regex(/^(0|[1-9]\d*)$/, "must be a base-10 integer string");
+
+// The spend mandate is NOT a tool argument. An MCP caller (an LLM) cannot
+// produce an EIP-712 signature, so the mandate is configured once at server
+// construction (see `signedMandate` in VerifiedStreamMcpServerOptions) exactly
+// like the AgentKit action provider. Tool inputs carry only the hire terms.
+const hireVerifiedServiceSchema = {
+  operator: addressSchema.describe(
+    "Seller payout wallet (EVM address) that receives USDC for oracle-verified delivery.",
+  ),
+  serviceRef: bytes32Schema.describe(
+    "bytes32 service identifier the oracle verifies delivery against (from discover_services).",
+  ),
+  budgetUsdc: decimalStringSchema.describe(
+    'Total USDC to escrow for this stream, in ATOMIC units (6 decimals): 1 USDC = "1000000".',
+  ),
+  ratePerSecondUsdc: decimalStringSchema.describe(
+    "Accrual to the seller per verified second, in USDC ATOMIC units (6 decimals).",
+  ),
+  durationSeconds: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "Optional max stream lifetime in seconds. Defaults to the server mandate's max duration.",
+    ),
+} as const;
+
+const getStreamStatusSchema = {
+  streamId: bytes32Schema.describe(
+    "Stream id returned by hire_verified_service.",
+  ),
+} as const;
+
+const reclaimStreamSchema = {
+  streamId: bytes32Schema.describe("Stream id to reclaim unspent USDC from."),
+  closeFirst: z
+    .boolean()
+    .optional()
+    .describe(
+      "Close the stream before reclaiming. Use when the stream is still active.",
+    ),
+} as const;
+
+const proveHttpsResponseSchema = {
+  streamId: bytes32Schema,
+  url: z.string().url(),
+  method: z.enum(["GET", "POST", "PUT"]).optional(),
+  headers: z.record(z.string()).optional(),
+  body: z.string().optional(),
+  responseMatches: z
+    .array(
+      z.object({
+        type: z.enum(["regex", "contains"]),
+        value: z.string().min(1),
+        invert: z.boolean().optional(),
+        isOptional: z.boolean().optional(),
+      }),
+    )
+    .min(1),
+  responseRedactions: z
+    .array(
+      z
+        .object({
+          regex: z.string().optional(),
+          jsonPath: z.string().optional(),
+          xPath: z.string().optional(),
+          hash: z.enum(["oprf", "oprf-raw"]).optional(),
+        })
+        .refine(
+          (value) =>
+            value.regex !== undefined ||
+            value.jsonPath !== undefined ||
+            value.xPath !== undefined,
+          "response redaction needs regex, jsonPath, or xPath",
+        ),
+    )
+    .optional(),
+  geoLocation: z.string().optional(),
+  useTee: z.boolean().optional(),
+  zkEngine: z.enum(["snarkjs", "stwo"]).optional(),
+} as const;
+
+const metrikAgentEnvSchema = z.object({
+  METRIK_AGENT_RPC_URL: z.string().url(),
+  METRIK_AGENT_ESCROW: addressSchema,
+  METRIK_AGENT_USDC: addressSchema,
+  METRIK_AGENT_CHAIN_ID: z.string().optional(),
+  METRIK_AGENT_CHAIN_NAME: z.string().optional(),
+  METRIK_AGENT_MCP_STATE_FILE: z.string().optional(),
+});
+
+export interface McpToolSpec {
+  name: string;
+  description: string;
+  /** Whether invoking this tool can move funds (must pass a spend mandate check). */
+  movesFunds: boolean;
+}
+
+export const METRIK_MCP_TOOLS: readonly McpToolSpec[] = [
+  {
+    name: "discover_services",
+    description:
+      "Discover verified third-party services on the Metrik marketplace. Returns operator + serviceRef + endpoint for listings whose operator signature is cryptographically verified, so an agent can go from discovery to hire without pre-known addresses.",
+    movesFunds: false,
+  },
+  {
+    name: "hire_verified_service",
+    description:
+      "Open a verified payment stream for a third-party service. Pays only for oracle-verified delivered time. Subject to the agent's spend mandate.",
+    movesFunds: true,
+  },
+  {
+    name: "check_stream_status",
+    description:
+      "Read a stream's live status, accrued amount, and claimable/reclaimable balances.",
+    movesFunds: false,
+  },
+  {
+    name: "reclaim_unspent",
+    description:
+      "Close a stream and reclaim unspent funds to the buyer after failure or completion.",
+    movesFunds: true,
+  },
+  {
+    name: "list_streams",
+    description: "List the agent's streams and their current state.",
+    movesFunds: false,
+  },
+  {
+    name: "prove_https_response",
+    description:
+      "Generate a zkTLS proof of the exact HTTPS response consumed for a tracked stream. This is an L4 delivery signal and must be cross-checked with oracle/L1 evidence.",
+    movesFunds: false,
+  },
+] as const;
+
+/** @deprecated Renamed to METRIK_MCP_TOOLS; retained for back-compat. */
+export const STREAMPROOF_MCP_TOOLS = METRIK_MCP_TOOLS;
+
+export interface StoredStreamRecord {
+  readonly streamId: `0x${string}`;
+  readonly buyer: `0x${string}`;
+  readonly operator: `0x${string}`;
+  readonly serviceRef: `0x${string}`;
+  readonly budgetUsdc: bigint;
+  readonly ratePerSecondUsdc: bigint;
+  readonly maxDurationSeconds: number;
+  readonly openedAtSeconds: number;
+  readonly mandateId: `0x${string}`;
+}
+
+export interface StreamRegistry {
+  put(record: StoredStreamRecord): Promise<void>;
+  get(streamId: `0x${string}`): Promise<StoredStreamRecord | null>;
+  list(): Promise<readonly StoredStreamRecord[]>;
+}
+
+export class InMemoryStreamRegistry implements StreamRegistry {
+  private readonly records = new Map<`0x${string}`, StoredStreamRecord>();
+
+  async put(record: StoredStreamRecord): Promise<void> {
+    this.records.set(record.streamId, record);
+  }
+
+  async get(streamId: `0x${string}`): Promise<StoredStreamRecord | null> {
+    return this.records.get(streamId) ?? null;
+  }
+
+  async list(): Promise<readonly StoredStreamRecord[]> {
+    return Array.from(this.records.values());
+  }
+}
+
+export class FileStreamRegistry implements StreamRegistry {
+  constructor(private readonly filePath: string) {}
+
+  async put(record: StoredStreamRecord): Promise<void> {
+    const records = await this.readAll();
+    records.set(record.streamId, record);
+    await this.writeAll(records);
+  }
+
+  async get(streamId: `0x${string}`): Promise<StoredStreamRecord | null> {
+    const records = await this.readAll();
+    return records.get(streamId) ?? null;
+  }
+
+  async list(): Promise<readonly StoredStreamRecord[]> {
+    return Array.from((await this.readAll()).values());
+  }
+
+  private async readAll(): Promise<Map<`0x${string}`, StoredStreamRecord>> {
+    const contents = await fs.readFile(this.filePath, "utf8").catch((error) => {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return "[]";
+      }
+      throw error;
+    });
+    const parsed = z
+      .array(
+        z.object({
+          streamId: bytes32Schema,
+          buyer: addressSchema,
+          operator: addressSchema,
+          serviceRef: bytes32Schema,
+          budgetUsdc: decimalStringSchema,
+          ratePerSecondUsdc: decimalStringSchema,
+          maxDurationSeconds: z.number().int().positive(),
+          openedAtSeconds: z.number().int().nonnegative(),
+          mandateId: bytes32Schema,
+        }),
+      )
+      .parse(JSON.parse(contents));
+
+    return new Map(
+      parsed.map((record) => [
+        record.streamId as `0x${string}`,
+        {
+          streamId: record.streamId as `0x${string}`,
+          buyer: record.buyer as `0x${string}`,
+          operator: record.operator as `0x${string}`,
+          serviceRef: record.serviceRef as `0x${string}`,
+          budgetUsdc: BigInt(record.budgetUsdc),
+          ratePerSecondUsdc: BigInt(record.ratePerSecondUsdc),
+          maxDurationSeconds: record.maxDurationSeconds,
+          openedAtSeconds: record.openedAtSeconds,
+          mandateId: record.mandateId as `0x${string}`,
+        },
+      ]),
+    );
+  }
+
+  private async writeAll(
+    records: Map<`0x${string}`, StoredStreamRecord>,
+  ): Promise<void> {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    await fs.writeFile(
+      this.filePath,
+      JSON.stringify(
+        Array.from(records.values()).map((record) => ({
+          ...record,
+          budgetUsdc: record.budgetUsdc.toString(),
+          ratePerSecondUsdc: record.ratePerSecondUsdc.toString(),
+        })),
+        null,
+        2,
+      ),
+    );
+  }
+}
+
+export interface MandateStateResolver {
+  getSpentSoFarUsdc(owner: `0x${string}`): Promise<bigint>;
+  getRevokedMandateIds(owner: `0x${string}`): Promise<readonly `0x${string}`[]>;
+}
+
+export interface VerifiedStreamMcpClient extends Pick<
+  VerifiedStreamAgentOpener,
+  "openVerifiedStream"
+> {
+  getStreamStatus(streamId: `0x${string}`): Promise<StreamStatusView>;
+  reclaimStream(
+    input: ReclaimAuthorizedStreamInput,
+  ): Promise<ReclaimVerifiedStreamResult>;
+}
+
+export interface VerifiedStreamMcpServerOptions {
+  readonly agentClient: VerifiedStreamMcpClient;
+  /**
+   * The owner-signed spend mandate that bounds every hire/reclaim (per-stream +
+   * total budget, rate, duration, allowed operators, expiry). Configured once at
+   * construction — the MCP caller (an LLM) never supplies or edits it, because it
+   * cannot produce an EIP-712 signature. Mirrors the AgentKit action provider.
+   */
+  readonly signedMandate: SignedSpendMandate;
+  /**
+   * Optional provider returning the CURRENT signed mandate. When set, it
+   * supersedes {@link signedMandate} for fund-moving operations and is resolved
+   * per call — so a provider that re-signs before expiry keeps a long-running
+   * server authorizing hires. The env builder supplies a lazily-re-signing one.
+   */
+  readonly mandateProvider?: () =>
+    | SignedSpendMandate
+    | Promise<SignedSpendMandate>;
+  readonly registry?: StreamRegistry;
+  readonly deliveryProofService?: ConsumerDeliveryProofService;
+  readonly mandateStateResolver?: Partial<MandateStateResolver>;
+  readonly now?: () => number;
+  /**
+   * Discovery driver for the `discover_services` tool. Defaults to the live
+   * registry-backed {@link discoverServices}; tests inject a double. Defaults for
+   * the registry URL/apikey come from env inside `discoverServices`.
+   */
+  readonly discoverServices?: DiscoverServicesFn;
+  readonly serverInfo?: {
+    readonly name: string;
+    readonly version: string;
+  };
+}
+
+export interface VerifiedStreamMcpServerRuntime {
+  readonly mcpServer: McpServer;
+  readonly registry: StreamRegistry;
+  connectStdio(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface ParsedMetrikAgentEnv {
+  readonly rpcUrl: string;
+  readonly escrow: `0x${string}`;
+  readonly usdc: `0x${string}`;
+  readonly chain: Chain;
+  readonly stateFile?: string;
+  readonly wallet: AgentWalletInput;
+}
+
+/**
+ * Re-sign the server mandate when it is within this many seconds of expiry, so a
+ * long-running server never bricks hires on a lapsed construction-time mandate.
+ */
+const MANDATE_REFRESH_WINDOW_SECONDS = 300;
+
+const warnedResolverGaps = new Set<string>();
+
+/** Emits a stderr warning at most once per process for a given key. */
+function warnOnce(key: string, message: string): void {
+  if (warnedResolverGaps.has(key)) {
+    return;
+  }
+  warnedResolverGaps.add(key);
+  // stderr, never stdout: stdout is the MCP stdio transport channel.
+  console.error(message);
+}
+
+const DISCOVER_TOOL_SPEC = METRIK_MCP_TOOLS[0]!;
+const HIRE_TOOL_SPEC = METRIK_MCP_TOOLS[1]!;
+const STATUS_TOOL_SPEC = METRIK_MCP_TOOLS[2]!;
+const RECLAIM_TOOL_SPEC = METRIK_MCP_TOOLS[3]!;
+const LIST_TOOL_SPEC = METRIK_MCP_TOOLS[4]!;
+const PROVE_TOOL_SPEC = METRIK_MCP_TOOLS[5]!;
+
+const discoverServicesSchema = {
+  category: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Optional marketplace category to filter listings by."),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Optional cap on the number of verified listings to return."),
+} as const;
+
+/** Discovery driver signature — overridable in tests. */
+export type DiscoverServicesFn = (
+  opts?: DiscoverServicesOptions,
+) => Promise<ServiceListing[]>;
+
+export function createVerifiedStreamMcpServer(
+  options: VerifiedStreamMcpServerOptions,
+): VerifiedStreamMcpServerRuntime {
+  const registry = options.registry ?? new InMemoryStreamRegistry();
+
+  // Fail-closed mandate accounting defaults (security):
+  // - Cumulative-cap (`maxTotalUsdc`) is enforced by DEFAULT: spent-so-far is
+  //   summed from escrowed budget tracked in the stream registry, so the total
+  //   cap applies with no external wiring. This is conservative (counts full
+  //   escrowed budget, buyer-favoring) — wire an explicit resolver for exact
+  //   settled-spend accounting.
+  // - Revocation cannot be known without an external store, so it defaults to
+  //   "none revoked" but emits a loud one-time warning: a revoked mandate is NOT
+  //   rejected until `getRevokedMandateIds` is wired.
+  const registryBackedSpent = async (owner: `0x${string}`): Promise<bigint> => {
+    const records = await registry.list();
+    return records
+      .filter((record) => record.buyer.toLowerCase() === owner.toLowerCase())
+      .reduce((sum, record) => sum + record.budgetUsdc, 0n);
+  };
+  if (options.mandateStateResolver?.getRevokedMandateIds === undefined) {
+    warnOnce(
+      "mcp-revocation",
+      "[metrik] MCP server started with no mandate revocation resolver: revoked mandates will NOT be rejected until getRevokedMandateIds is wired. Cumulative spend is bounded by escrowed budget from the stream registry.",
+    );
+  }
+  const resolver: MandateStateResolver = {
+    getSpentSoFarUsdc:
+      options.mandateStateResolver?.getSpentSoFarUsdc ?? registryBackedSpent,
+    getRevokedMandateIds:
+      options.mandateStateResolver?.getRevokedMandateIds ?? (async () => []),
+  };
+  // Resolve the CURRENT mandate per fund-moving call. A provider (env builder)
+  // re-signs before expiry so a long-running server keeps authorizing hires;
+  // without one, the static construction-time mandate is used.
+  const resolveMandate =
+    options.mandateProvider ?? (() => options.signedMandate);
+
+  // Per-owner serialization for hires. `getSpentSoFarUsdc` reads the registry
+  // BEFORE the new stream's record is written, so concurrent hires from one
+  // owner could both observe stale spend and overshoot `maxTotalUsdc`. Chaining
+  // hires per owner makes the read→check→open→record sequence atomic per owner.
+  const ownerHireChains = new Map<string, Promise<unknown>>();
+  const serializeHire = <T>(
+    owner: `0x${string}`,
+    task: () => Promise<T>,
+  ): Promise<T> => {
+    const key = owner.toLowerCase();
+    const prev = ownerHireChains.get(key) ?? Promise.resolve();
+    const run = prev.then(task, task);
+    ownerHireChains.set(
+      key,
+      run.then(
+        () => undefined,
+        () => undefined,
+      ),
+    );
+    return run;
+  };
+
+  const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+  const discover = options.discoverServices ?? defaultDiscoverServices;
+
+  const mcpServer = new McpServer(
+    options.serverInfo ?? {
+      name: "metrik-agent-mcp",
+      version: "0.1.0",
+    },
+  );
+
+  mcpServer.registerTool(
+    "discover_services",
+    {
+      description: DISCOVER_TOOL_SPEC.description,
+      inputSchema: discoverServicesSchema,
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true,
+        title: "Discover Verified Services",
+      },
+    },
+    async ({ category, limit }) => {
+      try {
+        const listings = await discover({
+          ...(category === undefined ? {} : { category }),
+          ...(limit === undefined ? {} : { limit }),
+        });
+        return successResult(
+          `discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}`,
+          { services: listings.map(serializeServiceListing) },
+        );
+      } catch (error) {
+        return safeToolError(error);
+      }
+    },
+  );
+
+  mcpServer.registerTool(
+    "hire_verified_service",
+    {
+      description: HIRE_TOOL_SPEC.description,
+      inputSchema: hireVerifiedServiceSchema,
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+        readOnlyHint: false,
+        title: "Hire Verified Service",
+      },
+    },
+    async (args) => {
+      try {
+        const signedMandate = await resolveMandate();
+        const owner = signedMandate.owner as `0x${string}`;
+        const nowSeconds = now();
+        const request = {
+          operator: args.operator as `0x${string}`,
+          budgetUsdc: BigInt(args.budgetUsdc),
+          ratePerSecondUsdc: BigInt(args.ratePerSecondUsdc),
+          maxDurationSeconds:
+            args.durationSeconds ?? signedMandate.mandate.maxDurationSeconds,
+        } satisfies Parameters<typeof checkMandate>[1];
+
+        // Serialize per owner: the spent-so-far read, cap check, open, and
+        // registry write must be atomic, or concurrent hires could both pass
+        // the cumulative-cap check on stale spend and overshoot maxTotalUsdc.
+        return await serializeHire(owner, async () => {
+          const spentSoFarUsdc = await resolver.getSpentSoFarUsdc(owner);
+          const revokedMandateIds = await resolver.getRevokedMandateIds(owner);
+          const decision = await checkMandate(
+            signedMandate,
+            request,
+            spentSoFarUsdc,
+            {
+              nowSeconds,
+              revokedMandateIds,
+            },
+          );
+          if (!decision.allowed) {
+            return errorResult(
+              `mandate denied: ${decision.reason ?? "unknown"}`,
+            );
+          }
+
+          const result = await options.agentClient.openVerifiedStream({
+            operator: request.operator,
+            serviceRef: args.serviceRef as `0x${string}`,
+            budgetUsdc: request.budgetUsdc,
+            ratePerSecondUsdc: request.ratePerSecondUsdc,
+            maxDurationSeconds: request.maxDurationSeconds,
+            signedMandate,
+            spentSoFarUsdc,
+            nowSeconds,
+            revokedMandateIds,
+          });
+
+          await registry.put({
+            streamId: result.streamId,
+            buyer: owner,
+            operator: request.operator,
+            serviceRef: args.serviceRef as `0x${string}`,
+            budgetUsdc: request.budgetUsdc,
+            ratePerSecondUsdc: request.ratePerSecondUsdc,
+            maxDurationSeconds: request.maxDurationSeconds,
+            openedAtSeconds: nowSeconds,
+            mandateId: signedMandate.mandateId as `0x${string}`,
+          });
+
+          return successResult(
+            `opened verified stream ${result.streamId} on chain ${result.handle.chainId}`,
+            {
+              streamId: result.streamId,
+              txHash: result.txHash,
+              approveTxHash: result.approveTxHash,
+              handle: {
+                streamId: result.handle.streamId,
+                escrow: result.handle.escrow,
+                chainId: result.handle.chainId,
+              },
+            },
+          );
+        });
+      } catch (error) {
+        return safeToolError(error);
+      }
+    },
+  );
+
+  mcpServer.registerTool(
+    "check_stream_status",
+    {
+      description: STATUS_TOOL_SPEC.description,
+      inputSchema: getStreamStatusSchema,
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: false,
+        readOnlyHint: true,
+        title: "Get Stream Status",
+      },
+    },
+    async ({ streamId }) => {
+      try {
+        const status = await options.agentClient.getStreamStatus(
+          streamId as `0x${string}`,
+        );
+        return successResult(
+          `stream ${streamId} is ${status.stream.status}`,
+          serializeStreamStatus(status, streamId as `0x${string}`),
+        );
+      } catch (error) {
+        return safeToolError(error);
+      }
+    },
+  );
+
+  mcpServer.registerTool(
+    "reclaim_unspent",
+    {
+      description: RECLAIM_TOOL_SPEC.description,
+      inputSchema: reclaimStreamSchema,
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+        readOnlyHint: false,
+        title: "Reclaim Stream",
+      },
+    },
+    async ({ streamId, closeFirst }) => {
+      try {
+        const record = await registry.get(streamId as `0x${string}`);
+        if (record === null) {
+          return errorResult(`unknown stream: ${streamId}`);
+        }
+        const signedMandate = await resolveMandate();
+
+        // Reclaim/close only RETURN unspent funds to the buyer or stop payment.
+        // They are authorized on mandate-owner signature ALONE (see the SDK
+        // client's authorizeBuyerRecovery) — never gated by expiry, revocation,
+        // or caps, so a lapsed/revoked mandate can never strand buyer funds.
+        const result = await options.agentClient.reclaimStream({
+          streamId: streamId as `0x${string}`,
+          signedMandate,
+          spentSoFarUsdc: 0n,
+          nowSeconds: now(),
+          ...(closeFirst === undefined ? {} : { closeFirst }),
+        });
+
+        return successResult(`reclaimed stream ${streamId}`, {
+          closeTxHash: result.closeResult?.txHash ?? null,
+          reclaimTxHash: result.reclaimResult.txHash,
+        });
+      } catch (error) {
+        return safeToolError(error);
+      }
+    },
+  );
+
+  mcpServer.registerTool(
+    "list_streams",
+    {
+      description: LIST_TOOL_SPEC.description,
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: false,
+        readOnlyHint: true,
+        title: "List Streams",
+      },
+    },
+    async () => {
+      try {
+        const records = await registry.list();
+        const entries = await Promise.all(
+          records.map(async (record) => {
+            const status = await options.agentClient
+              .getStreamStatus(record.streamId)
+              .then((value) => serializeStreamStatus(value, record.streamId))
+              .catch((error) => ({
+                streamId: record.streamId,
+                statusError: asErrorMessage(error),
+              }));
+            return {
+              streamId: record.streamId,
+              buyer: record.buyer,
+              operator: record.operator,
+              serviceRef: record.serviceRef,
+              budgetUsdc: record.budgetUsdc.toString(),
+              ratePerSecondUsdc: record.ratePerSecondUsdc.toString(),
+              maxDurationSeconds: record.maxDurationSeconds,
+              openedAtSeconds: record.openedAtSeconds,
+              mandateId: record.mandateId,
+              status,
+            };
+          }),
+        );
+
+        return successResult(
+          `tracked ${entries.length} stream${entries.length === 1 ? "" : "s"}`,
+          { streams: entries },
+        );
+      } catch (error) {
+        return safeToolError(error);
+      }
+    },
+  );
+
+  if (options.deliveryProofService !== undefined) {
+    const deliveryProofService = options.deliveryProofService;
+    mcpServer.registerTool(
+      "prove_https_response",
+      {
+        description: PROVE_TOOL_SPEC.description,
+        inputSchema: proveHttpsResponseSchema,
+        annotations: {
+          idempotentHint: false,
+          openWorldHint: true,
+          readOnlyHint: true,
+          title: "Prove HTTPS Response",
+        },
+      },
+      async ({
+        streamId,
+        url,
+        method,
+        headers,
+        body,
+        responseMatches,
+        responseRedactions,
+        geoLocation,
+        useTee,
+        zkEngine,
+      }) => {
+        try {
+          const record = await registry.get(streamId as `0x${string}`);
+          if (record === null) {
+            return errorResult(`unknown stream: ${streamId}`);
+          }
+
+          const result = await deliveryProofService.proveConsumedHttpsResponse({
+            url,
+            ...(method === undefined ? {} : { method }),
+            ...(headers === undefined ? {} : { headers }),
+            ...(body === undefined ? {} : { body }),
+            responseMatches,
+            ...(responseRedactions === undefined ? {} : { responseRedactions }),
+            ...(geoLocation === undefined ? {} : { geoLocation }),
+            ...(useTee === undefined ? {} : { useTee }),
+            ...(zkEngine === undefined ? {} : { zkEngine }),
+            delivery: {
+              owner: record.buyer,
+              streamId: record.streamId,
+              operator: record.operator,
+              serviceRef: record.serviceRef,
+              mandateId: record.mandateId,
+            },
+          });
+
+          return successResult(
+            `generated zkTLS response proof for stream ${streamId}`,
+            serializeConsumedResponseProof(record.streamId, result),
+          );
+        } catch (error) {
+          return safeToolError(error);
+        }
+      },
+    );
+  }
+
+  return {
+    mcpServer,
+    registry,
+    connectStdio: async () => {
+      await mcpServer.connect(new StdioServerTransport());
+    },
+    close: async () => {
+      await mcpServer.close();
+    },
+  };
+}
+
+export function parseMetrikAgentEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ParsedMetrikAgentEnv {
+  const parsed = metrikAgentEnvSchema.parse(env);
+  const chainId = Number(parsed.METRIK_AGENT_CHAIN_ID ?? baseSepolia.id);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error("METRIK_AGENT_CHAIN_ID must be a positive integer");
+  }
+  if (chainId !== baseSepolia.id) {
+    throw new Error(
+      `unsupported METRIK_AGENT_CHAIN_ID ${chainId}; phase 2 is Base Sepolia only`,
+    );
+  }
+
+  return {
+    rpcUrl: parsed.METRIK_AGENT_RPC_URL,
+    escrow: parsed.METRIK_AGENT_ESCROW as `0x${string}`,
+    usdc: parsed.METRIK_AGENT_USDC as `0x${string}`,
+    chain: {
+      ...baseSepolia,
+      name: parsed.METRIK_AGENT_CHAIN_NAME ?? baseSepolia.name,
+    },
+    ...(parsed.METRIK_AGENT_MCP_STATE_FILE === undefined
+      ? {}
+      : {
+          stateFile: parsed.METRIK_AGENT_MCP_STATE_FILE,
+        }),
+    wallet: parseAgentWalletEnv(env),
+  };
+}
+
+/**
+ * Builds the {@link VerifiedStreamMcpServerOptions} for a single wallet-backed
+ * tenant from environment configuration.
+ *
+ * This is split out from {@link createVerifiedStreamMcpServerFromEnv} so a
+ * multi-session transport (see `mcp/http.ts`) can construct a FRESH
+ * {@link McpServer} per MCP session while sharing one tenant's wallet-backed
+ * agent client and stream registry. A single `McpServer` can only be bound to
+ * one transport at a time, so concurrent sessions each need their own server
+ * instance built from these shared options.
+ */
+export async function createVerifiedStreamMcpServerOptionsFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<VerifiedStreamMcpServerOptions> {
+  const parsed = parseMetrikAgentEnv(env);
+  const caps = parseServerMandateCapsEnv(env);
+  if (caps === null) {
+    throw new ServerMandateConfigError(
+      "no spend mandate configured: set METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC, " +
+        "METRIK_AGENT_MANDATE_MAX_TOTAL_USDC, METRIK_AGENT_MANDATE_MAX_RATE_PER_SECOND_USDC, " +
+        "and METRIK_AGENT_MANDATE_MAX_DURATION_SECONDS. A fund-moving server refuses to run " +
+        "without an explicit spend ceiling.",
+    );
+  }
+  const deliveryProofService = createReclaimConsumerProofServiceFromEnv(env);
+  const { agentClient, wallet } = await createWalletBackedAgentClient(
+    {
+      chain: parsed.chain,
+      transport: http(parsed.rpcUrl),
+      escrow: parsed.escrow,
+      usdc: parsed.usdc,
+      settlementTarget: {
+        chainId: parsed.chain.id,
+        escrow: parsed.escrow,
+      },
+    },
+    parsed.wallet,
+  );
+
+  // Self-sign the mandate from the server's own funding wallet (its address is
+  // the mandate owner). The MCP caller never signs — see hire_verified_service.
+  // A lazily-re-signing provider keeps a long-running server authorizing hires:
+  // when the cached mandate is within the refresh window of its expiry, it is
+  // re-signed. (Reclaim/close are signature-only, so they never expire.)
+  const chainId = parsed.chain.id;
+  const signMandate = () =>
+    signServerMandate(wallet.account, caps, { chainId });
+  const signedMandate = await signMandate();
+  let cachedMandate = signedMandate;
+  const mandateProvider = async (): Promise<SignedSpendMandate> => {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (
+      nowSeconds >=
+      cachedMandate.mandate.expiresAt - MANDATE_REFRESH_WINDOW_SECONDS
+    ) {
+      cachedMandate = await signMandate();
+    }
+    return cachedMandate;
+  };
+
+  return {
+    agentClient,
+    signedMandate,
+    mandateProvider,
+    registry:
+      parsed.stateFile === undefined
+        ? new InMemoryStreamRegistry()
+        : new FileStreamRegistry(parsed.stateFile),
+    ...(deliveryProofService === null ? {} : { deliveryProofService }),
+  };
+}
+
+export async function createVerifiedStreamMcpServerFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<VerifiedStreamMcpServerRuntime> {
+  return createVerifiedStreamMcpServer(
+    await createVerifiedStreamMcpServerOptionsFromEnv(env),
+  );
+}
+
+export async function startVerifiedStreamMcpServerStdio(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const server = await createVerifiedStreamMcpServerFromEnv(env);
+  await server.connectStdio();
+}
+
+function serializeServiceListing(
+  listing: ServiceListing,
+): Record<string, unknown> {
+  return {
+    serviceRef: listing.serviceRef,
+    operator: listing.operator,
+    publicUrl: listing.publicUrl,
+    category: listing.category,
+    ...(listing.targetMetadata === undefined
+      ? {}
+      : { targetMetadata: listing.targetMetadata }),
+  };
+}
+
+function serializeStreamStatus(
+  status: StreamStatusView,
+  streamId: `0x${string}`,
+): Record<string, unknown> {
+  return {
+    streamId,
+    stream: {
+      buyer: status.stream.buyer,
+      operator: status.stream.operator,
+      serviceRef: status.stream.serviceRef,
+      deposit: status.stream.deposit.toString(),
+      ratePerSecond: status.stream.ratePerSecond.toString(),
+      accrued: status.stream.accrued.toString(),
+      claimed: status.stream.claimed.toString(),
+      openedAt: status.stream.openedAt,
+      expiresAt: status.stream.expiresAt,
+      lastVerifiedAt: status.stream.lastVerifiedAt,
+      lastSequence: status.stream.lastSequence.toString(),
+      consecutiveFailures: status.stream.consecutiveFailures,
+      status: status.stream.status,
+    },
+    claimable: status.claimable.toString(),
+    reclaimable: status.reclaimable.toString(),
+  };
+}
+
+function serializeConsumedResponseProof(
+  streamId: `0x${string}`,
+  proof: VerifiedConsumedHttpsResponseProof,
+): Record<string, unknown> {
+  return {
+    streamId,
+    proof: proof.proof,
+    request: {
+      ...proof.request,
+      responseMatches: [...proof.request.responseMatches],
+      responseRedactions: [...proof.request.responseRedactions],
+    },
+    verification: proof.verification,
+  };
+}
+
+function successResult(
+  text: string,
+  structuredContent?: Record<string, unknown>,
+) {
+  return {
+    content: [{ type: "text" as const, text }],
+    ...(structuredContent === undefined ? {} : { structuredContent }),
+  };
+}
+
+function errorResult(text: string) {
+  return {
+    content: [{ type: "text" as const, text }],
+    isError: true,
+  };
+}
+
+function asErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Logs the full error server-side (stderr) and returns a GENERIC message to the
+ * MCP caller. Underlying viem/CDP/SDK error strings can carry internal detail
+ * (RPC URLs, addresses, revert traces); tool callers see only that it failed.
+ * Deliberate, caller-actionable messages (mandate denied, unknown stream) are
+ * returned directly via errorResult and are unaffected.
+ */
+function safeToolError(error: unknown) {
+  console.error("[metrik] MCP tool error:", asErrorMessage(error));
+  return errorResult("The tool call failed. See server logs for details.");
+}