@paybond/kit 0.9.8 → 0.11.0

package/dist/mcp-server.js

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
-// @ts-ignore Node builtins are available in the published CLI runtime.
+import { Buffer } from "node:buffer";
 import { readFileSync } from "node:fs";
-import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { requireSecureGatewayUrl } from "./gateway-url.js";
+import { runCli } from "./cli/router.js";
+import { redactSensitiveFields } from "./cli/redact.js";
+import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, resolveMcpToolPolicy, toolAllowedByPolicy, } from "./cli/mcp-policy.js";
+import { MCP_EVIDENCE_POLICY_ENV, McpEvidenceValidationGate, completionEvidenceValidationOk, extractHarborEvidenceValidationInput, extractSandboxGuardrailValidationInput, parseMcpEvidencePolicy, } from "./mcp-evidence-policy.js";
+import { McpCapabilityTokenCache, mcpToolStoresCapabilityToken, parseMcpCapabilityTokenCacheConfig, } from "./mcp-capability-token-cache.js";
+import { createMcpPolicyGatewayAdapter, McpPolicyReloadGate, parseMcpPolicyReloadConfig, } from "./mcp-policy-reload.js";
+import { DEFAULT_PAYBOND_GATEWAY_BASE_URL, GatewayFraudClient, GatewaySignalClient, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.9.8";
+const SERVER_VERSION = "0.11.0";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
@@ -14,7 +24,10 @@ const TOOL_SELECTION_METADATA = {
         title: "Get Paybond Principal",
         annotations: readOnlyToolAnnotations("Get Paybond Principal"),
         outputSchema: outputObjectSchema({
-            tenant_id: { type: "string", description: "Tenant bound to the configured Paybond API key." },
+            tenant_id: {
+                type: "string",
+                description: "Tenant bound to the configured Paybond API key.",
+            },
             subject: { type: "string" },
             roles: { type: "array", items: { type: "string" } },
         }),
@@ -25,10 +38,22 @@ const TOOL_SELECTION_METADATA = {
             "Do not use this to create, fund, or modify intents; use paybond_authorize_agent_spend as the clearer gate before side-effecting agent tools.",
         annotations: additiveMutationToolAnnotations("Verify Paybond Capability"),
         outputSchema: outputObjectSchema({
-            allow: { type: "boolean", description: "Whether the requested operation is allowed." },
-            tenant: { type: "string", description: "Tenant echoed by the gateway." },
-            intent_id: { type: "string", description: "Verified Harbor intent UUID." },
-            audit_id: { type: "string", description: "Gateway audit identifier when available." },
+            allow: {
+                type: "boolean",
+                description: "Whether the requested operation is allowed.",
+            },
+            tenant: {
+                type: "string",
+                description: "Tenant echoed by the gateway.",
+            },
+            intent_id: {
+                type: "string",
+                description: "Verified Harbor intent UUID.",
+            },
+            audit_id: {
+                type: "string",
+                description: "Gateway audit identifier when available.",
+            },
         }, ["tenant", "intent_id"]),
     },
     paybond_authorize_agent_spend: {
@@ -37,10 +62,22 @@ const TOOL_SELECTION_METADATA = {
             "Do not use this for creating, funding, or changing intents; call paybond_create_spend_intent or paybond_fund_intent first when no funded capability token exists.",
         annotations: additiveMutationToolAnnotations("Authorize Agent Spend"),
         outputSchema: outputObjectSchema({
-            allow: { type: "boolean", description: "Whether the requested operation is allowed." },
-            tenant: { type: "string", description: "Tenant echoed by the gateway." },
-            intent_id: { type: "string", description: "Verified Harbor intent UUID." },
-            audit_id: { type: "string", description: "Gateway audit identifier when available." },
+            allow: {
+                type: "boolean",
+                description: "Whether the requested operation is allowed.",
+            },
+            tenant: {
+                type: "string",
+                description: "Tenant echoed by the gateway.",
+            },
+            intent_id: {
+                type: "string",
+                description: "Verified Harbor intent UUID.",
+            },
+            audit_id: {
+                type: "string",
+                description: "Gateway audit identifier when available.",
+            },
         }, ["tenant", "intent_id"]),
     },
     paybond_bootstrap_sandbox_guardrail: {
@@ -57,7 +94,30 @@ const TOOL_SELECTION_METADATA = {
             sandbox_lifecycle_status: { type: "string" },
             settlement_rail: { type: "string" },
             settlement_mode: { type: "string" },
-        }, ["tenant_id", "intent_id", "capability_token", "operation", "requested_spend_cents", "sandbox_lifecycle_status"]),
+        }, [
+            "tenant_id",
+            "intent_id",
+            "capability_token",
+            "operation",
+            "requested_spend_cents",
+            "sandbox_lifecycle_status",
+        ]),
+    },
+    paybond_validate_completion_evidence: {
+        title: "Validate Completion Evidence",
+        description: "Pre-validates vendor and canonical completion evidence against catalog JSON Schemas and preset forbidden_evidence_fields. " +
+            "Required before evidence submit tools when PAYBOND_MCP_EVIDENCE_POLICY=strict. Harbor remains authoritative at submit time.",
+        annotations: readOnlyToolAnnotations("Validate Completion Evidence"),
+        outputSchema: outputObjectSchema({
+            preset_id: { type: "string" },
+            ok: { type: "boolean" },
+            vendor_schema_ok: { type: "boolean" },
+            canonical_schema_ok: { type: "boolean" },
+            quality_fields_missing: { type: "array", items: { type: "string" } },
+            forbidden_fields_present: { type: "array", items: { type: "string" } },
+            pack_stale: { type: "boolean" },
+            drift_kinds: { type: "array", items: { type: "string" } },
+        }, ["preset_id", "ok"]),
     },
     paybond_submit_sandbox_guardrail_evidence: {
         title: "Submit Sandbox Guardrail Evidence",
@@ -72,13 +132,22 @@ const TOOL_SELECTION_METADATA = {
             sandbox_lifecycle_status: { type: "string" },
             predicate_passed: { type: "boolean" },
             payload_digest: { type: "string" },
-        }, ["tenant_id", "intent_id", "operation", "requested_spend_cents", "sandbox_lifecycle_status"]),
+        }, [
+            "tenant_id",
+            "intent_id",
+            "operation",
+            "requested_spend_cents",
+            "sandbox_lifecycle_status",
+        ]),
     },
     paybond_list_intents: {
         title: "List Harbor Intents",
         annotations: readOnlyToolAnnotations("List Harbor Intents"),
         outputSchema: outputObjectSchema({
-            items: { type: "array", items: { type: "object", additionalProperties: true } },
+            items: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
             next_cursor: { type: "string" },
         }),
     },
