Add vault payment MCP tools

[hiroTamada]

Summary

Expose payment-vault preparation and observation through the existing MCP server using the published TypeScript SDK v0.100.0. These tools do not submit merchant payments or complete provider approvals.

• Add manage_vaults, manage_vault_wallets, manage_vault_cards, and manage_vault_items under one configurable vaults toolset, with existing authentication and project-scope enforcement.
• Expose the four vault tools only when the current credential's organization entitlement explicitly grants access. Recheck on every request, including tool calls, with no cached grants, no retries, and a five-second lookup timeout. Missing, malformed, or unavailable entitlements disable only the vault tools; environment allowlists cannot grant access.
• Support both provider specifications, full card-spec replacement, live payment-method expansion, fresh advertised-operation checks, bounded observation, event cursors, and idempotent deletion on HTTP 404.
• Add creation-only browser vault references by ID/name, with a 20-reference cap and duplicate validation. Disable automatic retries for vault requests and vault-bound browser creation; propagate request cancellation.
• Project public response fields, retain non-secret checkout aliases, filter credential-bearing URLs and opaque provider data, and return only curated messages for recognized API error codes, with a generic fallback for unknown errors. Test the existing analytics payload filter against payment data.
• Return scoped observation hints and advertised-operation invocation hints in item responses. Invocation hints require explicit user approval and stay separate from provider-hosted actions. Event hints preserve the continuation cursor.
• Document both provider flows, live-only cards (no test-mode creation), user approval boundaries, response shapes, and toolset configuration in docs/vault-payments.md.

Deployment dependency

API dependency kernel/kernel#3802 is merged and deployed to dev and production. It adds features.vaults.enabled to GET /org/entitlements; older APIs without this field safely hide the vault tools. The MCP changes are deployed to the PR preview, not MCP production.

Validation

• bun test: 447 passed, 0 failed. Includes MCP discovery/call tests with the real SDK and synthetic HTTP responses, plus input validation, project isolation, no-retry failures, safe output, and browser attachment tests.
• Regression coverage verifies inline tools/list schemas without $refs and rejects wait outside get/events before making an API request.
• Synthetic HTTP regressions cover free-text secrets outside URLs, secret-bearing/unknown error codes, all recognized code mappings, and the live-only tool description.
• Real SDK and HTTP-route regressions cover allowed/denied credentials, revocation, unavailable or malformed entitlements, project headers, cancellation, and toolset configuration.
• Hint regressions cover all item-response call sites, resolved project selectors, missing/malformed operation metadata, approval boundaries, and resumable event cursors.
• 15 read-only checks passed against the preview at eb31dde, including executing observation hints unchanged and continuing events from the returned cursor. No payment operations were invoked; the existing item inspected advertised no invocations.
• bunx tsc --noEmit: passed.
• Prettier check for all changed supported files: passed.
• git diff main...HEAD --check: passed. Reviewed the complete diff and removed redundant validation.
• All seven documentation JSON examples parse.
• bun run format:check: blocked only by the unchanged AGENTS.md formatting warning.
• bun run build: compilation and TypeScript stages passed; page-data collection stopped because KERNEL_CLI_PROD_CLIENT_ID is not configured locally.

No live payment credentials were created, no merchant payments were submitted, and no end-to-end provider payment flow was run.

---

Note

High Risk
Introduces live payment-credential MCP APIs and browser vault binding; mistakes in projection, entitlement routing, or agent guidance could expose payment data or enable unsafe spend flows despite safeguards.

Overview
Adds payment-vault MCP tools (prepare/observe credentials only—no merchant checkout submission) on @onkernel/sdk v0.100.0, documented in docs/vault-payments.md and README.

Four tools (manage_vaults, manage_vault_wallets, manage_vault_cards, manage_vault_items) register under a vaults toolset with Link/AgentCard specs, bounded wait on get/events, API-advertised invoke, and creation-only vaults on manage_browsers (max 20, no retries when bound).

Discovery is entitlement-gated: each authenticated request calls resolveMcpVaultAccess against GET /org/entitlements (features.vaults.enabled must be literally true); failures hide only vault tools. Toolset env allowlists cannot grant access.

Responses use a field-projected public shape, safe URL filtering, curated API error codes, next-step hints with requires_user_approval, and analytics tests that strip vault specs/aliases/action URLs from telemetry.

^{Reviewed by Cursor Bugbot for commit eb31dde. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Sep 5, 2026 8:10pm UTC
mcp (staging)	Ready	Preview	Sep 5, 2026 8:10pm UTC

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​onkernel/​sdk@​0.98.0 ⏵ 0.100.0			+1	+1

View full report

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0be41fc. Configure here.}

[rgarcia]

looks good. the four focused tools make the input contracts clearer, and the shared schemas/projection keep the implementation cohesive. the fresh advertised-operation check, explicit event cursor, and published SDK integration all fit well.

approving the approach. please tighten error redaction and make the live-only behavior explicit before merge; left those comments inline, plus an optional suggestion for invocation hints.

validation: 383 tests passed locally; typecheck passed. no live payment flow was run.