@paybond/kit 0.9.6 → 0.9.8

package/README.md

@@ -1,5 +1,7 @@
 # `@paybond/kit`
 
+<!-- mcp-name: io.github.nonameuserd/paybond -->
+
 Paybond Kit for TypeScript is the npm package for tenant-bound Paybond integrations and delegated agent spend controls. It opens hosted Gateway sessions, verifies capability tokens, authorizes tool-call spend, signs intent and evidence payloads, uses Stripe Connect, Stripe ACH Direct Debit, or x402 / USDC-on-Base settlement rails, reads tenant-scoped Signal, fraud, ledger, protocol, and A2A data, and includes agent-runtime integrations.
 
 Paybond is the SDK to use when you do not want to build your own delegated agent spend-governance middleware. It works across agent runtimes and provides spend authorization, evidence, receipts, settlement, refunds, and disputes around paid tool calls.

package/dist/index.d.ts

@@ -4,6 +4,10 @@
  */
 import { type BuildSignedCreateIntentParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
+export type SpendScope = {
+    scope_type: string;
+    scope_key: string;
+};
 export type VerifyCapabilityResult = {
     allow: boolean;
     auditId: string;
@@ -11,6 +15,28 @@ export type VerifyCapabilityResult = {
     intentId: string;
     code?: string;
     message?: string;
+    decisionId?: string;
+    approvalRequestId?: string;
+    policyVersion?: number;
+    reasonCodes?: string[];
+    spendScope?: SpendScope;
+    remainingCents?: number;
+    retryAfter?: number;
+    /** True when gateway policy requires operator approval before execution may proceed. */
+    approvalRequired?: boolean;
+};
+export type PaybondSpendAuthorizationInput = {
+    operation: string;
+    requestedSpendCents?: number;
+    vendorId?: string;
+    taskId?: string;
+    workflowId?: string;
+    toolCallId?: string;
+    toolName?: string;
+    currency?: string;
+    agentSubject?: string;
+    approvalToken?: string;
+    idempotencyKey?: string;
 };
 export type SubmitEvidenceResult = {
     intentId: string;
@@ -715,14 +741,19 @@ export declare class PaybondCapabilityBinding {
     authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
 }
 export type PaybondSpendGuardInit = {
-    harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
+    harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability"> & {
+        completeSpendDecision?: (input: {
+            decisionId: string;
+            outcome: "consumed" | "released";
+        }) => Promise<void>;
+    };
     intentId: string;
     capabilityToken: string;
 };
-export type PaybondSpendAuthorizationInput = {
-    operation: string;
-    requestedSpendCents?: number;
-};
+export declare class PaybondSpendApprovalRequiredError extends Error {
+    readonly result: VerifyCapabilityResult;
+    constructor(result: VerifyCapabilityResult);
+}
 export declare class PaybondSpendDeniedError extends Error {
     readonly result: VerifyCapabilityResult;
     constructor(result: VerifyCapabilityResult);
@@ -730,13 +761,15 @@ export declare class PaybondSpendDeniedError extends Error {
 export type PaybondToolHandler<TArgs extends unknown[], TResult> = (...args: TArgs) => TResult | Promise<TResult>;
 export type PaybondGuardedToolHandler<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<Awaited<TResult>>;
 export declare class PaybondSpendGuard {
-    readonly harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
+    readonly harbor: PaybondSpendGuardInit["harbor"];
     readonly intentId: string;
     readonly capabilityToken: string;
     constructor(init: PaybondSpendGuardInit | PaybondCapabilityBinding);
     verifySpendCapability(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
     authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
     assertSpendAuthorized(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+    /** Finalizes scope reservations tied to an authorization decision after tool execution. */
+    completeSpendAuthorization(decisionId: string, outcome: "consumed" | "released"): Promise<void>;
     guardTool<TArgs extends unknown[], TResult>(input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
 }
 export declare function authorizeSpend(source: PaybondSpendGuardInit | PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
@@ -799,11 +832,9 @@ export declare class HarborClient {
      * @throws HarborHttpError when HTTP fails
      * @throws Error when Harbor echoes a different tenant / intent than requested
      */
-    verifyCapability(input: {
+    verifyCapability(input: PaybondSpendAuthorizationInput & {
         intentId: string;
         token: string;
-        operation: string;
-        requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
     verifySpendCapability(input: {
         intentId: string;
@@ -897,11 +928,9 @@ export declare class GatewayHarborClient {
     private fetchWithRetries;
     private postJSON;
     private mutationHeaders;
-    verifyCapability(input: {
+    verifyCapability(input: PaybondSpendAuthorizationInput & {
         intentId: string;
         token: string;
-        operation: string;
-        requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
     verifySpendCapability(input: {
         intentId: string;
@@ -915,6 +944,11 @@ export declare class GatewayHarborClient {
         operation: string;
         requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
+    /** Finalizes active spend reservations after tool execution completes or is aborted. */
+    completeSpendDecision(input: {
+        decisionId: string;
+        outcome: "consumed" | "released";
+    }): Promise<void>;
     createIntent(body: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<Record<string, unknown>>;
     fundIntent(intentId: string, options: GatewayHarborMutationOptions & {
         paymentSignature?: string;

package/dist/index.js

@@ -4,6 +4,77 @@
  */
 import { buildSignedCreateIntentBody, } from "./principal-intent.js";
 import { signPayeeEvidenceBinding } from "./payee-evidence.js";
+function parseVerifyCapabilityBody(body, expectedTenant, expectedIntentId) {
+    const tenant = String(body.tenant ?? "");
+    const intentId = String(body.intent_id ?? "");
+    if (tenant !== expectedTenant) {
+        throw new Error(`verify tenant mismatch: client=${expectedTenant} remote=${tenant}`);
+    }
+    if (intentId !== expectedIntentId) {
+        throw new Error(`verify intent mismatch: requested=${expectedIntentId} remote=${intentId}`);
+    }
+    const reasonCodes = Array.isArray(body.reason_codes)
+        ? body.reason_codes.map((value) => String(value))
+        : undefined;
+    const spendScope = body.spend_scope && typeof body.spend_scope === "object" && !Array.isArray(body.spend_scope)
+        ? {
+            scope_type: String(body.spend_scope.scope_type ?? ""),
+            scope_key: String(body.spend_scope.scope_key ?? ""),
+        }
+        : undefined;
+    const code = body.code != null ? String(body.code) : undefined;
+    const approvalRequired = code === "approval_required" ||
+        reasonCodes?.includes("approval_threshold_exceeded") ||
+        reasonCodes?.includes("approval_required_pending") ||
+        reasonCodes?.includes("anomaly_new_vendor") ||
+        reasonCodes?.includes("anomaly_amount_spike") ||
+        reasonCodes?.includes("anomaly_rapid_auth") ||
+        reasonCodes?.includes("anomaly_cap_proximity") ||
+        false;
+    return {
+        allow: Boolean(body.allow),
+        auditId: String(body.audit_id ?? ""),
+        tenant,
+        intentId,
+        code,
+        message: body.message != null ? String(body.message) : undefined,
+        decisionId: body.decision_id != null ? String(body.decision_id) : undefined,
+        approvalRequestId: body.approval_request_id != null ? String(body.approval_request_id) : undefined,
+        policyVersion: typeof body.policy_version === "number" ? body.policy_version : undefined,
+        reasonCodes,
+        spendScope,
+        remainingCents: typeof body.remaining_cents === "number" ? body.remaining_cents : undefined,
+        retryAfter: typeof body.retry_after === "number" ? body.retry_after : undefined,
+        approvalRequired,
+    };
+}
+function verifyCapabilityPayload(input) {
+    const payload = {
+        intent_id: input.intentId,
+        token: input.token,
+        operation: input.operation,
+        requested_spend_cents: input.requestedSpendCents ?? 0,
+    };
+    if (input.vendorId?.trim())
+        payload.vendor_id = input.vendorId.trim();
+    if (input.taskId?.trim())
+        payload.task_id = input.taskId.trim();
+    if (input.workflowId?.trim())
+        payload.workflow_id = input.workflowId.trim();
+    if (input.toolCallId?.trim())
+        payload.tool_call_id = input.toolCallId.trim();
+    if (input.toolName?.trim())
+        payload.tool_name = input.toolName.trim();
+    if (input.currency?.trim())
+        payload.currency = input.currency.trim();
+    if (input.agentSubject?.trim())
+        payload.agent_subject = input.agentSubject.trim();
+    if (input.approvalToken?.trim())
+        payload.approval_token = input.approvalToken.trim();
+    if (input.idempotencyKey?.trim())
+        payload.idempotency_key = input.idempotencyKey.trim();
+    return payload;
+}
 export const DEFAULT_PAYBOND_GATEWAY_BASE_URL = "https://api.paybond.ai";
 function defaultGatewayBaseUrl(value) {
     const trimmed = value?.trim();
@@ -158,16 +229,24 @@ export class PaybondCapabilityBinding {
     }
     async verifySpendCapability(input) {
         return this.harbor.verifyCapability({
+            ...input,
             intentId: this.intentId,
             token: this.capabilityToken,
-            operation: input.operation,
-            requestedSpendCents: input.requestedSpendCents,
         });
     }
     async authorizeSpend(input) {
         return this.verifySpendCapability(input);
     }
 }
+export class PaybondSpendApprovalRequiredError extends Error {
+    result;
+    constructor(result) {
+        const reason = result.message ?? result.code ?? "approval_required";
+        super(`Paybond spend authorization requires approval: ${reason}`);
+        this.name = "PaybondSpendApprovalRequiredError";
+        this.result = result;
+    }
+}
 export class PaybondSpendDeniedError extends Error {
     result;
     constructor(result) {
@@ -188,10 +267,9 @@ export class PaybondSpendGuard {
     }
     async verifySpendCapability(input) {
         return this.harbor.verifyCapability({
+            ...input,
             intentId: this.intentId,
             token: this.capabilityToken,
-            operation: input.operation,
-            requestedSpendCents: input.requestedSpendCents,
         });
     }
     async authorizeSpend(input) {
@@ -200,14 +278,42 @@ export class PaybondSpendGuard {
     async assertSpendAuthorized(input) {
         const result = await this.authorizeSpend(input);
         if (!result.allow) {
+            if (result.approvalRequired) {
+                throw new PaybondSpendApprovalRequiredError(result);
+            }
             throw new PaybondSpendDeniedError(result);
         }
         return result;
     }
+    /** Finalizes scope reservations tied to an authorization decision after tool execution. */
+    async completeSpendAuthorization(decisionId, outcome) {
+        const complete = this.harbor.completeSpendDecision;
+        if (!complete) {
+            return;
+        }
+        await complete.call(this.harbor, { decisionId, outcome });
+    }
     guardTool(input, handler) {
         return async (...args) => {
-            await this.assertSpendAuthorized(input);
-            return await handler(...args);
+            const auth = await this.assertSpendAuthorized(input);
+            try {
+                const result = await handler(...args);
+                if (auth.decisionId) {
+                    await this.completeSpendAuthorization(auth.decisionId, "consumed");
+                }
+                return result;
+            }
+            catch (err) {
+                if (auth.decisionId) {
+                    try {
+                        await this.completeSpendAuthorization(auth.decisionId, "released");
+                    }
+                    catch {
+                        // Best-effort release when the guarded handler fails.
+                    }
+                }
+                throw err;
+            }
         };
     }
 }
@@ -245,6 +351,9 @@ export function paybondRuntimeToolCallAdapter(init) {
             if (init.onDeny) {
                 return await init.onDeny(result, call);
             }
+            if (result.approvalRequired) {
+                throw new PaybondSpendApprovalRequiredError(result);
+            }
             throw new PaybondSpendDeniedError(result);
         }
         return await init.execute(call);
@@ -384,17 +493,13 @@ export class HarborClient {
      */
     async verifyCapability(input) {
         const url = `${this.base}verify`;
-        const payload = {
-            intent_id: input.intentId,
-            token: input.token,
-            operation: input.operation,
-            requested_spend_cents: input.requestedSpendCents ?? 0,
-        };
+        const payload = verifyCapabilityPayload(input);
         const res = await this.fetchWithRetries(url, {
             method: "POST",
             headers: {
                 "content-type": "application/json",
                 "x-tenant-id": this.tenantId,
+                ...(input.idempotencyKey?.trim() ? { "idempotency-key": input.idempotencyKey.trim() } : {}),
             },
             body: JSON.stringify(payload),
         }, { retryBody: payload });
@@ -407,20 +512,7 @@ export class HarborClient {
             });
         }
         const body = JSON.parse(text);
-        if (body.tenant !== this.tenantId) {
-            throw new Error(`verify tenant mismatch: client=${this.tenantId} harbor=${body.tenant}`);
-        }
-        if (body.intent_id !== input.intentId) {
-            throw new Error(`verify intent mismatch: requested=${input.intentId} harbor=${body.intent_id}`);
-        }
-        return {
-            allow: body.allow,
-            auditId: body.audit_id,
-            tenant: body.tenant,
-            intentId: body.intent_id,
-            code: body.code,
-            message: body.message,
-        };
+        return parseVerifyCapabilityBody(body, this.tenantId, input.intentId);
     }
     async verifySpendCapability(input) {
         return this.verifyCapability(input);
@@ -722,13 +814,12 @@ export class GatewayHarborClient {
         });
     }
     async verifyCapability(input) {
-        const payload = {
-            intent_id: input.intentId,
-            token: input.token,
-            operation: input.operation,
-            requested_spend_cents: input.requestedSpendCents ?? 0,
-        };
-        const { res, text, url } = await this.postJSON("/verify", payload);
+        const payload = verifyCapabilityPayload(input);
+        const headers = {};
+        if (input.idempotencyKey?.trim()) {
+            headers["idempotency-key"] = input.idempotencyKey.trim();
+        }
+        const { res, text, url } = await this.postJSON("/verify", payload, headers);
         if (!res.ok) {
             throw new HarborHttpError(`Gateway verify HTTP ${res.status}: ${text}`, {
                 statusCode: res.status,
@@ -737,20 +828,7 @@ export class GatewayHarborClient {
             });
         }
         const body = JSON.parse(text);
-        if (body.tenant !== this.tenantId) {
-            throw new Error(`verify tenant mismatch: client=${this.tenantId} gateway=${body.tenant}`);
-        }
-        if (body.intent_id !== input.intentId) {
-            throw new Error(`verify intent mismatch: requested=${input.intentId} gateway=${body.intent_id}`);
-        }
-        return {
-            allow: body.allow,
-            auditId: body.audit_id,
-            tenant: body.tenant,
-            intentId: body.intent_id,
-            code: body.code,
-            message: body.message,
-        };
+        return parseVerifyCapabilityBody(body, this.tenantId, input.intentId);
     }
     async verifySpendCapability(input) {
         return this.verifyCapability(input);
@@ -758,6 +836,17 @@ export class GatewayHarborClient {
     async authorizeSpend(input) {
         return this.verifyCapability(input);
     }
+    /** Finalizes active spend reservations after tool execution completes or is aborted. */
+    async completeSpendDecision(input) {
+        const { res, text, url } = await this.postJSON(`/v1/spend/decisions/${encodeURIComponent(input.decisionId)}/complete`, { outcome: input.outcome });
+        if (!res.ok) {
+            throw new HarborHttpError(`Gateway spend complete HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+    }
     async createIntent(body, options) {
         const { res, text, url } = await this.postJSON("/harbor/intents", body, this.mutationHeaders("createIntent", options));
         if (!res.ok) {

package/dist/init.js

@@ -170,7 +170,7 @@ export async function openPaybondFromEnv(options: OpenPaybondFromEnvOptions = {}
 
   return Paybond.open({
     apiKey,
-    gatewayBaseUrl: process.env.PAYBOND_GATEWAY_BASE_URL,
+    gatewayBaseUrl: process.env.PAYBOND_GATEWAY_URL ?? process.env.PAYBOND_GATEWAY_BASE_URL,
     expectedEnvironment: "sandbox",
   });
 }

package/dist/mcp-server.js

@@ -3,12 +3,276 @@
 import { readFileSync } from "node:fs";
 import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.6.0";
+const SERVER_VERSION = "0.9.8";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";
 const agentRecognitionProofHeader = "x-paybond-agent-recognition-proof";
 const DEFAULT_ENV_FILE = ".env.local";
+const TOOL_SELECTION_METADATA = {
+    paybond_get_principal: {
+        title: "Get Paybond Principal",
+        annotations: readOnlyToolAnnotations("Get Paybond Principal"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string", description: "Tenant bound to the configured Paybond API key." },
+            subject: { type: "string" },
+            roles: { type: "array", items: { type: "string" } },
+        }),
+    },
+    paybond_verify_capability: {
+        title: "Verify Paybond Capability",
+        description: "Use this when you need raw capability-token verification for one tenant-bound Harbor intent. " +
+            "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." },
+        }, ["tenant", "intent_id"]),
+    },
+    paybond_authorize_agent_spend: {
+        title: "Authorize Agent Spend",
+        description: "Use this when an agent has an intent_id and capability_token and needs a tenant-bound spend gate before calling a side-effecting tool, paid API, vendor action, or settlement workflow. " +
+            "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." },
+        }, ["tenant", "intent_id"]),
+    },
+    paybond_bootstrap_sandbox_guardrail: {
+        title: "Bootstrap Sandbox Guardrail",
+        description: "Use this when building or testing a first paid-tool integration and you need a sandbox-only guardrail intent with no live settlement rails. " +
+            "Do not use this for production live money movement or already-created Harbor intents.",
+        annotations: additiveMutationToolAnnotations("Bootstrap Sandbox Guardrail"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            intent_id: { type: "string" },
+            capability_token: { type: "string" },
+            operation: { type: "string" },
+            requested_spend_cents: { type: "integer" },
+            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"]),
+    },
+    paybond_submit_sandbox_guardrail_evidence: {
+        title: "Submit Sandbox Guardrail Evidence",
+        description: "Use this when a sandbox guardrail intent needs evidence to complete simulator settlement or predicate checks. " +
+            "Do not use this for live Harbor spend evidence; use paybond_submit_spend_evidence for production spend intents.",
+        annotations: additiveMutationToolAnnotations("Submit Sandbox Guardrail Evidence"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            intent_id: { type: "string" },
+            operation: { type: "string" },
+            requested_spend_cents: { type: "integer" },
+            sandbox_lifecycle_status: { type: "string" },
+            predicate_passed: { type: "boolean" },
+            payload_digest: { type: "string" },
+        }, ["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 } },
+            next_cursor: { type: "string" },
+        }),
+    },
+    paybond_get_intent: {
+        title: "Get Harbor Intent",
+        annotations: readOnlyToolAnnotations("Get Harbor Intent"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            tenant_id: { type: "string" },
+        }),
+    },
+    paybond_get_reputation_receipt: {
+        title: "Get Reputation Receipt",
+        annotations: readOnlyToolAnnotations("Get Reputation Receipt"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            operator_did: { type: "string" },
+            signature_hex: { type: "string" },
+        }),
+    },
+    paybond_get_portfolio_summary: {
+        title: "Get Portfolio Summary",
+        annotations: readOnlyToolAnnotations("Get Portfolio Summary"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            score_model_version: { type: "string" },
+            operators: { type: "array", items: { type: "object", additionalProperties: true } },
+        }),
+    },
+    paybond_get_signed_portfolio_artifact: {
+        title: "Get Signed Portfolio Artifact",
+        annotations: readOnlyToolAnnotations("Get Signed Portfolio Artifact"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            kind: { type: "string" },
+            signature_hex: { type: "string" },
+            checkpoint_last_ledger_seq: { type: "integer" },
+        }),
+    },
+    paybond_get_fraud_assessment: {
+        title: "Get Fraud Assessment",
+        annotations: readOnlyToolAnnotations("Get Fraud Assessment"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            operator_did: { type: "string" },
+            fraud_assessment: { type: "object", additionalProperties: true },
+        }),
+    },
+    paybond_get_fraud_metrics: {
+        title: "Get Fraud Metrics",
+        annotations: readOnlyToolAnnotations("Get Fraud Metrics"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            window: { type: "string" },
+            flagged_operator_count: { type: "integer" },
+            critical_signal_count: { type: "integer" },
+        }),
+    },
+    paybond_get_a2a_agent_card: {
+        title: "Get A2A Agent Card",
+        annotations: readOnlyToolAnnotations("Get A2A Agent Card"),
+        outputSchema: outputObjectSchema({
+            name: { type: "string" },
+            version: { type: "string" },
+            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 } },
+        }),
+    },
+    paybond_get_a2a_task_contract: {
+        title: "Get A2A Task Contract",
+        annotations: readOnlyToolAnnotations("Get A2A Task Contract"),
+        outputSchema: outputObjectSchema({
+            id: { type: "string" },
+            name: { type: "string" },
+            description: { type: "string" },
+        }),
+    },
+    paybond_verify_agent_mandate_v1: {
+        title: "Verify Agent Mandate",
+        annotations: readOnlyToolAnnotations("Verify Agent Mandate"),
+        outputSchema: outputObjectSchema({
+            valid: { type: "boolean" },
+            mandate_digest_sha256_hex: { type: "string" },
+        }),
+    },
+    paybond_verify_agent_recognition_proof_v1: {
+        title: "Verify Agent Recognition Proof",
+        annotations: readOnlyToolAnnotations("Verify Agent Recognition Proof"),
+        outputSchema: outputObjectSchema({
+            valid: { type: "boolean" },
+            proof: { type: "object", additionalProperties: true },
+        }),
+    },
+    paybond_import_agent_mandate_v1: {
+        title: "Import Agent Mandate",
+        annotations: additiveMutationToolAnnotations("Import Agent Mandate"),
+        outputSchema: outputObjectSchema({
+            valid: { type: "boolean" },
+            intent_id: { type: "string" },
+            mandate_digest_sha256_hex: { type: "string" },
+            authorization_receipt: { type: "object", additionalProperties: true },
+        }),
+    },
+    paybond_get_settlement_receipt_v1: {
+        title: "Get Settlement Receipt",
+        annotations: readOnlyToolAnnotations("Get Settlement Receipt"),
+        outputSchema: outputObjectSchema({
+            tenant_id: { type: "string" },
+            receipt_id: { type: "string" },
+            intent_id: { type: "string" },
+        }, ["tenant_id", "receipt_id"]),
+    },
+    paybond_verify_protocol_receipt_v1: {
+        title: "Verify Protocol Receipt",
+        annotations: readOnlyToolAnnotations("Verify Protocol Receipt"),
+        outputSchema: outputObjectSchema({
+            valid: { type: "boolean" },
+            receipt_id: { type: "string" },
+        }),
+    },
+    paybond_create_intent: {
+        title: "Create Harbor Intent",
+        description: "Use this when you already have a fully signed Harbor intent request body and replay-safe recognition proof for the gateway /harbor/intents route. " +
+            "Do not use this for the normal agent spend-control path unless you specifically need the low-level Harbor API; prefer paybond_create_spend_intent.",
+        annotations: additiveMutationToolAnnotations("Create Harbor Intent"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            capability_token: { type: "string" },
+        }),
+    },
+    paybond_create_spend_intent: {
+        title: "Create Spend Intent",
+        description: "Use this when an agent workflow needs a new Paybond spend intent with bounded budget, allowed operations, evidence requirements, and settlement review. " +
+            "Do not use this for checking an already funded capability token; use paybond_authorize_agent_spend before the paid action.",
+        annotations: additiveMutationToolAnnotations("Create Spend Intent"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            capability_token: { type: "string" },
+        }),
+    },
+    paybond_fund_intent: {
+        title: "Fund Intent",
+        description: "Use this when an existing Harbor intent needs to advance through funding via the gateway and you have a replay-safe recognition proof. " +
+            "Do not use this to create a new intent or to authorize a downstream tool call; use the returned intent_id and capability_token with paybond_authorize_agent_spend.",
+        annotations: liveMutationToolAnnotations("Fund Intent"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            capability_token: { type: "string" },
+        }),
+    },
+    paybond_submit_evidence: {
+        title: "Submit Harbor Evidence",
+        description: "Use this when you already have a Harbor evidence request body and recognition proof for the gateway /harbor/intents/{id}/evidence route. " +
+            "Do not use this for the high-level spend-control path unless you need the low-level Harbor API; prefer paybond_submit_spend_evidence.",
+        annotations: additiveMutationToolAnnotations("Submit Harbor Evidence"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            evidence_id: { type: "string" },
+        }),
+    },
+    paybond_submit_spend_evidence: {
+        title: "Submit Spend Evidence",
+        description: "Use this when a Paybond spend intent needs signed evidence so release, refund, review, and receipt generation use the same audit-ready record. " +
+            "Do not use this to create or fund intents, and do not use it for sandbox guardrail evidence.",
+        annotations: additiveMutationToolAnnotations("Submit Spend Evidence"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            evidence_id: { type: "string" },
+        }),
+    },
+    paybond_confirm_settlement: {
+        title: "Confirm Settlement",
+        description: "Use this when a Harbor intent is ready for final settlement confirmation and you have the signed body plus recognition proof. " +
+            "Do not use this for evidence submission or capability authorization.",
+        annotations: liveMutationToolAnnotations("Confirm Settlement"),
+        outputSchema: outputObjectSchema({
+            intent_id: { type: "string" },
+            state: { type: "string" },
+            receipt_id: { type: "string" },
+        }),
+    },
+};
 function readEnvFileValue(envFile, key) {
     let body;
     try {
@@ -393,8 +657,11 @@ export class PaybondMCPServer {
     listTools() {
         return this.tools.map((tool) => ({
             name: tool.name,
+            title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+            ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
         }));
     }
     async callTool(name, args = {}) {
@@ -445,7 +712,10 @@ export class PaybondMCPServer {
                         },
                         serverInfo: {
                             name: SERVER_NAME,
+                            title: "Paybond MCP",
                             version: SERVER_VERSION,
+                            description: "Tenant-bound Paybond gateway tools for agent spend controls, Harbor intents, Signal reputation, fraud review, and protocol verification.",
+                            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 " +
@@ -872,7 +1142,7 @@ export class PaybondMCPServer {
                 }),
             },
         ];
-        return tools;
+        return tools.map((tool) => toolWithSelectionMetadata(tool));
     }
 }
 export function settingsFromEnv(env = process.env) {
@@ -882,7 +1152,9 @@ 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_BASE_URL) ?? DEFAULT_PAYBOND_GATEWAY_BASE_URL,
+        gatewayBaseUrl: optionalEnv(env.PAYBOND_GATEWAY_URL) ??
+            optionalEnv(env.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)
@@ -985,6 +1257,52 @@ function emptyObjectSchema() {
         additionalProperties: false,
     };
 }
+function outputObjectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        additionalProperties: true,
+        ...(required.length === 0 ? {} : { required }),
+    };
+}
+function readOnlyToolAnnotations(title) {
+    return {
+        title,
+        readOnlyHint: true,
+        openWorldHint: false,
+    };
+}
+function additiveMutationToolAnnotations(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    };
+}
+function liveMutationToolAnnotations(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    };
+}
+function toolWithSelectionMetadata(tool) {
+    const metadata = TOOL_SELECTION_METADATA[tool.name];
+    if (metadata === undefined) {
+        throw new Error(`missing MCP tool selection metadata for ${tool.name}`);
+    }
+    return {
+        ...tool,
+        title: metadata.title,
+        description: metadata.description ?? tool.description,
+        outputSchema: metadata.outputSchema,
+        annotations: metadata.annotations,
+    };
+}
 function toToolResult(value) {
     if (value === null) {
         return {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@paybond/kit",
-  "version": "0.9.6",
+  "version": "0.9.8",
+  "mcpName": "io.github.nonameuserd/paybond",
   "description": "Paybond Kit for TypeScript: agent spend governance for paid tool calls with spend authorization, evidence receipts, refunds, disputes, hosted Gateway sessions, and settlement.",
   "license": "Apache-2.0",
   "type": "module",