@@ -106,7 +175,10 @@ const TOOL_SELECTION_METADATA = {
         outputSchema: outputObjectSchema({
             tenant_id: { type: "string" },
             score_model_version: { type: "string" },
-            operators: { type: "array", items: { type: "object", additionalProperties: true } },
+            operators: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
         }),
     },
     paybond_get_signed_portfolio_artifact: {
@@ -144,14 +216,20 @@ const TOOL_SELECTION_METADATA = {
         outputSchema: outputObjectSchema({
             name: { type: "string" },
             version: { type: "string" },
-            skills: { type: "array", items: { type: "object", additionalProperties: true } },
+            skills: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
         }),
     },
     paybond_list_a2a_task_contracts: {
         title: "List A2A Task Contracts",
         annotations: readOnlyToolAnnotations("List A2A Task Contracts"),
         outputSchema: outputObjectSchema({
-            contracts: { type: "array", items: { type: "object", additionalProperties: true } },
+            contracts: {
+                type: "array",
+                items: { type: "object", additionalProperties: true },
+            },
         }),
     },
     paybond_get_a2a_task_contract: {
@@ -273,6 +351,13 @@ const TOOL_SELECTION_METADATA = {
         }),
     },
 };
+function readIntentAllowedTools(intent) {
+    const raw = intent.allowed_tools;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
 function readEnvFileValue(envFile, key) {
     let body;
     try {
@@ -327,8 +412,12 @@ function parseGatewayErrorEnvelope(text) {
         if (body === null || Array.isArray(body) || typeof body !== "object") {
             return {};
         }
-        const errorCode = typeof body.error === "string" && body.error.trim() ? body.error.trim() : undefined;
-        const errorMessage = typeof body.message === "string" && body.message.trim() ? body.message.trim() : undefined;
+        const errorCode = typeof body.error === "string" && body.error.trim()
+            ? body.error.trim()
+            : undefined;
+        const errorMessage = typeof body.message === "string" && body.message.trim()
+            ? body.message.trim()
+            : undefined;
         return { errorCode, errorMessage };
     }
     catch {
@@ -369,7 +458,9 @@ class GatewayAPIClient {
                         accept: "application/json",
                         authorization: `Bearer ${this.apiKey}`,
                         ...(extraHeaders ?? {}),
-                        ...(payload === undefined ? {} : { "content-type": "application/json" }),
+                        ...(payload === undefined
+                            ? {}
+                            : { "content-type": "application/json" }),
                     },
                     ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
                 });
@@ -382,7 +473,8 @@ class GatewayAPIClient {
                 await delay(backoffMs(attempt));
                 continue;
             }
-            if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < this.maxRetries) {
+            if ([429, 500, 502, 503, 504].includes(res.status) &&
+                attempt + 1 < this.maxRetries) {
                 const retryAfter = parseRetryAfterSeconds(res.headers.get("retry-after"));
                 await delay(retryAfter != null ? retryAfter * 1000 : backoffMs(attempt));
                 continue;
@@ -409,7 +501,14 @@ class PaybondMCPRuntime {
     principalValue = null;
     signalValue = null;
     fraudValue = null;
+    capabilityTokenCache;
+    evidenceGate;
+    policyReloadConfig;
+    policyGatePromise = null;
     constructor(settings) {
+        this.evidenceGate = new McpEvidenceValidationGate(settings.evidencePolicy ?? parseMcpEvidencePolicy(undefined));
+        this.capabilityTokenCache = new McpCapabilityTokenCache(settings.capabilityTokenCache);
+        this.policyReloadConfig = settings.policyReload ?? null;
         this.settings = {
             gatewayBaseUrl: settings.gatewayBaseUrl ?? DEFAULT_PAYBOND_GATEWAY_BASE_URL,
             apiKey: settings.apiKey,
@@ -422,6 +521,102 @@ class PaybondMCPRuntime {
             maxRetries: this.settings.maxRetries,
         });
     }
+    async policyGate() {
+        if (!this.policyReloadConfig) {
+            return null;
+        }
+        this.policyGatePromise ??= McpPolicyReloadGate.open(this.policyReloadConfig, {
+            gateway: createMcpPolicyGatewayAdapter(this.gateway),
+        });
+        return this.policyGatePromise;
+    }
+    async getPolicyReloadStatus() {
+        const gate = await this.policyGate();
+        return gate?.status() ?? null;
+    }
+    async beginPolicyToolCall() {
+        const gate = await this.policyGate();
+        gate?.beginToolCall();
+    }
+    async endPolicyToolCall() {
+        const gate = await this.policyGate();
+        gate?.endToolCall();
+    }
+    stopPolicyReload() {
+        void this.policyGatePromise?.then((gate) => gate?.stop());
+        this.policyGatePromise = null;
+    }
+    async authorizeAgentSpend(init) {
+        const gate = await this.policyGate();
+        let operation = init.operation;
+        let requestedSpendCents = init.requestedSpendCents ?? 0;
+        let policyDigest;
+        if (gate) {
+            const intent = await this.getIntent(init.intentId);
+            const allowedTools = readIntentAllowedTools(intent);
+            const gated = gate.assertSpendGate({
+                toolName: init.toolName,
+                operation,
+                allowedTools,
+                requestedSpendCents: init.requestedSpendCents,
+            });
+            operation = gated.operation;
+            requestedSpendCents = gated.requestedSpendCents;
+            policyDigest = gated.policyDigest;
+        }
+        const body = await this.verifyCapability({
+            intentId: init.intentId,
+            token: init.token,
+            operation,
+            requestedSpendCents,
+        });
+        if (policyDigest) {
+            body.policy_digest = policyDigest;
+        }
+        return body;
+    }
+    storeCapabilityToken(intentId, token) {
+        this.capabilityTokenCache.store(intentId, token);
+    }
+    async resolveCapabilityToken(intentId, token) {
+        const explicit = token?.trim();
+        if (explicit) {
+            return explicit;
+        }
+        const stored = this.capabilityTokenCache.resolve(intentId.trim());
+        if (stored) {
+            return stored;
+        }
+        throw new Error(`capability token unavailable or expired for intent ${intentId}; create or bootstrap a funded intent first`);
+    }
+    prepareToolResponse(value, toolName) {
+        if (value === null) {
+            return null;
+        }
+        const intentId = String(value.intent_id ?? "").trim();
+        const token = value.capability_token;
+        if (mcpToolStoresCapabilityToken(toolName) &&
+            intentId &&
+            typeof token === "string" &&
+            token.trim()) {
+            this.storeCapabilityToken(intentId, token);
+        }
+        return redactSensitiveFields(value);
+    }
+    validateCompletionEvidence(input) {
+        const report = this.evidenceGate.validateAndRecord(input);
+        return {
+            ...report,
+            ok: completionEvidenceValidationOk(report),
+        };
+    }
+    requireEvidenceValidation(input) {
+        this.evidenceGate.requirePass(input);
+    }
+    /** Resolve and cache the gateway principal during MCP server startup. */
+    async preloadPrincipal() {
+        await this.principal();
+    }
     async principal() {
         this.principalValue ??= this.gateway.getJSON(this.settings.principalPath);
         const body = await this.principalValue;
@@ -524,6 +719,11 @@ class PaybondMCPRuntime {
         return body;
     }
     async submitSandboxGuardrailEvidence(init) {
+        const extracted = extractSandboxGuardrailValidationInput({
+            payload: init.payload,
+            completionPresetId: init.completionPresetId,
+        });
+        this.requireEvidenceValidation(extracted);
         const expectedTenant = await this.tenantId();
         const payload = {};
         if (init.payload !== undefined) {
@@ -561,7 +761,6 @@ class PaybondMCPRuntime {
         const verifier = {
             tenant_id: await this.tenantId(),
             verifier_id: DEFAULT_RECOGNITION_VERIFIER_ID,
-            ...(init.expectedVerifier ?? {}),
         };
         return this.gateway.postJSON("/protocol/v2/recognition/verify", {
             proof: init.proof,
@@ -620,10 +819,14 @@ class PaybondMCPRuntime {
     async fundHarborIntent(init) {
         return this.gateway.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/fund`, {}, gatewayMutationHeaders(await this.tenantId(), init.recognitionProof, {
             ...optionalMutationHeaders(init.idempotencyKey),
-            ...(init.paymentSignature?.trim() ? { "payment-signature": init.paymentSignature.trim() } : {}),
+            ...(init.paymentSignature?.trim()
+                ? { "payment-signature": init.paymentSignature.trim() }
+                : {}),
         }));
     }
     async submitHarborEvidence(init) {
+        const extracted = extractHarborEvidenceValidationInput(init.body, init.completionPresetId);
+        this.requireEvidenceValidation(extracted);
         return this.gateway.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/evidence`, init.body, gatewayMutationHeaders(await this.tenantId(), init.recognitionProof, optionalMutationHeaders(init.idempotencyKey)));
     }
     async confirmHarborSettlement(init) {
@@ -643,16 +846,22 @@ function gatewayMutationHeaders(tenantId, recognitionProof, extraHeaders) {
         [agentRecognitionProofHeader]: encodeRecognitionProofHeader(recognitionProof),
     };
 }
+export function formatMcpStdioFrame(response) {
+    const body = JSON.stringify(response);
+    return `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`;
+}
 export class PaybondMCPServer {
     runtime;
     tools;
+    toolPolicy;
     initialized = false;
     constructor(settings) {
         if (!settings.apiKey.trim()) {
             throw new Error("PAYBOND_API_KEY is required");
         }
+        this.toolPolicy = resolveMcpToolPolicy(settings.toolPolicy ?? { policy: null, allowlist: [] });
         this.runtime = new PaybondMCPRuntime(settings);
-        this.tools = this.buildTools(settings);
+        this.tools = this.buildTools(settings).filter((tool) => toolAllowedByPolicy(tool.name, tool.annotations, this.toolPolicy));
     }
     listTools() {
         return this.tools.map((tool) => ({
@@ -660,8 +869,12 @@ export class PaybondMCPServer {
             title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
-            ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
-            ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+            ...(tool.outputSchema === undefined
+                ? {}
+                : { outputSchema: tool.outputSchema }),
+            ...(tool.annotations === undefined
+                ? {}
+                : { annotations: tool.annotations }),
         }));
     }
     async callTool(name, args = {}) {
@@ -672,9 +885,26 @@ export class PaybondMCPServer {
                 isError: true,
             };
         }
+        if (!toolAllowedByPolicy(name, tool.annotations, this.toolPolicy)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Tool blocked by ${MCP_TOOL_POLICY_ENV}=${this.toolPolicy.policy ?? "spend-write"}: ${name}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
         try {
-            const value = await tool.call(args);
-            return toToolResult(value);
+            await this.runtime.beginPolicyToolCall();
+            try {
+                const value = await tool.call(args);
+                return toToolResult(this.runtime.prepareToolResponse(value === null ? null : value, name));
+            }
+            finally {
+                await this.runtime.endPolicyToolCall();
+            }
         }
         catch (err) {
             return {
@@ -700,6 +930,7 @@ export class PaybondMCPServer {
         }
         switch (method) {
             case "initialize":
+                await this.runtime.preloadPrincipal();
                 return {
                     jsonrpc: "2.0",
                     id: message.id,
@@ -718,9 +949,10 @@ export class PaybondMCPServer {
                             websiteUrl: "https://paybond.ai",
                         },
                         instructions: "This MCP server is tenant-bound to the configured Paybond service-account API key. " +
-                            "Use paybond_create_spend_intent or paybond_fund_intent to obtain the intent_id and " +
-                            "capability_token, then call paybond_authorize_agent_spend before side-effecting tools. " +
-                            "It works with any MCP-compatible host and does not assume a specific model provider.",
+                            "Use paybond_create_spend_intent or paybond_bootstrap_sandbox_guardrail to obtain a funded intent_id, " +
+                            "then call paybond_authorize_agent_spend before side-effecting tools. Capability tokens are stored " +
+                            "inside this MCP server and are not returned to agent logs. It works with any MCP-compatible host " +
+                            "and does not assume a specific model provider.",
                     },
                 };
             case "ping":
@@ -740,7 +972,9 @@ export class PaybondMCPServer {
             case "tools/call": {
                 const params = ensureObject(message.params, "tools/call params");
                 const name = stringArg(params.name, "name");
-                const args = params.arguments === undefined ? {} : ensureObject(params.arguments, "arguments");
+                const args = params.arguments === undefined
+                    ? {}
+                    : ensureObject(params.arguments, "arguments");
                 return {
                     jsonrpc: "2.0",
                     id: message.id,
@@ -752,26 +986,36 @@ export class PaybondMCPServer {
         }
     }
     runStdio() {
-        let buffer = "";
-        process.stdin.setEncoding("utf8");
+        let buffer = Buffer.alloc(0);
         process.stdin.on("data", (chunk) => {
-            buffer += chunk;
+            buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8")]);
             while (true) {
-                const newlineIndex = buffer.indexOf("\n");
-                if (newlineIndex < 0) {
+                const headerEnd = buffer.indexOf("\r\n\r\n");
+                if (headerEnd < 0) {
                     break;
                 }
-                const line = buffer.slice(0, newlineIndex).trim();
-                buffer = buffer.slice(newlineIndex + 1);
-                if (!line) {
-                    continue;
+                const headerText = buffer.subarray(0, headerEnd).toString("ascii");
+                const contentLength = Number.parseInt(headerText
+                    .split("\r\n")
+                    .find((line) => line.toLowerCase().startsWith("content-length:"))
+                    ?.split(":", 2)[1]
+                    ?.trim() ?? "", 10);
+                if (!Number.isFinite(contentLength) || contentLength <= 0) {
+                    break;
                 }
-                void this.handleLine(line);
+                const bodyStart = headerEnd + 4;
+                const frameEnd = bodyStart + contentLength;
+                if (buffer.length < frameEnd) {
+                    break;
+                }
+                const body = buffer.subarray(bodyStart, frameEnd).toString("utf8");
+                buffer = buffer.subarray(frameEnd);
+                void this.handleLine(body);
             }
         });
         process.stdin.on("end", () => {
-            if (buffer.trim()) {
-                void this.handleLine(buffer.trim());
+            if (buffer.length > 0) {
+                void this.handleLine(buffer.toString("utf8"));
             }
         });
         process.stdin.resume();
@@ -791,7 +1035,7 @@ export class PaybondMCPServer {
         }
     }
     writeResponse(response) {
-        process.stdout.write(`${JSON.stringify(response)}\n`);
+        process.stdout.write(formatMcpStdioFrame(response));
     }
     buildTools(settings) {
         const tools = [
@@ -805,60 +1049,86 @@ export class PaybondMCPServer {
                 name: "paybond_verify_capability",
                 description: "Verify a capability token returned by a created or funded Paybond intent for one tenant-bound Harbor intent.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Canonical Harbor intent UUID.",
+                    },
                     token: {
                         type: "string",
-                        description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
+                        description: "Optional capability token override. When omitted, the MCP server uses the token stored for intent_id.",
+                    },
+                    operation: {
+                        type: "string",
+                        description: "Delegated operation or tool name.",
                     },
-                    operation: { type: "string", description: "Delegated operation or tool name." },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Optional requested spend in cents for this tool call.",
                     },
-                }, ["intent_id", "token", "operation"]),
-                call: async (args) => this.runtime.verifyCapability({
-                    intentId: uuidArg(args.intent_id, "intent_id"),
-                    token: stringArg(args.token, "token"),
-                    operation: stringArg(args.operation, "operation"),
-                    requestedSpendCents: args.requested_spend_cents === undefined
-                        ? 0
-                        : intArg(args.requested_spend_cents, "requested_spend_cents"),
-                }),
+                }, ["intent_id", "operation"]),
+                call: async (args) => {
+                    const intentId = uuidArg(args.intent_id, "intent_id");
+                    return this.runtime.authorizeAgentSpend({
+                        intentId,
+                        token: await this.runtime.resolveCapabilityToken(intentId, optionalString(args.token)),
+                        operation: stringArg(args.operation, "operation"),
+                        requestedSpendCents: args.requested_spend_cents === undefined
+                            ? undefined
+                            : intArg(args.requested_spend_cents, "requested_spend_cents"),
+                        toolName: stringArg(args.operation, "operation"),
+                    });
+                },
             },
             {
                 name: "paybond_authorize_agent_spend",
                 description: "Provider-agnostic spend gate: verify the funded intent's capability token before a side-effecting tool, paid API, vendor action, or settlement workflow executes.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Canonical Harbor intent UUID.",
+                    },
                     token: {
                         type: "string",
-                        description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
+                        description: "Optional capability token override. When omitted, the MCP server uses the token stored for intent_id.",
+                    },
+                    operation: {
+                        type: "string",
+                        description: "Delegated operation or tool name.",
                     },
-                    operation: { type: "string", description: "Delegated operation or tool name." },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Optional requested spend in cents for this tool call.",
                     },
-                }, ["intent_id", "token", "operation"]),
-                call: async (args) => this.runtime.verifyCapability({
-                    intentId: uuidArg(args.intent_id, "intent_id"),
-                    token: stringArg(args.token, "token"),
-                    operation: stringArg(args.operation, "operation"),
-                    requestedSpendCents: args.requested_spend_cents === undefined
-                        ? 0
-                        : intArg(args.requested_spend_cents, "requested_spend_cents"),
-                }),
+                }, ["intent_id", "operation"]),
+                call: async (args) => {
+                    const intentId = uuidArg(args.intent_id, "intent_id");
+                    return this.runtime.authorizeAgentSpend({
+                        intentId,
+                        token: await this.runtime.resolveCapabilityToken(intentId, optionalString(args.token)),
+                        operation: stringArg(args.operation, "operation"),
+                        requestedSpendCents: args.requested_spend_cents === undefined
+                            ? undefined
+                            : intArg(args.requested_spend_cents, "requested_spend_cents"),
+                        toolName: stringArg(args.operation, "operation"),
+                    });
+                },
             },
             {
                 name: "paybond_bootstrap_sandbox_guardrail",
                 description: "Bootstrap a sandbox-only Paybond guardrail intent for a first paid-tool integration. Tenant scope is derived from the configured service-account API key and the route never touches live settlement rails.",
                 inputSchema: objectSchema({
-                    operation: { type: "string", description: "Delegated operation or paid tool name." },
+                    operation: {
+                        type: "string",
+                        description: "Delegated operation or paid tool name.",
+                    },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Sandbox spend amount in cents to authorize for the sample tool call.",
                     },
-                    currency: { type: "string", description: "Optional ISO currency code; defaults at the gateway." },
+                    currency: {
+                        type: "string",
+                        description: "Optional ISO currency code; defaults at the gateway.",
+                    },
                     evidence_schema: { type: "object", additionalProperties: true },
                     metadata: { type: "object", additionalProperties: true },
                     idempotency_key: { type: "string" },
@@ -867,35 +1137,77 @@ export class PaybondMCPServer {
                     operation: stringArg(args.operation, "operation"),
                     requestedSpendCents: intArg(args.requested_spend_cents, "requested_spend_cents"),
                     currency: optionalString(args.currency),
-                    evidenceSchema: args.evidence_schema === undefined ? undefined : ensureObject(args.evidence_schema, "evidence_schema"),
-                    metadata: args.metadata === undefined ? undefined : ensureObject(args.metadata, "metadata"),
+                    evidenceSchema: args.evidence_schema === undefined
+                        ? undefined
+                        : ensureObject(args.evidence_schema, "evidence_schema"),
+                    metadata: args.metadata === undefined
+                        ? undefined
+                        : ensureObject(args.metadata, "metadata"),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
+            {
+                name: "paybond_validate_completion_evidence",
+                description: "Pre-validates completion evidence against the shared preset catalog. Call this before paybond_submit_*_evidence when PAYBOND_MCP_EVIDENCE_POLICY=strict.",
+                inputSchema: objectSchema({
+                    preset_id: { type: "string" },
+                    vendor_payload: { type: "object", additionalProperties: true },
+                    canonical_payload: { type: "object", additionalProperties: true },
+                    frozen_vendor_api_version: { type: "string" },
+                    frozen_vendor_schema_digest_hex: { type: "string" },
+                    frozen_canonical_schema_digest_hex: { type: "string" },
+                }, ["preset_id"]),
+                call: async (args) => this.runtime.validateCompletionEvidence({
+                    presetId: stringArg(args.preset_id, "preset_id"),
+                    vendorPayload: args.vendor_payload === undefined
+                        ? undefined
+                        : ensureObject(args.vendor_payload, "vendor_payload"),
+                    canonicalPayload: args.canonical_payload === undefined
+                        ? undefined
+                        : ensureObject(args.canonical_payload, "canonical_payload"),
+                    frozenVendorApiVersion: optionalString(args.frozen_vendor_api_version),
+                    frozenVendorSchemaDigestHex: optionalString(args.frozen_vendor_schema_digest_hex),
+                    frozenCanonicalSchemaDigestHex: optionalString(args.frozen_canonical_schema_digest_hex),
+                }),
+            },
             {
                 name: "paybond_submit_sandbox_guardrail_evidence",
                 description: "Submit evidence for a sandbox-only Paybond guardrail intent. Tenant scope is derived from the configured service-account API key and simulator settlement remains sandbox-only.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Sandbox guardrail intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Sandbox guardrail intent UUID.",
+                    },
                     payload: { type: "object", additionalProperties: true },
                     artifacts: { type: "array", items: { type: "string" } },
-                    operation: { type: "string", description: "Optional operation override for the evidence record." },
+                    operation: {
+                        type: "string",
+                        description: "Optional operation override for the evidence record.",
+                    },
                     requested_spend_cents: {
                         type: "integer",
                         description: "Optional sandbox spend amount override for the evidence record.",
                     },
                     metadata: { type: "object", additionalProperties: true },
+                    completion_preset_id: { type: "string" },
                     idempotency_key: { type: "string" },
                 }, ["intent_id"]),
                 call: async (args) => this.runtime.submitSandboxGuardrailEvidence({
                     intentId: uuidArg(args.intent_id, "intent_id"),
-                    payload: args.payload === undefined ? undefined : ensureObject(args.payload, "payload"),
-                    artifacts: args.artifacts === undefined ? undefined : stringArrayArg(args.artifacts, "artifacts"),
+                    payload: args.payload === undefined
+                        ? undefined
+                        : ensureObject(args.payload, "payload"),
+                    artifacts: args.artifacts === undefined
+                        ? undefined
+                        : stringArrayArg(args.artifacts, "artifacts"),
                     operation: optionalString(args.operation),
                     requestedSpendCents: args.requested_spend_cents === undefined
                         ? undefined
                         : intArg(args.requested_spend_cents, "requested_spend_cents"),
-                    metadata: args.metadata === undefined ? undefined : ensureObject(args.metadata, "metadata"),
+                    metadata: args.metadata === undefined
+                        ? undefined
+                        : ensureObject(args.metadata, "metadata"),
+                    completionPresetId: optionalString(args.completion_preset_id),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -919,7 +1231,10 @@ export class PaybondMCPServer {
                 name: "paybond_get_intent",
                 description: "Fetch one tenant-scoped Harbor intent detail through the gateway operator view.",
                 inputSchema: objectSchema({
-                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    intent_id: {
+                        type: "string",
+                        description: "Canonical Harbor intent UUID.",
+                    },
                 }, ["intent_id"]),
                 call: async (args) => this.runtime.getIntent(uuidArg(args.intent_id, "intent_id")),
             },
@@ -999,20 +1314,17 @@ export class PaybondMCPServer {
             },
             {
                 name: "paybond_verify_agent_recognition_proof_v1",
-                description: "Verify a replay-safe AgentRecognitionProofV1 against an expected purpose, verifier context, and request envelope.",
+                description: "Verify a replay-safe AgentRecognitionProofV1 against an expected purpose and request envelope. " +
+                    "Verifier context (tenant_id, verifier_id) is derived from the authenticated MCP session only.",
                 inputSchema: objectSchema({
                     proof: { type: "object", additionalProperties: true },
                     expected_purpose: { type: "string" },
                     expected_request: { type: "object", additionalProperties: true },
-                    expected_verifier: { type: "object", additionalProperties: true },
                 }, ["proof", "expected_purpose", "expected_request"]),
                 call: async (args) => this.runtime.verifyAgentRecognitionProofV1({
                     proof: ensureObject(args.proof, "proof"),
                     expectedPurpose: stringArg(args.expected_purpose, "expected_purpose"),
                     expectedRequest: ensureObject(args.expected_request, "expected_request"),
-                    expectedVerifier: args.expected_verifier === undefined
-                        ? undefined
-                        : ensureObject(args.expected_verifier, "expected_verifier"),
                 }),
             },
             {
@@ -1100,12 +1412,14 @@ export class PaybondMCPServer {
                     intent_id: { type: "string" },
                     body: { type: "object", additionalProperties: true },
                     recognition_proof: { type: "object", additionalProperties: true },
+                    completion_preset_id: { type: "string" },
                     idempotency_key: { type: "string" },
                 }, ["intent_id", "body", "recognition_proof"]),
                 call: async (args) => this.runtime.submitHarborEvidence({
                     intentId: uuidArg(args.intent_id, "intent_id"),
                     body: ensureObject(args.body, "body"),
                     recognitionProof: ensureObject(args.recognition_proof, "recognition_proof"),
+                    completionPresetId: optionalString(args.completion_preset_id),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -1116,12 +1430,14 @@ export class PaybondMCPServer {
                     intent_id: { type: "string" },
                     body: { type: "object", additionalProperties: true },
                     recognition_proof: { type: "object", additionalProperties: true },
+                    completion_preset_id: { type: "string" },
                     idempotency_key: { type: "string" },
                 }, ["intent_id", "body", "recognition_proof"]),
                 call: async (args) => this.runtime.submitHarborEvidence({
                     intentId: uuidArg(args.intent_id, "intent_id"),
                     body: ensureObject(args.body, "body"),
                     recognitionProof: ensureObject(args.recognition_proof, "recognition_proof"),
+                    completionPresetId: optionalString(args.completion_preset_id),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -1152,14 +1468,18 @@ export function settingsFromEnv(env = process.env) {
         throw new Error("PAYBOND_API_KEY is required; run paybond login or configure your MCP host environment");
     }
     return {
-        gatewayBaseUrl: optionalEnv(env.PAYBOND_GATEWAY_URL) ??
+        gatewayBaseUrl: requireSecureGatewayUrl(optionalEnv(env.PAYBOND_GATEWAY_URL) ??
             optionalEnv(env.PAYBOND_GATEWAY_BASE_URL) ??
-            DEFAULT_PAYBOND_GATEWAY_BASE_URL,
+            DEFAULT_PAYBOND_GATEWAY_BASE_URL),
         apiKey,
         principalPath: optionalEnv(env.PAYBOND_PRINCIPAL_PATH) ?? DEFAULT_PRINCIPAL_PATH,
         maxRetries: optionalEnv(env.PAYBOND_MCP_MAX_RETRIES)
             ? intArg(optionalEnv(env.PAYBOND_MCP_MAX_RETRIES), "PAYBOND_MCP_MAX_RETRIES")
             : 3,
+        toolPolicy: resolveMcpToolPolicy(mergeMcpToolPolicy(parseMcpToolPolicy(optionalEnv(env[MCP_TOOL_POLICY_ENV])), parseMcpToolAllowlist(optionalEnv(env[MCP_TOOL_ALLOWLIST_ENV])))),
+        evidencePolicy: parseMcpEvidencePolicy(optionalEnv(env[MCP_EVIDENCE_POLICY_ENV])),
+        policyReload: parseMcpPolicyReloadConfig(env),
+        capabilityTokenCache: parseMcpCapabilityTokenCacheConfig(env),
     };
 }
 export function main(argv = process.argv.slice(2)) {
@@ -1182,7 +1502,7 @@ export function main(argv = process.argv.slice(2)) {
     }
 }
 function normalizeBase(url) {
-    return url.trim().replace(/\/+$/, "");
+    return requireSecureGatewayUrl(url);
 }
 function parseJSONObject(text, context) {
     let parsed;
@@ -1314,18 +1634,6 @@ function toToolResult(value) {
         structuredContent: value,
     };
 }
-function jsonObjectFromValue(value) {
-    if (value === null) {
-        return {};
-    }
-    if (Array.isArray(value)) {
-        return { items: value };
-    }
-    if (typeof value !== "object") {
-        return { value };
-    }
-    return JSON.parse(JSON.stringify(value));
-}
 function responseError(id, code, message) {
     return {
         jsonrpc: "2.0",
@@ -1356,28 +1664,21 @@ function optionalEnv(value) {
     return value?.trim() ? value.trim() : undefined;
 }
 function formatError(err) {
-    if (err instanceof Error ||
-        err instanceof GatewayAuthError ||
-        err instanceof GatewayHTTPError ||
-        err instanceof SignalHttpError) {
+    if (err instanceof Error) {
         return err.message;
     }
     return String(err);
 }
 function normalizeFileURL(url) {
-    return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
+    return url.startsWith("file:///var/")
+        ? url.replace("file:///var/", "file:///private/var/")
+        : url;
 }
 async function invokedFromCLI() {
     const scriptPath = process.argv[1];
     if (!scriptPath) {
         return false;
     }
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const fs = (await import("node:fs/promises"));
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const path = (await import("node:path"));
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const url = (await import("node:url"));
     async function realFileURL(filePath) {
         let resolved = path.resolve(filePath);
         try {
@@ -1387,14 +1688,21 @@ async function invokedFromCLI() {
             // If realpath fails, compare the absolute path. This keeps direct execution
             // working even when the script path disappears during process startup.
         }
-        return normalizeFileURL(url.pathToFileURL(resolved).href);
+        return normalizeFileURL(pathToFileURL(resolved).href);
     }
-    return (await realFileURL(scriptPath)) === (await realFileURL(url.fileURLToPath(import.meta.url)));
+    return ((await realFileURL(scriptPath)) ===
+        (await realFileURL(fileURLToPath(import.meta.url))));
 }
 invokedFromCLI().then((invoked) => {
-    if (invoked && main() !== 0) {
-        process.exitCode = 1;
+    if (!invoked) {
+        return;
     }
+    runCli(["mcp", "serve", ...process.argv.slice(2)]).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        process.stderr.write(`${formatError(err)}\n`);
+        process.exitCode = 1;
+    });
 }, (err) => {
     process.stderr.write(`${formatError(err)}\n`);
     process.exitCode = 1;