Vault and Credentials

Two ways to supply a credential

A deployment entry that needs auth can get it two ways:

1. A one-off credential, written directly to that deployment entry and used only there.
2. A vault entry, created once and linked to as many deployments as you want. Linking clears any one-off value already on that entry, and requires the vault entry's mcp_namespace to match the bundle entry's listing namespace.

Reach for a vault entry the moment you're deploying the same MCP with the same credential more than once - it's the difference between updating one secret when it rotates versus hunting down every deployment that has a copy of it.

Personal vs. organisation vault

There are two vault scopes, backed by separate tables:

• Personal (UserVaultEntry) - owned by one user, managed under /vault/entries. This is the only scope deployment credential links currently accept.
• Organisation (OrganisationVaultEntry) - shared across an org's members, managed under /organisations/{org_id}/vault/entries. Any member can read an org's vault entries; only admins and owners can create, edit, or delete them.

What's stored, and how

A vault entry holds an mcp_namespace, provider_name, auth_type, a display name, and the credential itself - encrypted server-side with AES-256-GCM before it's written. The API never returns the decrypted value; you get metadata plus a usage_count showing how many deployments currently reference it.

Supported auth_type values differ slightly by path: vault entries support bearer, api_key, basic, oauth2_cc, oauth2_pkce, and azure_keyvault; one-off deployment credentials support the same set except azure_keyvault, and add custom_headers instead.

OAuth2 is a separate flow

MCPs that authenticate via OAuth2 rather than a static credential don't use the credential-write endpoints at all - they use a three-step interactive PKCE exchange (POST /oauth2/initiate, the provider's callback, then a session status check). See OAuth2/initiate_oauth in the API reference for the exact sequence.

Where to go next

• Bundles and Deployments for where credentials fit into the deployment lifecycle.
• Full endpoint list: Vault and OAuth2 in the API reference.