Vault and upstream accounts

Configure upstream accounts

Under MCP backends → Upstream authentication → Vault, choose a shared service account or one account per user. Shared mode uses a fixed administrator-provided Vault path. Personal mode uses server-assigned paths and requires the user portal and client grants.

Administrators configure Vault AppRole, path policies, discovery credentials, upstream OAuth callbacks and backups. Users only connect their own accounts in the portal. See Vault configuration and operations and the user's personal account steps. Personal Vault accounts currently cover remote MCP endpoints, not HTTP tool groups.

This is an administrator configuration and operations guide. For employee access, use the user manual.

Fresh deployments support HashiCorp Vault KV v2, SQLite and one MCPHub instance with PostgreSQL. Managed storage uses schema 10. Back up the database, matching encryption key and Vault data together.

User workflow

Connection, reconnection and disconnect steps are in the user manual: personal accounts.

Administrator configuration

Configure Vault on the server, then open MCP Backends → Upstream authentication → Vault. Choose a shared service account or each user's own account. The editor offers a Vault connection check, connection method and callback URL; field/header mapping stays under Advanced.

Shared mode reads an administrator-selected path. Personal paths are generated by the server and cannot be chosen by users or Agents. Personal mode requires the authorization portal and require_client_grant; the editor enables the latter automatically. Global Vault settings require a restart. Endpoint changes use existing configuration governance and runtime reload.

Merge this fragment into an existing remote-management configuration, retaining server, auth and admin. Upstream authorization is separate from signing in to MCPHub.

vault.* and credentials.* are literal fields and do not expand ${...}; *_env contains a variable name. Personal mode must set require_client_grant: true on the backend itself, even with global enforcement enabled. YAML backends are imported only during initial database bootstrap; edit existing deployments through UI/API.

vault:
  address: https://vault.example.com
  mount: secret
  prefix: mcphub
  role_id_env: MCPHUB_VAULT_ROLE_ID
  secret_id_env: MCPHUB_VAULT_SECRET_ID
  # auth_mount: approle
  # namespace: team-a
  # ca_file: /etc/mcphub/vault-ca.pem

client_authorization:
  enabled: true
  client_id: mcphub-portal

backends:
  - id: projects
    url: https://projects.example.com/mcp
    require_client_grant: true
    required_scopes: [projects:access]
    published_tools: [get_project, update_project]
    tool_rules:
      - match: get_project
        effect: read
      - match: update_project
        effect: write
    credentials:
      mode: personal
      discovery_path: discovery/projects
      oauth:
        issuer: https://accounts.example.com
        client_id: mcphub-projects
        scopes: [projects.read, projects.write]
        # client_secret_path: oauth/projects

Register https://hub.example.com/client-auth/api/accounts/callback upstream: the origin of server.public_url plus this path. The provider must support OIDC discovery, PKCE S256, ID tokens and access tokens accepted by the endpoint. Public clients use none; confidential clients support client_secret_basic or client_secret_post, reading the client_secret field from the configured Vault path.

Authorization and token requests include the full endpoint URL as resource. MCPHub validates discovery issuer, browser session/state, authorization-response issuer, ID-token signature/audience/nonce, then verifies credentials through an MCP handshake without invoking tools. Only a successful connection replaces the previous one. Login attempts expire after five minutes; denial or validation failure preserves the existing account. Network authorization endpoints require HTTPS.

Configured upstream scopes are requested with openid, plus offline_access when advertised. Narrowed scopes or an invalid refresh grant require reconnecting. Tokens without refresh capability are accepted, with a reconnect-after-expiry notice.

For a PAT/API key, omit credentials.oauth. Users supply their own token and optional account label/expiry. The default is Authorization: Bearer <token>; an API key can use header: X-API-Key and scheme: "". PAT labels and expiry are user-supplied, not OIDC-verified identity claims.

A shared credential uses:

credentials:
  mode: shared
  path: services/projects
  field: token
  header: Authorization
  scheme: Bearer

Write a token field at secret/services/projects using Vault's administration tools. The configured path is relative to the KV v2 mount, without secret/ or data/. Shared credentials are rotated by Vault operations or the upstream system; MCPHub does not run third-party OAuth refresh for shared KV values.

discovery_path is a shared credential limited to initialization and catalog discovery. Omit it for an anonymous catalog. Published tools must be visible through discovery. Personal catalogs may narrow the tool list or vary descriptions, while tool schemas and policies must match the client grant. Personal calls never fall back to discovery credentials; discovery prompts, resources and notifications are excluded from personal views.

Paths and credential fields

Vault access and operations

Prefer AppRole. Development can instead set token_env: MCPHUB_VAULT_TOKEN. Never put tokens or SecretIDs in YAML. MCPHub logs in again before its AppRole token expires; provision and rotate SecretIDs with suitable lifetimes/use counts. Environment changes require a restart. The connection check uses lookup-self; it does not verify permissions on every application path.

Example policy for mount secret and prefix mcphub:

path "secret/data/mcphub/accounts/*" {
  capabilities = ["create", "update", "read"]
}
path "secret/metadata/mcphub/accounts/*" {
  capabilities = ["delete"]
}
path "secret/data/discovery/projects" {
  capabilities = ["read"]
}
path "secret/data/oauth/projects" {
  capabilities = ["read"]
}
path "auth/token/lookup-self" {
  capabilities = ["read"]
}

Add exact shared-secret read paths as needed. Do not deploy with a root token. Vault requires HTTPS, with optional custom CA; development HTTP requires allow_insecure_http and a numeric loopback address. Vault, OAuth and authenticated upstream clients do not follow redirects.

Personal tokens live in KV v2. The database encrypts ownership, endpoint UID, policy hash, revision and account metadata. A process mutex and Vault CAS serialize refresh across clients. Calls receive credentials only after rotation has been persisted. A failed write retains the rotated token in memory for retry. If the process crashes in that interval, reconnecting may be necessary: OAuth issuance and Vault persistence are not one atomic transaction.

Disconnect revokes local access before deleting all Vault versions of the secret. A durable cleanup queue retries during outages and reclaims orphaned credentials from interrupted connections. Coordinate database and Vault backups/restores; restoring an old database can restore old grant state and requires an authorization review.

Security boundaries

• Hub identity, ClientGrant, user/group policy, scopes, business-resource restrictions, tool publication/state and write approvals all remain enforced. Upstream authorization further restricts execution. Hub and upstream scopes are distinct namespaces.
• Brokers/Agents receive Hub authorization only. Upstream tokens stay on the server and are sent only to Vault, the OAuth service and the selected endpoint. There is no token-export API. Diagnostics record credential binding ID and account label, never tokens.
• MCP sessions, issued resource links and subscriptions are isolated by user/grant. Network failures do not replay operations. Cancellation cannot undo a write already committed upstream.
• Deleting KV data is not provider-side revocation. This release does not call provider-specific revoke APIs; revoke there separately when necessary. Vault operators, the Hub process and configuration administrators remain trusted. Retain least privilege, independent security review and network isolation.
• The first version covers remote MCP endpoints. HTTP tool groups, dynamic database/cloud credentials, Vault Agentic IAM/OBO and multi-instance refresh coordination are not included. Personal browser authorization requires OIDC; provider-specific SaaS OAuth adapters are not included.
• The endpoint must accept and enforce personal credentials. A fixed shared database account inside an endpoint does not become a personal database identity merely by adding Vault to MCPHub.

References: Vault KV v2 API, AppRole.