feat(mcpd): Llm resource — CRUD + CLI + apply

Why: every client that wants an LLM (the agent, HTTP-mode mcplocal, Claude
Code's STDIO mcplocal) today has to know the provider URL + key, and each
user's ~/.mcpctl/config.json carries them. Centralising the catalogue on the
server is the prerequisite for Phase 2 (mcpd proxies inference so credentials
never leave the cluster).

This phase adds the `Llm` resource and its CRUD surface — no proxy yet, no
client pivot yet. Just enough to register what you have.

Schema:
- New `Llm` model: name/type/model/url/tier/description + {apiKeySecretId,
  apiKeySecretKey} FK pair. Reverse `llms` relation on Secret.
- Provider types: anthropic | openai | deepseek | vllm | ollama | gemini-cli.
- Tiers: fast | heavy.

mcpd:
- LlmRepository + LlmService + Zod validation schema + /api/v1/llms routes.
- API surface exposes `apiKeyRef: {name, key}` — the service translates to/
  from the FK pair so clients never deal in cuids.
- `resolveApiKey(llmName)` reads through SecretService (which itself dispatches
  to the right SecretBackend). That's the hook Phase 2's inference proxy uses.
- RBAC: added `'llms'` to RBAC_RESOURCES + resource alias. Standard
  view/create/edit/delete semantics.
- Wired into main.ts (repo, service, routes).

CLI:
- `mcpctl create llm <name> --type X --model Y --tier fast|heavy --api-key-ref SECRET/KEY [--url ...] [--extra k=v ...]`
- `mcpctl get|describe|delete llm` — standard resource verbs.
- `mcpctl apply -f` with `kind: llm` (single- or multi-doc yaml/json).
  Applied after secrets, before servers — apiKeyRef resolves an existing Secret.
- Shell completions regenerated.

Tests: 11 service unit tests + 9 route tests (happy path, 404s, 409, validation).
Full suite 1812/1812 (+20 from the 1792 Phase 0 baseline). TypeScript clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

completions/mcpctl.bash

@@ -5,11 +5,11 @@ _mcpctl() {
   local cur prev words cword
   _init_completion || return
 
-  local commands="status login logout config get describe delete logs create edit apply patch backup approve console cache test"
+  local commands="status login logout config get describe delete logs create edit apply patch backup approve console cache test migrate"
   local project_commands="get describe delete logs create edit attach-server detach-server"
   local global_opts="-v --version --daemon-url --direct -p --project -h --help"
-  local resources="servers instances secrets templates projects users groups rbac prompts promptrequests serverattachments proxymodels all"
+  local resources="servers instances secrets secretbackends llms templates projects users groups rbac prompts promptrequests serverattachments proxymodels all"
-  local resource_aliases="servers instances secrets templates projects users groups rbac prompts promptrequests serverattachments proxymodels all server srv instance inst secret sec template tpl project proj user group rbac-definition rbac-binding prompt promptrequest pr serverattachment sa proxymodel pm"
+  local resource_aliases="servers instances secrets secretbackends llms templates projects users groups rbac prompts promptrequests serverattachments proxymodels all server srv instance inst secret sec secretbackend sb llm template tpl project proj user group rbac-definition rbac-binding prompt promptrequest pr serverattachment sa proxymodel pm"
 
   # Check if --project/-p was given
   local has_project=false
@@ -175,7 +175,7 @@ _mcpctl() {
     create)
       local create_sub=$(_mcpctl_get_subcmd $subcmd_pos)
       if [[ -z "$create_sub" ]]; then
-        COMPREPLY=($(compgen -W "server secret project user group rbac mcptoken prompt serverattachment promptrequest help" -- "$cur"))
+        COMPREPLY=($(compgen -W "server secret llm secretbackend project user group rbac mcptoken prompt serverattachment promptrequest help" -- "$cur"))
       else
         case "$create_sub" in
           server)
@@ -184,6 +184,12 @@ _mcpctl() {
           secret)
             COMPREPLY=($(compgen -W "--data --force -h --help" -- "$cur"))
             ;;
+          llm)
+            COMPREPLY=($(compgen -W "--type --model --url --tier --description --api-key-ref --extra --force -h --help" -- "$cur"))
+            ;;
+          secretbackend)
+            COMPREPLY=($(compgen -W "--type --description --default --url --namespace --mount --path-prefix --token-secret --config --force -h --help" -- "$cur"))
+            ;;
           project)
             COMPREPLY=($(compgen -W "-d --description --proxy-model --prompt --gated --no-gated --server --force -h --help" -- "$cur"))
             ;;
@@ -329,6 +335,21 @@ _mcpctl() {
         esac
       fi
       return ;;
+    migrate)
+      local migrate_sub=$(_mcpctl_get_subcmd $subcmd_pos)
+      if [[ -z "$migrate_sub" ]]; then
+        COMPREPLY=($(compgen -W "secrets help" -- "$cur"))
+      else
+        case "$migrate_sub" in
+          secrets)
+            COMPREPLY=($(compgen -W "--from --to --names --keep-source --dry-run -h --help" -- "$cur"))
+            ;;
+          *)
+            COMPREPLY=($(compgen -W "-h --help" -- "$cur"))
+            ;;
+        esac
+      fi
+      return ;;
     help)
       COMPREPLY=($(compgen -W "$commands" -- "$cur"))
       return ;;

completions/mcpctl.fish

@@ -4,7 +4,7 @@
 # Erase any stale completions from previous versions
 complete -c mcpctl -e
 
-set -l commands status login logout config get describe delete logs create edit apply patch backup approve console cache test
+set -l commands status login logout config get describe delete logs create edit apply patch backup approve console cache test migrate
 set -l project_commands get describe delete logs create edit attach-server detach-server
 
 # Disable file completions by default
@@ -31,10 +31,10 @@ function __mcpctl_has_project
 end
 
 # Resource type detection
-set -l resources servers instances secrets templates projects users groups rbac prompts promptrequests serverattachments proxymodels all
+set -l resources servers instances secrets secretbackends llms templates projects users groups rbac prompts promptrequests serverattachments proxymodels all
 
 function __mcpctl_needs_resource_type
-    set -l resource_aliases servers instances secrets templates projects users groups rbac prompts promptrequests serverattachments proxymodels all server srv instance inst secret sec template tpl project proj user group rbac-definition rbac-binding prompt promptrequest pr serverattachment sa proxymodel pm
+    set -l resource_aliases servers instances secrets secretbackends llms templates projects users groups rbac prompts promptrequests serverattachments proxymodels all server srv instance inst secret sec secretbackend sb llm template tpl project proj user group rbac-definition rbac-binding prompt promptrequest pr serverattachment sa proxymodel pm
     set -l tokens (commandline -opc)
     set -l found_cmd false
     for tok in $tokens
@@ -59,6 +59,8 @@ function __mcpctl_resolve_resource
         case server srv servers;      echo servers
         case instance inst instances; echo instances
         case secret sec secrets;      echo secrets
+        case secretbackend sb secretbackends; echo secretbackends
+        case llm llms;                echo llms
         case template tpl templates;  echo templates
         case project proj projects;   echo projects
         case user users;              echo users
@@ -74,7 +76,7 @@ function __mcpctl_resolve_resource
 end
 
 function __mcpctl_get_resource_type
-    set -l resource_aliases servers instances secrets templates projects users groups rbac prompts promptrequests serverattachments proxymodels all server srv instance inst secret sec template tpl project proj user group rbac-definition rbac-binding prompt promptrequest pr serverattachment sa proxymodel pm
+    set -l resource_aliases servers instances secrets secretbackends llms templates projects users groups rbac prompts promptrequests serverattachments proxymodels all server srv instance inst secret sec secretbackend sb llm template tpl project proj user group rbac-definition rbac-binding prompt promptrequest pr serverattachment sa proxymodel pm
     set -l tokens (commandline -opc)
     set -l found_cmd false
     for tok in $tokens
@@ -223,7 +225,7 @@ complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a describe -d 'Show detailed information about a resource'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a delete -d 'Delete a resource (server, instance, secret, project, user, group, rbac)'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a logs -d 'Get logs from an MCP server instance'
-complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a create -d 'Create a resource (server, secret, project, user, group, rbac, serverattachment, prompt)'
+complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a create -d 'Create a resource (server, secret, secretbackend, llm, project, user, group, rbac, serverattachment, prompt)'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a edit -d 'Edit a resource in your default editor (server, project)'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a apply -d 'Apply declarative configuration from a YAML or JSON file'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a patch -d 'Patch a resource field (e.g. mcpctl patch project myproj llmProvider=none)'
@@ -232,13 +234,14 @@ complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a console -d 'Interactive MCP console — unified timeline with tools, provenance, and lab replay'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a cache -d 'Manage ProxyModel pipeline cache'
 complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a test -d 'Utilities for testing MCP endpoints and config'
+complete -c mcpctl -n "not __mcpctl_has_project; and not __fish_seen_subcommand_from $commands" -a migrate -d 'Move resources between backends (currently: secrets between SecretBackends)'
 
 # Project-scoped commands (with --project)
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a get -d 'List resources (servers, projects, instances, all)'
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a describe -d 'Show detailed information about a resource'
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a delete -d 'Delete a resource (server, instance, secret, project, user, group, rbac)'
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a logs -d 'Get logs from an MCP server instance'
-complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a create -d 'Create a resource (server, secret, project, user, group, rbac, serverattachment, prompt)'
+complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a create -d 'Create a resource (server, secret, secretbackend, llm, project, user, group, rbac, serverattachment, prompt)'
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a edit -d 'Edit a resource in your default editor (server, project)'
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a attach-server -d 'Attach a server to a project (requires --project)'
 complete -c mcpctl -n "__mcpctl_has_project; and not __fish_seen_subcommand_from $project_commands" -a detach-server -d 'Detach a server from a project (requires --project)'
@@ -281,9 +284,11 @@ complete -c mcpctl -n "__mcpctl_subcmd_active config claude-generate" -l stdout
 complete -c mcpctl -n "__mcpctl_subcmd_active config impersonate" -l quit -d 'Stop impersonating and return to original identity'
 
 # create subcommands
-set -l create_cmds server secret project user group rbac mcptoken prompt serverattachment promptrequest
+set -l create_cmds server secret llm secretbackend project user group rbac mcptoken prompt serverattachment promptrequest
 complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a server -d 'Create an MCP server definition'
 complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a secret -d 'Create a secret'
+complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a llm -d 'Register a server-managed LLM (anthropic, openai, vllm, ollama, deepseek, gemini-cli)'
+complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a secretbackend -d 'Create a secret backend (plaintext, openbao)'
 complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a project -d 'Create a project'
 complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a user -d 'Create a user'
 complete -c mcpctl -n "__fish_seen_subcommand_from create; and not __fish_seen_subcommand_from $create_cmds" -a group -d 'Create a group'
@@ -313,6 +318,28 @@ complete -c mcpctl -n "__mcpctl_subcmd_active create server" -l force -d 'Update
 complete -c mcpctl -n "__mcpctl_subcmd_active create secret" -l data -d 'Secret data KEY=value (repeat for multiple)' -x
 complete -c mcpctl -n "__mcpctl_subcmd_active create secret" -l force -d 'Update if already exists'
 
+# create llm options
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l type -d 'Provider type (anthropic, openai, deepseek, vllm, ollama, gemini-cli)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l model -d 'Model identifier (e.g. claude-3-5-sonnet-20241022)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l url -d 'Endpoint URL (empty = provider default)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l tier -d 'Tier: fast or heavy' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l description -d 'Description' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l api-key-ref -d 'API key reference in SECRET/KEY form (e.g. anthropic-key/token)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l extra -d 'Extra config key=value (repeat)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create llm" -l force -d 'Update if already exists'
+
+# create secretbackend options
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l type -d 'Backend type (plaintext, openbao)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l description -d 'Description' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l default -d 'Promote this backend to default (atomically demotes the current one)'
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l url -d 'openbao: vault URL (e.g. http://bao.example:8200)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l namespace -d 'openbao: X-Vault-Namespace header value' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l mount -d 'openbao: KV v2 mount point (default: secret)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l path-prefix -d 'openbao: path prefix under mount (default: mcpctl)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l token-secret -d 'openbao: token secret reference in SECRET/KEY form (e.g. bao-creds/token)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l config -d 'Extra config as key=value (repeat for multiple)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active create secretbackend" -l force -d 'Update if already exists'
+
 # create project options
 complete -c mcpctl -n "__mcpctl_subcmd_active create project" -s d -l description -d 'Project description' -x
 complete -c mcpctl -n "__mcpctl_subcmd_active create project" -l proxy-model -d 'Plugin name (default, content-pipeline, gate, none)' -x
@@ -391,6 +418,17 @@ complete -c mcpctl -n "__mcpctl_subcmd_active test mcp" -l timeout -d 'Per-reque
 complete -c mcpctl -n "__mcpctl_subcmd_active test mcp" -s o -l output -d 'Output format: text or json' -x
 complete -c mcpctl -n "__mcpctl_subcmd_active test mcp" -l no-health -d 'Skip the /healthz preflight check'
 
+# migrate subcommands
+set -l migrate_cmds secrets
+complete -c mcpctl -n "__fish_seen_subcommand_from migrate; and not __fish_seen_subcommand_from $migrate_cmds" -a secrets -d 'Migrate secrets from one SecretBackend to another'
+
+# migrate secrets options
+complete -c mcpctl -n "__mcpctl_subcmd_active migrate secrets" -l from -d 'Source SecretBackend name' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active migrate secrets" -l to -d 'Destination SecretBackend name' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active migrate secrets" -l names -d 'Comma-separated secret names (default: all)' -x
+complete -c mcpctl -n "__mcpctl_subcmd_active migrate secrets" -l keep-source -d 'Leave the source copy intact (default: delete from source after write+commit)'
+complete -c mcpctl -n "__mcpctl_subcmd_active migrate secrets" -l dry-run -d 'Show which secrets would be migrated without touching them'
+
 # status options
 complete -c mcpctl -n "__fish_seen_subcommand_from status" -s o -l output -d 'output format (table, json, yaml)' -x
 

docs/secret-backends.md

@@ -0,0 +1,167 @@
+# Secret backends
+
+`mcpctl` stores the raw data for `Secret` resources in a pluggable **backend**.
+The default is `plaintext` — the secret payload lives in Postgres as plain JSON
+— which is fine for laptop development but a poor fit for shared clusters. For
+production, point at an external KV store and delete secrets from the DB after
+migration.
+
+This guide covers the model, the shipped drivers, and how to migrate without
+downtime.
+
+## Model
+
+- A `SecretBackend` resource is a single named driver instance (e.g. a pointer
+  at one OpenBao deployment).
+- Every `Secret` row carries a `backendId` FK — the backend that owns its data.
+- Exactly one `SecretBackend` has `isDefault: true`. New secrets created through
+  the API/CLI land on that backend.
+- The `plaintext` backend is seeded at startup and named `default`. It cannot
+  be deleted — there needs to always be one row where the driver's own
+  credentials can bootstrap from (see below).
+
+## CLI
+
+```bash
+mcpctl get secretbackends              # list backends
+mcpctl describe secretbackend <name>   # inspect config (credentials masked)
+mcpctl create secretbackend <name> --type plaintext [--default] [--description ...]
+mcpctl create secretbackend <name> --type openbao \
+  --url http://bao.example:8200 \
+  --token-secret bao-creds/token \
+  [--namespace <ns>] [--mount secret] [--path-prefix mcpctl] \
+  [--default]
+mcpctl delete secretbackend <name>     # blocked if any secret still points at it
+
+mcpctl migrate secrets --from default --to bao
+mcpctl migrate secrets --from default --to bao --names a,b --keep-source
+mcpctl migrate secrets --from default --to bao --dry-run
+```
+
+Anything you can do with `create secretbackend` also works via `apply -f`:
+
+```yaml
+kind: secretbackend
+name: bao
+type: openbao
+description: "shared cluster OpenBao"
+isDefault: true
+config:
+  url: http://bao.svc.cluster.local:8200
+  tokenSecretRef: { name: bao-creds, key: token }
+  namespace: platform
+```
+
+## Drivers
+
+### plaintext
+
+Trivial. `Secret.data` holds the JSON, `externalRef` is empty.
+
+- Storage: Postgres column.
+- Bootstrap: seeded as `default` at startup.
+- Cost: zero setup, zero encryption at rest, full access for any DB reader.
+
+Use for development, CI, or single-tenant self-hosts where the DB itself is
+treated as sensitive.
+
+### openbao
+
+Talks HTTP to an [OpenBao](https://openbao.org) (MPL 2.0 Vault fork) KV v2
+mount. Also compatible with HashiCorp Vault KV v2 — the wire protocol is the
+same.
+
+| Config key       | Required? | Description |
+|------------------|-----------|-------------|
+| `url`            | yes       | Base URL, e.g. `http://bao.svc.cluster.local:8200`. |
+| `tokenSecretRef` | yes       | `{ name, key }` pointing at a `Secret` on the **plaintext** backend that holds the bootstrap token. |
+| `mount`          | no        | KV v2 mount name. Default `secret`. |
+| `pathPrefix`     | no        | Path prefix under the mount. Default `mcpctl`. Secrets land at `<mount>/<pathPrefix>/<secretName>`. |
+| `namespace`      | no        | `X-Vault-Namespace` header for OpenBao/Vault Enterprise namespaces. |
+
+The driver only stores a reference in `Secret.externalRef` (`mount/path`). The
+`Secret.data` column is left empty for openbao-backed rows — you can safely
+drop DB-level access to secrets after migration.
+
+#### Required OpenBao policy
+
+Minimum token policy for a backend that lives at `secret/mcpctl/`:
+
+```hcl
+path "secret/data/mcpctl/*" {
+  capabilities = ["create", "read", "update"]
+}
+
+path "secret/metadata/mcpctl/*" {
+  capabilities = ["list", "delete"]
+}
+
+path "secret/metadata/mcpctl/" {
+  capabilities = ["list"]
+}
+```
+
+Grant `delete` on `metadata/...` only if you need mcpctl to fully remove
+secrets — OpenBao soft-deletes until the metadata is gone.
+
+#### Chicken-and-egg: where does the OpenBao token live?
+
+mcpd reads the OpenBao token from a `Secret` on the **plaintext** backend.
+That's the whole point of keeping plaintext around — it's the trust root:
+
+1. Operator creates a plaintext `Secret` holding the bootstrap token.
+2. Operator creates the `openbao` backend, pointing at that secret via
+   `tokenSecretRef`.
+3. Operator runs `mcpctl migrate secrets --from default --to bao` to move all
+   other secrets off plaintext.
+4. After migration, the only sensitive row left on plaintext is the OpenBao
+   token itself. DB access is now equivalent to OpenBao token access (a single
+   key), not equivalent to all API keys in the system.
+
+Follow-up work (not shipped yet) replaces static token auth with Kubernetes
+ServiceAccount auth so no bootstrap token is needed at all.
+
+## Migration — `mcpctl migrate secrets`
+
+Atomicity is **per secret**, not per batch. Remote writes can't roll back, so we
+don't pretend. For each secret the service:
+
+1. Reads the plaintext from the source driver.
+2. Writes it to the destination driver.
+3. Updates the `Secret` row: flips `backendId`, sets new `externalRef`, clears
+   `data`.
+4. Deletes from source (skipped with `--keep-source`).
+
+If the command is interrupted between step 2 and 3, the destination has an
+orphan entry but the source still owns the row. Re-running is idempotent — the
+service skips secrets that are already on the destination and picks up the
+rest.
+
+```bash
+# Dry-run first: see what would move.
+mcpctl migrate secrets --from default --to bao --dry-run
+
+# Migrate everything.
+mcpctl migrate secrets --from default --to bao
+
+# Migrate a subset only.
+mcpctl migrate secrets --from default --to bao --names api-keys,oauth-client
+
+# Leave the source copy in place (useful for A/B validation).
+mcpctl migrate secrets --from default --to bao --keep-source
+```
+
+The command prints a per-secret summary (migrated / skipped / failed) and exits
+non-zero if any secret failed. Ctrl-C during the run is safe — restart when you
+want, no duplicate writes.
+
+## RBAC
+
+- `resource: secretbackends` — gated like any other resource (`view`,
+  `create`, `edit`, `delete`).
+- `role: run, action: migrate-secrets` — required to call
+  `POST /api/v1/secrets/migrate`.
+
+Describe output masks config values whose keys look like credentials
+(`token`, `secret`, `password`, `key`), so `mcpctl describe secretbackend` is
+safe to paste into tickets.

scripts/generate-completions.ts

@@ -184,7 +184,7 @@ async function extractTree(): Promise<CmdInfo> {
 // ============================================================
 
 const CANONICAL_RESOURCES = [
-  'servers', 'instances', 'secrets', 'templates', 'projects',
+  'servers', 'instances', 'secrets', 'secretbackends', 'llms', 'templates', 'projects',
   'users', 'groups', 'rbac', 'prompts', 'promptrequests',
   'serverattachments', 'proxymodels', 'all',
 ];
@@ -193,6 +193,8 @@ const ALIAS_ENTRIES: [string, string][] = [
   ['server', 'servers'], ['srv', 'servers'],
   ['instance', 'instances'], ['inst', 'instances'],
   ['secret', 'secrets'], ['sec', 'secrets'],
+  ['secretbackend', 'secretbackends'], ['sb', 'secretbackends'],
+  ['llm', 'llms'], ['llms', 'llms'],
   ['template', 'templates'], ['tpl', 'templates'],
   ['project', 'projects'], ['proj', 'projects'],
   ['user', 'users'],

src/cli/src/commands/apply.ts

@@ -41,6 +41,28 @@ const SecretSpecSchema = z.object({
   data: z.record(z.string()).default({}),
 });
 
+const SecretBackendSpecSchema = z.object({
+  name: z.string().min(1),
+  type: z.string().min(1),
+  description: z.string().default(''),
+  isDefault: z.boolean().optional(),
+  config: z.record(z.unknown()).default({}),
+});
+
+const LlmSpecSchema = z.object({
+  name: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/),
+  type: z.enum(['anthropic', 'openai', 'deepseek', 'vllm', 'ollama', 'gemini-cli']),
+  model: z.string().min(1),
+  url: z.string().url().optional(),
+  tier: z.enum(['fast', 'heavy']).default('fast'),
+  description: z.string().max(500).default(''),
+  apiKeyRef: z.object({
+    name: z.string().min(1),
+    key: z.string().min(1),
+  }).nullable().optional(),
+  extraConfig: z.record(z.unknown()).default({}),
+});
+
 const TemplateEnvEntrySchema = z.object({
   name: z.string().min(1),
   description: z.string().optional(),
@@ -142,7 +164,9 @@ const McpTokenSpecSchema = z.object({
 });
 
 const ApplyConfigSchema = z.object({
+  secretbackends: z.array(SecretBackendSpecSchema).default([]),
   secrets: z.array(SecretSpecSchema).default([]),
+  llms: z.array(LlmSpecSchema).default([]),
   servers: z.array(ServerSpecSchema).default([]),
   users: z.array(UserSpecSchema).default([]),
   groups: z.array(GroupSpecSchema).default([]),
@@ -183,7 +207,9 @@ export function createApplyCommand(deps: ApplyCommandDeps): Command {
 
       if (opts.dryRun) {
         log('Dry run - would apply:');
+        if (config.secretbackends.length > 0) log(`  ${config.secretbackends.length} secretbackend(s)`);
         if (config.secrets.length > 0) log(`  ${config.secrets.length} secret(s)`);
+        if (config.llms.length > 0) log(`  ${config.llms.length} llm(s)`);
         if (config.servers.length > 0) log(`  ${config.servers.length} server(s)`);
         if (config.users.length > 0) log(`  ${config.users.length} user(s)`);
         if (config.groups.length > 0) log(`  ${config.groups.length} group(s)`);
@@ -229,6 +255,8 @@ const KIND_TO_RESOURCE: Record<string, string> = {
   promptrequest: 'promptrequests',
   serverattachment: 'serverattachments',
   mcptoken: 'mcptokens',
+  secretbackend: 'secretbackends',
+  llm: 'llms',
 };
 
 /**
@@ -324,6 +352,30 @@ async function applyConfig(client: ApiClient, config: ApplyConfig, log: (...args
     }
   }
 
+  // Apply secret backends first — secrets reference them.
+  // When multiple backends claim isDefault: true, the server's atomic swap will
+  // leave whichever was applied last as the effective default.
+  for (const sb of config.secretbackends) {
+    try {
+      const existing = await cachedFindByName('secretbackends', sb.name);
+      if (existing) {
+        const updateBody: Record<string, unknown> = {
+          config: sb.config,
+          description: sb.description,
+        };
+        if (sb.isDefault !== undefined) updateBody.isDefault = sb.isDefault;
+        await withRetry(() => client.put(`/api/v1/secretbackends/${existing.id}`, updateBody));
+        log(`Updated secretbackend: ${sb.name}`);
+      } else {
+        await withRetry(() => client.post('/api/v1/secretbackends', sb));
+        invalidateCache('secretbackends');
+        log(`Created secretbackend: ${sb.name}`);
+      }
+    } catch (err) {
+      log(`Error applying secretbackend '${sb.name}': ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
   // Apply secrets
   for (const secret of config.secrets) {
     try {
@@ -341,6 +393,25 @@ async function applyConfig(client: ApiClient, config: ApplyConfig, log: (...args
     }
   }
 
+  // Apply LLMs (after secrets — apiKeyRef resolves to an existing Secret)
+  for (const llm of config.llms) {
+    try {
+      const existing = await cachedFindByName('llms', llm.name);
+      if (existing) {
+        // Exclude type on update — type is immutable.
+        const { name: _n, type: _t, ...updateBody } = llm;
+        await withRetry(() => client.put(`/api/v1/llms/${existing.id}`, updateBody));
+        log(`Updated llm: ${llm.name}`);
+      } else {
+        await withRetry(() => client.post('/api/v1/llms', llm));
+        invalidateCache('llms');
+        log(`Created llm: ${llm.name}`);
+      }
+    } catch (err) {
+      log(`Error applying llm '${llm.name}': ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
   // Apply servers
   for (const server of config.servers) {
     try {

src/cli/src/commands/create.ts

@@ -88,7 +88,7 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
   const { client, log } = deps;
 
   const cmd = new Command('create')
-    .description('Create a resource (server, secret, project, user, group, rbac, serverattachment, prompt)');
+    .description('Create a resource (server, secret, secretbackend, llm, project, user, group, rbac, serverattachment, prompt)');
 
   // --- create server ---
   cmd.command('server')
@@ -252,6 +252,125 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
       }
     });
 
+  // --- create llm ---
+  cmd.command('llm')
+    .description('Register a server-managed LLM (anthropic, openai, vllm, ollama, deepseek, gemini-cli)')
+    .argument('<name>', 'LLM name (lowercase alphanumeric with hyphens)')
+    .requiredOption('--type <type>', 'Provider type (anthropic, openai, deepseek, vllm, ollama, gemini-cli)')
+    .requiredOption('--model <model>', 'Model identifier (e.g. claude-3-5-sonnet-20241022)')
+    .option('--url <url>', 'Endpoint URL (empty = provider default)')
+    .option('--tier <tier>', 'Tier: fast or heavy', 'fast')
+    .option('--description <text>', 'Description')
+    .option('--api-key-ref <ref>', 'API key reference in SECRET/KEY form (e.g. anthropic-key/token)')
+    .option('--extra <entry>', 'Extra config key=value (repeat)', collect, [])
+    .option('--force', 'Update if already exists')
+    .action(async (name: string, opts) => {
+      const body: Record<string, unknown> = {
+        name,
+        type: opts.type,
+        model: opts.model,
+        tier: opts.tier,
+      };
+      if (opts.url) body.url = opts.url;
+      if (opts.description !== undefined) body.description = opts.description;
+      if (opts.apiKeyRef) {
+        const slashIdx = (opts.apiKeyRef as string).indexOf('/');
+        if (slashIdx < 1) throw new Error(`Invalid --api-key-ref '${opts.apiKeyRef as string}'. Expected SECRET_NAME/KEY_NAME`);
+        body.apiKeyRef = {
+          name: (opts.apiKeyRef as string).slice(0, slashIdx),
+          key: (opts.apiKeyRef as string).slice(slashIdx + 1),
+        };
+      }
+      if (opts.extra && (opts.extra as string[]).length > 0) {
+        const extra: Record<string, unknown> = {};
+        for (const entry of opts.extra as string[]) {
+          const eqIdx = entry.indexOf('=');
+          if (eqIdx === -1) throw new Error(`Invalid --extra '${entry}'. Expected key=value`);
+          extra[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1);
+        }
+        body.extraConfig = extra;
+      }
+
+      try {
+        const row = await client.post<{ id: string; name: string }>('/api/v1/llms', body);
+        log(`llm '${row.name}' created (id: ${row.id})`);
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 409 && opts.force) {
+          const existing = (await client.get<Array<{ id: string; name: string }>>('/api/v1/llms')).find((l) => l.name === name);
+          if (!existing) throw err;
+          const { name: _n, type: _t, ...updateBody } = body;
+          await client.put(`/api/v1/llms/${existing.id}`, updateBody);
+          log(`llm '${name}' updated (id: ${existing.id})`);
+        } else {
+          throw err;
+        }
+      }
+    });
+
+  // --- create secretbackend ---
+  cmd.command('secretbackend')
+    .alias('sb')
+    .description('Create a secret backend (plaintext, openbao)')
+    .argument('<name>', 'Backend name (lowercase, hyphens allowed)')
+    .requiredOption('--type <type>', 'Backend type (plaintext, openbao)')
+    .option('--description <text>', 'Description')
+    .option('--default', 'Promote this backend to default (atomically demotes the current one)')
+    .option('--url <url>', 'openbao: vault URL (e.g. http://bao.example:8200)')
+    .option('--namespace <ns>', 'openbao: X-Vault-Namespace header value')
+    .option('--mount <mount>', 'openbao: KV v2 mount point (default: secret)')
+    .option('--path-prefix <prefix>', 'openbao: path prefix under mount (default: mcpctl)')
+    .option('--token-secret <ref>', 'openbao: token secret reference in SECRET/KEY form (e.g. bao-creds/token)')
+    .option('--config <entry>', 'Extra config as key=value (repeat for multiple)', collect, [])
+    .option('--force', 'Update if already exists')
+    .action(async (name: string, opts) => {
+      const type = opts.type as string;
+      const config: Record<string, unknown> = {};
+
+      if (type === 'openbao') {
+        if (!opts.url) throw new Error('--url is required for openbao backend');
+        if (!opts.tokenSecret) throw new Error('--token-secret is required for openbao backend (format: SECRET/KEY)');
+        const slashIdx = (opts.tokenSecret as string).indexOf('/');
+        if (slashIdx < 1) throw new Error(`Invalid --token-secret '${opts.tokenSecret as string}'. Expected SECRET_NAME/KEY_NAME`);
+        config.url = opts.url;
+        config.tokenSecretRef = {
+          name: (opts.tokenSecret as string).slice(0, slashIdx),
+          key: (opts.tokenSecret as string).slice(slashIdx + 1),
+        };
+        if (opts.namespace) config.namespace = opts.namespace;
+        if (opts.mount) config.mount = opts.mount;
+        if (opts.pathPrefix) config.pathPrefix = opts.pathPrefix;
+      }
+
+      // Extra config key=value pairs (overwrite/extend above)
+      for (const entry of opts.config as string[]) {
+        const eqIdx = entry.indexOf('=');
+        if (eqIdx === -1) throw new Error(`Invalid --config '${entry}'. Expected key=value`);
+        config[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1);
+      }
+
+      const body: Record<string, unknown> = { name, type, config };
+      if (opts.description !== undefined) body.description = opts.description;
+      if (opts.default) body.isDefault = true;
+
+      try {
+        const row = await client.post<{ id: string; name: string }>('/api/v1/secretbackends', body);
+        log(`secretbackend '${row.name}' created (id: ${row.id})`);
+        if (opts.default) log(`  promoted to default backend`);
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 409 && opts.force) {
+          const existing = (await client.get<Array<{ id: string; name: string }>>('/api/v1/secretbackends')).find((b) => b.name === name);
+          if (!existing) throw err;
+          const updateBody: Record<string, unknown> = { config };
+          if (opts.description !== undefined) updateBody.description = opts.description;
+          if (opts.default) updateBody.isDefault = true;
+          await client.put(`/api/v1/secretbackends/${existing.id}`, updateBody);
+          log(`secretbackend '${name}' updated (id: ${existing.id})`);
+        } else {
+          throw err;
+        }
+      }
+    });
+
   // --- create project ---
   cmd.command('project')
     .description('Create a project')

src/cli/src/commands/describe.ts

@@ -218,6 +218,80 @@ function formatSecretDetail(secret: Record<string, unknown>, showValues: boolean
   return lines.join('\n');
 }
 
+function formatLlmDetail(llm: Record<string, unknown>): string {
+  const lines: string[] = [];
+  lines.push(`=== LLM: ${llm.name} ===`);
+  lines.push(`${pad('Name:')}${llm.name}`);
+  lines.push(`${pad('Type:')}${llm.type}`);
+  lines.push(`${pad('Model:')}${llm.model}`);
+  lines.push(`${pad('Tier:')}${llm.tier ?? 'fast'}`);
+  if (llm.url) lines.push(`${pad('URL:')}${llm.url}`);
+  if (llm.description) lines.push(`${pad('Description:')}${llm.description}`);
+
+  const ref = llm.apiKeyRef as { name: string; key: string } | null | undefined;
+  lines.push('');
+  lines.push('API Key:');
+  if (ref) {
+    lines.push(`  ${pad('Secret:', 12)}${ref.name}`);
+    lines.push(`  ${pad('Key:', 12)}${ref.key}`);
+  } else {
+    lines.push('  (none)');
+  }
+
+  const extra = llm.extraConfig as Record<string, unknown> | undefined;
+  if (extra && Object.keys(extra).length > 0) {
+    lines.push('');
+    lines.push('Extra Config:');
+    const keyW = Math.max(6, ...Object.keys(extra).map((k) => k.length)) + 2;
+    for (const [k, v] of Object.entries(extra)) {
+      let display: string;
+      if (v === null || v === undefined) display = '-';
+      else if (typeof v === 'object') display = JSON.stringify(v);
+      else display = String(v);
+      lines.push(`  ${k.padEnd(keyW)}${display}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Metadata:');
+  lines.push(`  ${pad('ID:', 12)}${llm.id}`);
+  if (llm.createdAt) lines.push(`  ${pad('Created:', 12)}${llm.createdAt}`);
+  if (llm.updatedAt) lines.push(`  ${pad('Updated:', 12)}${llm.updatedAt}`);
+
+  return lines.join('\n');
+}
+
+function formatSecretBackendDetail(backend: Record<string, unknown>): string {
+  const lines: string[] = [];
+  lines.push(`=== SecretBackend: ${backend.name} ===`);
+  lines.push(`${pad('Name:')}${backend.name}`);
+  lines.push(`${pad('Type:')}${backend.type}`);
+  lines.push(`${pad('Default:')}${backend.isDefault ? 'yes' : 'no'}`);
+  if (backend.description) lines.push(`${pad('Description:')}${backend.description}`);
+
+  const config = backend.config as Record<string, unknown> | undefined;
+  if (config && Object.keys(config).length > 0) {
+    lines.push('');
+    lines.push('Config:');
+    const keyW = Math.max(6, ...Object.keys(config).map((k) => k.length)) + 2;
+    for (const [key, value] of Object.entries(config)) {
+      let display: string;
+      if (value === null || value === undefined) display = '-';
+      else if (typeof value === 'object') display = JSON.stringify(value);
+      else display = String(value);
+      lines.push(`  ${key.padEnd(keyW)}${display}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Metadata:');
+  lines.push(`  ${pad('ID:', 12)}${backend.id}`);
+  if (backend.createdAt) lines.push(`  ${pad('Created:', 12)}${backend.createdAt}`);
+  if (backend.updatedAt) lines.push(`  ${pad('Updated:', 12)}${backend.updatedAt}`);
+
+  return lines.join('\n');
+}
+
 function formatTemplateDetail(template: Record<string, unknown>): string {
   const lines: string[] = [];
   lines.push(`=== Template: ${template.name} ===`);
@@ -806,6 +880,12 @@ export function createDescribeCommand(deps: DescribeCommandDeps): Command {
           case 'templates':
             deps.log(formatTemplateDetail(item));
             break;
+          case 'secretbackends':
+            deps.log(formatSecretBackendDetail(item));
+            break;
+          case 'llms':
+            deps.log(formatLlmDetail(item));
+            break;
           case 'projects': {
             const projectPrompts = await deps.client
               .get<Array<{ name: string; priority: number; linkTarget: string | null }>>(`/api/v1/prompts?projectId=${item.id as string}`)

src/cli/src/commands/get.ts

@@ -119,6 +119,43 @@ const rbacColumns: Column<RbacRow>[] = [
   { header: 'ID', key: 'id' },
 ];
 
+interface LlmRow {
+  id: string;
+  name: string;
+  type: string;
+  model: string;
+  tier: string;
+  url: string;
+  description: string;
+  apiKeyRef: { name: string; key: string } | null;
+}
+
+const llmColumns: Column<LlmRow>[] = [
+  { header: 'NAME', key: 'name' },
+  { header: 'TYPE', key: 'type', width: 12 },
+  { header: 'MODEL', key: 'model', width: 28 },
+  { header: 'TIER', key: 'tier', width: 8 },
+  { header: 'KEY', key: (r) => r.apiKeyRef ? `secret://${r.apiKeyRef.name}/${r.apiKeyRef.key}` : '-', width: 34 },
+  { header: 'ID', key: 'id' },
+];
+
+interface SecretBackendRow {
+  id: string;
+  name: string;
+  type: string;
+  isDefault: boolean;
+  description: string;
+  config?: Record<string, unknown>;
+}
+
+const secretBackendColumns: Column<SecretBackendRow>[] = [
+  { header: 'NAME', key: 'name' },
+  { header: 'TYPE', key: 'type', width: 14 },
+  { header: 'DEFAULT', key: (r) => r.isDefault ? '*' : '', width: 8 },
+  { header: 'DESCRIPTION', key: (r) => r.description || '-', width: 30 },
+  { header: 'ID', key: 'id' },
+];
+
 interface McpTokenRow {
   id: string;
   name: string;
@@ -265,6 +302,10 @@ function getColumnsForResource(resource: string): Column<Record<string, unknown>
       return proxymodelColumns as unknown as Column<Record<string, unknown>>[];
     case 'mcptokens':
       return mcpTokenColumns as unknown as Column<Record<string, unknown>>[];
+    case 'secretbackends':
+      return secretBackendColumns as unknown as Column<Record<string, unknown>>[];
+    case 'llms':
+      return llmColumns as unknown as Column<Record<string, unknown>>[];
     default:
       return [
         { header: 'ID', key: 'id' as keyof Record<string, unknown> },
@@ -287,6 +328,8 @@ const RESOURCE_KIND: Record<string, string> = {
   promptrequests: 'promptrequest',
   serverattachments: 'serverattachment',
   mcptokens: 'mcptoken',
+  secretbackends: 'secretbackend',
+  llms: 'llm',
 };
 
 /**

src/cli/src/commands/migrate.ts

@@ -0,0 +1,80 @@
+import { Command } from 'commander';
+import type { ApiClient } from '../api-client.js';
+
+export interface MigrateCommandDeps {
+  client: ApiClient;
+  log: (...args: unknown[]) => void;
+}
+
+interface MigrateResult {
+  migrated: Array<{ name: string }>;
+  skipped: Array<{ name: string; reason: string }>;
+  failed: Array<{ name: string; error: string }>;
+}
+
+interface DryRunResult {
+  dryRun: true;
+  candidates: Array<{ id: string; name: string }>;
+}
+
+/**
+ * Top-level `mcpctl migrate <subcommand>` verb.
+ *
+ * Today only `secrets` is implemented (SecretBackend → SecretBackend move),
+ * but the command is structured so new migrations can slot in.
+ *
+ * Per-secret atomicity is handled server-side — if this command is interrupted
+ * mid-run, re-running is idempotent (skips secrets already on the destination).
+ */
+export function createMigrateCommand(deps: MigrateCommandDeps): Command {
+  const { client, log } = deps;
+
+  const cmd = new Command('migrate')
+    .description('Move resources between backends (currently: secrets between SecretBackends)');
+
+  cmd.command('secrets')
+    .description('Migrate secrets from one SecretBackend to another')
+    .requiredOption('--from <name>', 'Source SecretBackend name')
+    .requiredOption('--to <name>', 'Destination SecretBackend name')
+    .option('--names <csv>', 'Comma-separated secret names (default: all)')
+    .option('--keep-source', 'Leave the source copy intact (default: delete from source after write+commit)')
+    .option('--dry-run', 'Show which secrets would be migrated without touching them')
+    .action(async (opts) => {
+      const body: Record<string, unknown> = { from: opts.from, to: opts.to };
+      if (opts.names) body.names = (opts.names as string).split(',').map((s) => s.trim()).filter(Boolean);
+      if (opts.keepSource) body.keepSource = true;
+      if (opts.dryRun) body.dryRun = true;
+
+      if (opts.dryRun) {
+        const res = await client.post<DryRunResult>('/api/v1/secrets/migrate', body);
+        if (res.candidates.length === 0) {
+          log(`No secrets to migrate from '${opts.from as string}' to '${opts.to as string}'.`);
+          return;
+        }
+        log(`Dry run — ${String(res.candidates.length)} secret(s) would be migrated from '${opts.from as string}' → '${opts.to as string}':`);
+        for (const c of res.candidates) log(`  - ${c.name}`);
+        return;
+      }
+
+      const res = await client.post<MigrateResult>('/api/v1/secrets/migrate', body);
+
+      if (res.migrated.length > 0) {
+        log(`Migrated ${String(res.migrated.length)} secret(s) from '${opts.from as string}' → '${opts.to as string}':`);
+        for (const m of res.migrated) log(`  ✓ ${m.name}`);
+      }
+      if (res.skipped.length > 0) {
+        log(`Skipped ${String(res.skipped.length)}:`);
+        for (const s of res.skipped) log(`  - ${s.name}: ${s.reason}`);
+      }
+      if (res.failed.length > 0) {
+        log(`Failed ${String(res.failed.length)}:`);
+        for (const f of res.failed) log(`  ✗ ${f.name}: ${f.error}`);
+        process.exitCode = 1;
+      }
+      if (res.migrated.length === 0 && res.skipped.length === 0 && res.failed.length === 0) {
+        log(`No secrets to migrate from '${opts.from as string}' to '${opts.to as string}'.`);
+      }
+    });
+
+  return cmd;
+}

src/cli/src/commands/shared.ts

@@ -31,6 +31,11 @@ export const RESOURCE_ALIASES: Record<string, string> = {
   mcptokens: 'mcptokens',
   token: 'mcptokens',
   tokens: 'mcptokens',
+  secretbackend: 'secretbackends',
+  secretbackends: 'secretbackends',
+  sb: 'secretbackends',
+  llm: 'llms',
+  llms: 'llms',
   all: 'all',
 };
 

src/cli/src/index.ts

@@ -18,6 +18,7 @@ import { createMcpCommand } from './commands/mcp.js';
 import { createPatchCommand } from './commands/patch.js';
 import { createConsoleCommand } from './commands/console/index.js';
 import { createCacheCommand } from './commands/cache.js';
+import { createMigrateCommand } from './commands/migrate.js';
 import { ApiClient, ApiError } from './api-client.js';
 import { loadConfig } from './config/index.js';
 import { loadCredentials } from './auth/index.js';
@@ -249,6 +250,11 @@ export function createProgram(): Command {
     log: (...args) => console.log(...args),
   }));
 
+  program.addCommand(createMigrateCommand({
+    client,
+    log: (...args) => console.log(...args),
+  }));
+
   return program;
 }
 

src/db/prisma/schema.prisma

@@ -111,17 +111,79 @@ model McpTemplate {
   @@index([name])
 }
 
+// ── Secret Backends ──
+//
+// Pluggable storage for Secret.data. Default is `plaintext` (data stored in
+// Secret.data JSON). Other drivers (e.g. `openbao`) store only a reference in
+// Secret.externalRef and fetch actual values from the external system at read
+// time. A `plaintext` row is seeded on first startup so the system always has
+// a viable backend; additional backends are user-managed via
+// `mcpctl create secretbackend`.
+
+model SecretBackend {
+  id          String   @id @default(cuid())
+  name        String   @unique
+  type        String                                  // plaintext | openbao | (future: vault, aws-sm, ...)
+  config      Json     @default("{}")                 // type-specific: url, mount, namespace, tokenSecretRef
+  isDefault   Boolean  @default(false)                // exactly one row has isDefault=true
+  description String   @default("")
+  version     Int      @default(1)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  secrets Secret[]
+
+  @@index([name])
+  @@index([isDefault])
+}
+
 // ── Secrets ──
 
 model Secret {
   id          String   @id @default(cuid())
   name        String   @unique
-  data      Json     @default("{}")
+  backendId   String                                  // FK to SecretBackend — dispatches read/write
+  data        Json     @default("{}")                 // populated by plaintext backend only
+  externalRef String   @default("")                   // populated by non-plaintext backends (e.g. "mount/path#v3")
   version     Int      @default(1)
   createdAt   DateTime @default(now())
   updatedAt   DateTime @updatedAt
 
+  backend SecretBackend @relation(fields: [backendId], references: [id])
+  llms    Llm[]
+
   @@index([name])
+  @@index([backendId])
+}
+
+// ── LLMs ──
+//
+// Server-managed LLM providers. Clients (agent, HTTP-mode mcplocal) send
+// OpenAI-format requests to `mcpd /api/v1/llms/:name/infer` — mcpd attaches the
+// provider API key server-side so credentials never leave the cluster.
+// Credentials are stored by reference: `apiKeySecret` points at a Secret, and
+// `apiKeySecretKey` names the key within that secret's data.
+
+model Llm {
+  id              String   @id @default(cuid())
+  name            String   @unique
+  type            String                                  // anthropic | openai | deepseek | vllm | ollama | gemini-cli
+  model           String                                  // e.g. claude-3-5-sonnet-20241022
+  url             String   @default("")                   // endpoint (empty for provider default)
+  tier            String   @default("fast")               // fast | heavy
+  description     String   @default("")
+  apiKeySecretId  String?                                 // FK to Secret
+  apiKeySecretKey String?                                 // key inside the Secret's data
+  extraConfig     Json     @default("{}")                 // per-type extras
+  version         Int      @default(1)
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+
+  apiKeySecret Secret? @relation(fields: [apiKeySecretId], references: [id], onDelete: SetNull)
+
+  @@index([name])
+  @@index([tier])
+  @@index([apiKeySecretId])
 }
 
 // ── Groups ──

src/mcpd/src/bootstrap/secret-backends.ts

@@ -0,0 +1,53 @@
+/**
+ * Bootstrap the `plaintext` SecretBackend + backfill existing Secret rows.
+ *
+ * Runs on every mcpd startup. Idempotent:
+ *   - if no SecretBackend exists, create `default` (type `plaintext`, isDefault=true)
+ *   - if any Secret has no backendId (fresh after schema migration), point it at `default`
+ *   - if no backend is currently flagged default, promote `default`
+ *
+ * Safe to run repeatedly; never destroys configuration.
+ */
+import type { PrismaClient } from '@prisma/client';
+
+/** Well-known name for the always-present plaintext backend. */
+export const DEFAULT_PLAINTEXT_BACKEND_NAME = 'default';
+
+export async function bootstrapSecretBackends(prisma: PrismaClient): Promise<void> {
+  let plaintext = await prisma.secretBackend.findUnique({
+    where: { name: DEFAULT_PLAINTEXT_BACKEND_NAME },
+  });
+
+  if (plaintext === null) {
+    plaintext = await prisma.secretBackend.create({
+      data: {
+        name: DEFAULT_PLAINTEXT_BACKEND_NAME,
+        type: 'plaintext',
+        isDefault: true,
+        description: 'Default in-database plaintext backend. Seeded on first startup.',
+      },
+    });
+  }
+
+  const currentDefault = await prisma.secretBackend.findFirst({ where: { isDefault: true } });
+  if (currentDefault === null) {
+    await prisma.secretBackend.update({
+      where: { id: plaintext.id },
+      data: { isDefault: true },
+    });
+  }
+
+  // Backfill any secrets left with an empty backendId after the schema migration.
+  // `findMany({ where: { backendId: '' } })` catches rows that existed before
+  // the column was added and had a default-empty value assigned.
+  const orphans = await prisma.secret.findMany({
+    where: { backendId: '' },
+    select: { id: true },
+  });
+  if (orphans.length > 0) {
+    await prisma.secret.updateMany({
+      where: { id: { in: orphans.map((o) => o.id) } },
+      data: { backendId: plaintext.id },
+    });
+  }
+}

src/mcpd/src/main.ts

@@ -20,6 +20,15 @@ import {
   AuditEventRepository,
   McpTokenRepository,
 } from './repositories/index.js';
+import { SecretBackendRepository } from './repositories/secret-backend.repository.js';
+import { SecretBackendService } from './services/secret-backend.service.js';
+import { SecretMigrateService } from './services/secret-migrate.service.js';
+import { bootstrapSecretBackends } from './bootstrap/secret-backends.js';
+import { registerSecretBackendRoutes } from './routes/secret-backends.js';
+import { registerSecretMigrateRoutes } from './routes/secret-migrate.js';
+import { LlmRepository } from './repositories/llm.repository.js';
+import { LlmService } from './services/llm.service.js';
+import { registerLlmRoutes } from './routes/llms.js';
 import { PromptRepository } from './repositories/prompt.repository.js';
 import { PromptRequestRepository } from './repositories/prompt-request.repository.js';
 import { bootstrapSystemProject } from './bootstrap/system-project.js';
@@ -93,11 +102,14 @@ function mapUrlToPermission(method: string, url: string): PermissionCheck {
   if (segment === 'backup') return { kind: 'operation', operation: 'backup' };
   if (segment === 'restore') return { kind: 'operation', operation: 'restore' };
   if (segment === 'audit-logs' && method === 'DELETE') return { kind: 'operation', operation: 'audit-purge' };
+  // /api/v1/secrets/migrate is a bulk cross-backend operation — treat as op, not a plain secret write.
+  if (url.startsWith('/api/v1/secrets/migrate')) return { kind: 'operation', operation: 'migrate-secrets' };
 
   const resourceMap: Record<string, string | undefined> = {
     'servers': 'servers',
     'instances': 'instances',
     'secrets': 'secrets',
+    'secretbackends': 'secretbackends',
     'projects': 'projects',
     'templates': 'templates',
     'users': 'users',
@@ -108,6 +120,7 @@ function mapUrlToPermission(method: string, url: string): PermissionCheck {
     'prompts': 'prompts',
     'promptrequests': 'promptrequests',
     'mcptokens': 'mcptokens',
+    'llms': 'llms',
   };
 
   const resource = resourceMap[segment];
@@ -261,6 +274,8 @@ async function main(): Promise<void> {
   // Repositories
   const serverRepo = new McpServerRepository(prisma);
   const secretRepo = new SecretRepository(prisma);
+  const secretBackendRepo = new SecretBackendRepository(prisma);
+  const llmRepo = new LlmRepository(prisma);
   const instanceRepo = new McpInstanceRepository(prisma);
   const projectRepo = new ProjectRepository(prisma);
   const auditLogRepo = new AuditLogRepository(prisma);
@@ -271,14 +286,20 @@ async function main(): Promise<void> {
   const groupRepo = new GroupRepository(prisma);
   const mcpTokenRepo = new McpTokenRepository(prisma);
 
+  // SecretBackend bootstrap: ensure a `plaintext` default row exists and any
+  // pre-existing `Secret` rows are pointed at it. Idempotent per run.
+  await bootstrapSecretBackends(prisma);
+
   // CUID detection for RBAC name resolution
   const CUID_RE = /^c[^\s-]{8,}$/i;
   const nameResolvers: Record<string, { findById(id: string): Promise<{ name: string } | null> }> = {
     servers: serverRepo,
     secrets: secretRepo,
+    secretbackends: secretBackendRepo,
     projects: projectRepo,
     groups: groupRepo,
     mcptokens: mcpTokenRepo,
+    llms: llmRepo,
   };
 
   // Migrate legacy 'admin' role → granular roles
@@ -291,9 +312,30 @@ async function main(): Promise<void> {
 
   // Services
   const serverService = new McpServerService(serverRepo);
-  const instanceService = new InstanceService(instanceRepo, serverRepo, orchestrator, secretRepo);
+  // SecretBackend service — needs a lazy bridge to the yet-to-be-constructed
+  // SecretService because the OpenBao driver's auth token lives in a plaintext
+  // Secret. The bridge defers the resolve until after `secretService` is
+  // assigned, breaking the circular dependency at construction time.
+  const secretResolverBridge = {
+    resolve: async (name: string, key: string): Promise<string> => secretService.resolve(name, key),
+  };
+  const secretBackendService = new SecretBackendService(secretBackendRepo, {
+    plaintext: {
+      listAllPlaintext: async () => {
+        const rows = await prisma.secret.findMany({
+          where: { backend: { type: 'plaintext' } },
+          select: { name: true, data: true },
+        });
+        return rows.map((r) => ({ name: r.name, data: r.data as Record<string, string> }));
+      },
+    },
+    secretRefResolver: secretResolverBridge,
+  });
+  const secretService = new SecretService(secretRepo, secretBackendService);
+  const secretMigrateService = new SecretMigrateService(secretRepo, secretBackendService);
+  const llmService = new LlmService(llmRepo, secretService);
+  const instanceService = new InstanceService(instanceRepo, serverRepo, orchestrator, secretService);
   serverService.setInstanceService(instanceService);
-  const secretService = new SecretService(secretRepo);
   const projectService = new ProjectService(projectRepo, serverRepo);
   const auditLogService = new AuditLogService(auditLogRepo);
   const auditEventService = new AuditEventService(auditEventRepo);
@@ -313,7 +355,7 @@ async function main(): Promise<void> {
   promptRuleRegistry.register(systemPromptVarsRule);
   const promptService = new PromptService(promptRepo, promptRequestRepo, projectRepo, promptRuleRegistry);
   const backupService = new BackupService(serverRepo, projectRepo, secretRepo, userRepo, groupRepo, rbacDefinitionRepo, promptRepo, templateRepo);
-  const restoreService = new RestoreService(serverRepo, projectRepo, secretRepo, userRepo, groupRepo, rbacDefinitionRepo, promptRepo, templateRepo);
+  const restoreService = new RestoreService(serverRepo, projectRepo, secretRepo, secretService, userRepo, groupRepo, rbacDefinitionRepo, promptRepo, templateRepo);
 
   // Shared auth dependencies. Both the global auth hook and the per-route
   // preHandler on /api/v1/mcp/proxy must know how to resolve both session
@@ -430,6 +472,9 @@ async function main(): Promise<void> {
   registerMcpServerRoutes(app, serverService, instanceService);
   registerTemplateRoutes(app, templateService);
   registerSecretRoutes(app, secretService);
+  registerSecretBackendRoutes(app, secretBackendService);
+  registerSecretMigrateRoutes(app, secretMigrateService);
+  registerLlmRoutes(app, llmService);
   registerInstanceRoutes(app, instanceService);
   registerProjectRoutes(app, projectService);
   registerAuditLogRoutes(app, auditLogService);

src/mcpd/src/repositories/interfaces.ts

@@ -1,6 +1,6 @@
 import type { McpServer, McpInstance, AuditLog, AuditEvent, McpToken, Secret, InstanceStatus } from '@prisma/client';
 import type { CreateMcpServerInput, UpdateMcpServerInput } from '../validation/mcp-server.schema.js';
-import type { CreateSecretInput, UpdateSecretInput } from '../validation/secret.schema.js';
+import type { SecretRepoCreateInput, SecretRepoUpdateInput } from './secret.repository.js';
 
 export interface IMcpServerRepository {
   findAll(): Promise<McpServer[]>;
@@ -24,8 +24,9 @@ export interface ISecretRepository {
   findAll(): Promise<Secret[]>;
   findById(id: string): Promise<Secret | null>;
   findByName(name: string): Promise<Secret | null>;
-  create(data: CreateSecretInput): Promise<Secret>;
+  findByBackend(backendId: string): Promise<Secret[]>;
-  update(id: string, data: UpdateSecretInput): Promise<Secret>;
+  create(data: SecretRepoCreateInput): Promise<Secret>;
+  update(id: string, data: SecretRepoUpdateInput): Promise<Secret>;
   delete(id: string): Promise<void>;
 }
 

src/mcpd/src/repositories/llm.repository.ts

@@ -0,0 +1,89 @@
+import type { PrismaClient, Llm, Prisma } from '@prisma/client';
+
+export interface CreateLlmInput {
+  name: string;
+  type: string;
+  model: string;
+  url?: string;
+  tier?: string;
+  description?: string;
+  apiKeySecretId?: string | null;
+  apiKeySecretKey?: string | null;
+  extraConfig?: Record<string, unknown>;
+}
+
+export interface UpdateLlmInput {
+  model?: string;
+  url?: string;
+  tier?: string;
+  description?: string;
+  apiKeySecretId?: string | null;
+  apiKeySecretKey?: string | null;
+  extraConfig?: Record<string, unknown>;
+}
+
+export interface ILlmRepository {
+  findAll(): Promise<Llm[]>;
+  findById(id: string): Promise<Llm | null>;
+  findByName(name: string): Promise<Llm | null>;
+  findByTier(tier: string): Promise<Llm[]>;
+  create(data: CreateLlmInput): Promise<Llm>;
+  update(id: string, data: UpdateLlmInput): Promise<Llm>;
+  delete(id: string): Promise<void>;
+}
+
+export class LlmRepository implements ILlmRepository {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async findAll(): Promise<Llm[]> {
+    return this.prisma.llm.findMany({ orderBy: { name: 'asc' } });
+  }
+
+  async findById(id: string): Promise<Llm | null> {
+    return this.prisma.llm.findUnique({ where: { id } });
+  }
+
+  async findByName(name: string): Promise<Llm | null> {
+    return this.prisma.llm.findUnique({ where: { name } });
+  }
+
+  async findByTier(tier: string): Promise<Llm[]> {
+    return this.prisma.llm.findMany({ where: { tier }, orderBy: { name: 'asc' } });
+  }
+
+  async create(data: CreateLlmInput): Promise<Llm> {
+    return this.prisma.llm.create({
+      data: {
+        name: data.name,
+        type: data.type,
+        model: data.model,
+        url: data.url ?? '',
+        tier: data.tier ?? 'fast',
+        description: data.description ?? '',
+        apiKeySecretId: data.apiKeySecretId ?? null,
+        apiKeySecretKey: data.apiKeySecretKey ?? null,
+        extraConfig: (data.extraConfig ?? {}) as Prisma.InputJsonValue,
+      },
+    });
+  }
+
+  async update(id: string, data: UpdateLlmInput): Promise<Llm> {
+    const updateData: Prisma.LlmUpdateInput = {};
+    if (data.model !== undefined) updateData.model = data.model;
+    if (data.url !== undefined) updateData.url = data.url;
+    if (data.tier !== undefined) updateData.tier = data.tier;
+    if (data.description !== undefined) updateData.description = data.description;
+    if (data.apiKeySecretId !== undefined) {
+      updateData.apiKeySecret = data.apiKeySecretId === null
+        ? { disconnect: true }
+        : { connect: { id: data.apiKeySecretId } };
+    }
+    if (data.apiKeySecretKey !== undefined) updateData.apiKeySecretKey = data.apiKeySecretKey;
+    if (data.extraConfig !== undefined) updateData.extraConfig = data.extraConfig as Prisma.InputJsonValue;
+    return this.prisma.llm.update({ where: { id }, data: updateData });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.prisma.llm.delete({ where: { id } });
+  }
+}

src/mcpd/src/repositories/secret-backend.repository.ts

@@ -0,0 +1,103 @@
+import type { PrismaClient, SecretBackend, Prisma } from '@prisma/client';
+
+export interface CreateSecretBackendInput {
+  name: string;
+  type: string;
+  config?: Record<string, unknown>;
+  isDefault?: boolean;
+  description?: string;
+}
+
+export interface UpdateSecretBackendInput {
+  config?: Record<string, unknown>;
+  isDefault?: boolean;
+  description?: string;
+}
+
+export interface ISecretBackendRepository {
+  findAll(): Promise<SecretBackend[]>;
+  findById(id: string): Promise<SecretBackend | null>;
+  findByName(name: string): Promise<SecretBackend | null>;
+  findDefault(): Promise<SecretBackend | null>;
+  create(data: CreateSecretBackendInput): Promise<SecretBackend>;
+  update(id: string, data: UpdateSecretBackendInput): Promise<SecretBackend>;
+  /**
+   * Atomically clear `isDefault` on every row except the one named, then set
+   * the given row as default. Used by `setDefault`.
+   */
+  setAsDefault(id: string): Promise<SecretBackend>;
+  delete(id: string): Promise<void>;
+  /** Count secrets that still reference this backend — used to guard delete. */
+  countReferencingSecrets(backendId: string): Promise<number>;
+}
+
+export class SecretBackendRepository implements ISecretBackendRepository {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async findAll(): Promise<SecretBackend[]> {
+    return this.prisma.secretBackend.findMany({ orderBy: { name: 'asc' } });
+  }
+
+  async findById(id: string): Promise<SecretBackend | null> {
+    return this.prisma.secretBackend.findUnique({ where: { id } });
+  }
+
+  async findByName(name: string): Promise<SecretBackend | null> {
+    return this.prisma.secretBackend.findUnique({ where: { name } });
+  }
+
+  async findDefault(): Promise<SecretBackend | null> {
+    return this.prisma.secretBackend.findFirst({ where: { isDefault: true } });
+  }
+
+  async create(data: CreateSecretBackendInput): Promise<SecretBackend> {
+    return this.prisma.$transaction(async (tx) => {
+      if (data.isDefault === true) {
+        await tx.secretBackend.updateMany({ where: { isDefault: true }, data: { isDefault: false } });
+      }
+      return tx.secretBackend.create({
+        data: {
+          name: data.name,
+          type: data.type,
+          config: (data.config ?? {}) as Prisma.InputJsonValue,
+          isDefault: data.isDefault ?? false,
+          description: data.description ?? '',
+        },
+      });
+    });
+  }
+
+  async update(id: string, data: UpdateSecretBackendInput): Promise<SecretBackend> {
+    return this.prisma.$transaction(async (tx) => {
+      if (data.isDefault === true) {
+        await tx.secretBackend.updateMany({
+          where: { isDefault: true, NOT: { id } },
+          data: { isDefault: false },
+        });
+      }
+      const updateData: Prisma.SecretBackendUpdateInput = {};
+      if (data.config !== undefined) updateData.config = data.config as Prisma.InputJsonValue;
+      if (data.isDefault !== undefined) updateData.isDefault = data.isDefault;
+      if (data.description !== undefined) updateData.description = data.description;
+      return tx.secretBackend.update({ where: { id }, data: updateData });
+    });
+  }
+
+  async setAsDefault(id: string): Promise<SecretBackend> {
+    return this.prisma.$transaction(async (tx) => {
+      await tx.secretBackend.updateMany({
+        where: { isDefault: true, NOT: { id } },
+        data: { isDefault: false },
+      });
+      return tx.secretBackend.update({ where: { id }, data: { isDefault: true } });
+    });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.prisma.secretBackend.delete({ where: { id } });
+  }
+
+  async countReferencingSecrets(backendId: string): Promise<number> {
+    return this.prisma.secret.count({ where: { backendId } });
+  }
+}

src/mcpd/src/repositories/secret.repository.ts

@@ -1,6 +1,18 @@
-import { type PrismaClient, type Secret } from '@prisma/client';
+import { type PrismaClient, type Secret, type Prisma } from '@prisma/client';
 import type { ISecretRepository } from './interfaces.js';
-import type { CreateSecretInput, UpdateSecretInput } from '../validation/secret.schema.js';
+
+export interface SecretRepoCreateInput {
+  name: string;
+  backendId: string;
+  data?: Record<string, string>;
+  externalRef?: string;
+}
+
+export interface SecretRepoUpdateInput {
+  data?: Record<string, string>;
+  externalRef?: string;
+  backendId?: string;
+}
 
 export class SecretRepository implements ISecretRepository {
   constructor(private readonly prisma: PrismaClient) {}
@@ -17,20 +29,29 @@ export class SecretRepository implements ISecretRepository {
     return this.prisma.secret.findUnique({ where: { name } });
   }
 
-  async create(data: CreateSecretInput): Promise<Secret> {
+  async findByBackend(backendId: string): Promise<Secret[]> {
+    return this.prisma.secret.findMany({ where: { backendId }, orderBy: { name: 'asc' } });
+  }
+
+  async create(data: SecretRepoCreateInput): Promise<Secret> {
     return this.prisma.secret.create({
       data: {
         name: data.name,
-        data: data.data,
+        backendId: data.backendId,
+        data: (data.data ?? {}) as Prisma.InputJsonValue,
+        externalRef: data.externalRef ?? '',
       },
     });
   }
 
-  async update(id: string, data: UpdateSecretInput): Promise<Secret> {
+  async update(id: string, data: SecretRepoUpdateInput): Promise<Secret> {
-    return this.prisma.secret.update({
+    const updateData: Prisma.SecretUpdateInput = {};
-      where: { id },
+    if (data.data !== undefined) updateData.data = data.data as Prisma.InputJsonValue;
-      data: { data: data.data },
+    if (data.externalRef !== undefined) updateData.externalRef = data.externalRef;
-    });
+    if (data.backendId !== undefined) {
+      updateData.backend = { connect: { id: data.backendId } };
+    }
+    return this.prisma.secret.update({ where: { id }, data: updateData });
   }
 
   async delete(id: string): Promise<void> {

src/mcpd/src/routes/llms.ts

@@ -0,0 +1,64 @@
+import type { FastifyInstance } from 'fastify';
+import type { LlmService } from '../services/llm.service.js';
+import { NotFoundError, ConflictError } from '../services/mcp-server.service.js';
+
+export function registerLlmRoutes(
+  app: FastifyInstance,
+  service: LlmService,
+): void {
+  app.get('/api/v1/llms', async () => {
+    return service.list();
+  });
+
+  app.get<{ Params: { id: string } }>('/api/v1/llms/:id', async (request, reply) => {
+    try {
+      return await service.getById(request.params.id);
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        reply.code(404);
+        return { error: err.message };
+      }
+      throw err;
+    }
+  });
+
+  app.post('/api/v1/llms', async (request, reply) => {
+    try {
+      const row = await service.create(request.body);
+      reply.code(201);
+      return row;
+    } catch (err) {
+      if (err instanceof ConflictError) {
+        reply.code(409);
+        return { error: err.message };
+      }
+      throw err;
+    }
+  });
+
+  app.put<{ Params: { id: string } }>('/api/v1/llms/:id', async (request, reply) => {
+    try {
+      return await service.update(request.params.id, request.body);
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        reply.code(404);
+        return { error: err.message };
+      }
+      throw err;
+    }
+  });
+
+  app.delete<{ Params: { id: string } }>('/api/v1/llms/:id', async (request, reply) => {
+    try {
+      await service.delete(request.params.id);
+      reply.code(204);
+      return null;
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        reply.code(404);
+        return { error: err.message };
+      }
+      throw err;
+    }
+  });
+}

src/mcpd/src/routes/secret-backends.ts

@@ -0,0 +1,89 @@
+import type { FastifyInstance } from 'fastify';
+import type { SecretBackendService } from '../services/secret-backend.service.js';
+import { SecretBackendInUseError } from '../services/secret-backend.service.js';
+import { NotFoundError, ConflictError } from '../services/mcp-server.service.js';
+
+export function registerSecretBackendRoutes(
+  app: FastifyInstance,
+  service: SecretBackendService,
+): void {
+  app.get('/api/v1/secretbackends', async () => {
+    const rows = await service.list();
+    return rows.map(redactConfig);
+  });
+
+  app.get<{ Params: { id: string } }>('/api/v1/secretbackends/:id', async (request) => {
+    const row = await service.getById(request.params.id);
+    return redactConfig(row);
+  });
+
+  app.post('/api/v1/secretbackends', async (request, reply) => {
+    try {
+      const row = await service.create(request.body as {
+        name: string;
+        type: string;
+        config?: Record<string, unknown>;
+        isDefault?: boolean;
+        description?: string;
+      });
+      reply.code(201);
+      return redactConfig(row);
+    } catch (err) {
+      if (err instanceof ConflictError) {
+        reply.code(409);
+        return { error: err.message };
+      }
+      throw err;
+    }
+  });
+
+  app.put<{ Params: { id: string } }>('/api/v1/secretbackends/:id', async (request) => {
+    const row = await service.update(request.params.id, request.body as {
+      config?: Record<string, unknown>;
+      isDefault?: boolean;
+      description?: string;
+    });
+    return redactConfig(row);
+  });
+
+  app.post<{ Params: { id: string } }>('/api/v1/secretbackends/:id/default', async (request) => {
+    const row = await service.setDefault(request.params.id);
+    return redactConfig(row);
+  });
+
+  app.delete<{ Params: { id: string } }>('/api/v1/secretbackends/:id', async (request, reply) => {
+    try {
+      await service.delete(request.params.id);
+      reply.code(204);
+      return null;
+    } catch (err) {
+      if (err instanceof SecretBackendInUseError) {
+        reply.code(409);
+        return { error: err.message };
+      }
+      if (err instanceof NotFoundError) {
+        reply.code(404);
+        return { error: err.message };
+      }
+      throw err;
+    }
+  });
+}
+
+/**
+ * Strip any value from `config` whose key looks like a credential, and replace
+ * tokenSecretRef with a short description. Prevents accidental exposure via
+ * GET responses.
+ */
+function redactConfig<T extends { config: unknown }>(row: T): T {
+  const config = (row.config ?? {}) as Record<string, unknown>;
+  const cleaned: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(config)) {
+    if (/token|secret|password|key/i.test(k) && typeof v === 'string') {
+      cleaned[k] = '***';
+    } else {
+      cleaned[k] = v;
+    }
+  }
+  return { ...row, config: cleaned };
+}

src/mcpd/src/routes/secret-migrate.ts

@@ -0,0 +1,41 @@
+import type { FastifyInstance } from 'fastify';
+import type { SecretMigrateService } from '../services/secret-migrate.service.js';
+
+export function registerSecretMigrateRoutes(
+  app: FastifyInstance,
+  service: SecretMigrateService,
+): void {
+  /**
+   * POST /api/v1/secrets/migrate
+   *   body: { from: string, to: string, names?: string[], keepSource?: boolean, dryRun?: boolean }
+   *   RBAC: operation `migrate-secrets` (role:run).
+   */
+  app.post<{
+    Body: {
+      from: string;
+      to: string;
+      names?: string[];
+      keepSource?: boolean;
+      dryRun?: boolean;
+    };
+  }>('/api/v1/secrets/migrate', async (request, reply) => {
+    const { from, to, names, keepSource, dryRun } = request.body;
+    if (!from || !to) {
+      reply.code(400);
+      return { error: 'from and to are required' };
+    }
+
+    if (dryRun === true) {
+      const options: Parameters<SecretMigrateService['dryRun']>[0] = { from, to };
+      if (names !== undefined) options.names = names;
+      if (keepSource !== undefined) options.keepSource = keepSource;
+      const secrets = await service.dryRun(options);
+      return { dryRun: true, candidates: secrets.map((s) => ({ id: s.id, name: s.name })) };
+    }
+
+    const options: Parameters<SecretMigrateService['migrate']>[0] = { from, to };
+    if (names !== undefined) options.names = names;
+    if (keepSource !== undefined) options.keepSource = keepSource;
+    return service.migrate(options);
+  });
+}

src/mcpd/src/services/backup/restore-service.ts

@@ -6,6 +6,7 @@ import type { IRbacDefinitionRepository } from '../../repositories/rbac-definiti
 import type { IPromptRepository } from '../../repositories/prompt.repository.js';
 import type { ITemplateRepository } from '../../repositories/template.repository.js';
 import type { RbacRoleBinding } from '../../validation/rbac-definition.schema.js';
+import type { SecretService } from '../secret.service.js';
 import { decrypt } from './crypto.js';
 import type { BackupBundle } from './backup-service.js';
 
@@ -41,6 +42,7 @@ export class RestoreService {
     private serverRepo: IMcpServerRepository,
     private projectRepo: IProjectRepository,
     private secretRepo: ISecretRepository,
+    private secretService: SecretService,
     private userRepo?: IUserRepository,
     private groupRepo?: IGroupRepository,
     private rbacRepo?: IRbacDefinitionRepository,
@@ -125,16 +127,13 @@ export class RestoreService {
             result.secretsSkipped++;
             continue;
           }
-          // overwrite
+          // overwrite — route through SecretService so backend dispatch applies.
-          await this.secretRepo.update(existing.id, { data: secret.data });
+          await this.secretService.update(existing.id, { data: secret.data });
           result.secretsCreated++;
           continue;
         }
 
-        await this.secretRepo.create({
+        await this.secretService.create({ name: secret.name, data: secret.data });
-          name: secret.name,
-          data: secret.data,
-        });
         result.secretsCreated++;
       } catch (err) {
         result.errors.push(`Failed to restore secret "${secret.name}": ${err instanceof Error ? err.message : String(err)}`);

src/mcpd/src/services/env-resolver.ts

@@ -1,42 +1,44 @@
 import type { McpServer } from '@prisma/client';
-import type { ISecretRepository } from '../repositories/interfaces.js';
 import type { ServerEnvEntry } from '../validation/mcp-server.schema.js';
 
+/**
+ * Minimal dependency surface for the env resolver: anything that can turn a
+ * (secretName, key) pair into a string. Matches `SecretService.resolve()` so
+ * resolution now flows through the configured SecretBackend driver instead
+ * of reading `Secret.data` directly.
+ */
+export interface SecretResolver {
+  resolve(secretName: string, key: string): Promise<string>;
+}
+
 /**
  * Resolve a server's env entries into a flat key-value map.
  * - Inline `value` entries are used directly.
- * - `valueFrom.secretRef` entries are looked up from the secret repository.
+ * - `valueFrom.secretRef` entries are looked up through the resolver.
  * Throws if a referenced secret or key is missing.
  */
 export async function resolveServerEnv(
   server: McpServer,
-  secretRepo: ISecretRepository,
+  resolver: SecretResolver,
 ): Promise<Record<string, string>> {
   const entries = server.env as ServerEnvEntry[];
   if (!entries || entries.length === 0) return {};
 
   const result: Record<string, string> = {};
-  const secretCache = new Map<string, Record<string, string>>();
 
   for (const entry of entries) {
     if (entry.value !== undefined) {
       result[entry.name] = entry.value;
     } else if (entry.valueFrom?.secretRef) {
       const { name: secretName, key } = entry.valueFrom.secretRef;
-
+      try {
-      if (!secretCache.has(secretName)) {
+        result[entry.name] = await resolver.resolve(secretName, key);
-        const secret = await secretRepo.findByName(secretName);
+      } catch (err) {
-        if (!secret) {
+        const msg = err instanceof Error ? err.message : String(err);
-          throw new Error(`Secret '${secretName}' not found (referenced by server '${server.name}' env '${entry.name}')`);
+        throw new Error(
+          `Cannot resolve secret for server '${server.name}' env '${entry.name}': ${msg}`,
+        );
       }
-        secretCache.set(secretName, secret.data as Record<string, string>);
-      }
-
-      const data = secretCache.get(secretName)!;
-      if (!(key in data)) {
-        throw new Error(`Key '${key}' not found in secret '${secretName}' (referenced by server '${server.name}' env '${entry.name}')`);
-      }
-      result[entry.name] = data[key]!;
     }
   }
 

src/mcpd/src/services/instance.service.ts

@@ -1,8 +1,8 @@
 import type { McpInstance } from '@prisma/client';
-import type { IMcpInstanceRepository, IMcpServerRepository, ISecretRepository } from '../repositories/interfaces.js';
+import type { IMcpInstanceRepository, IMcpServerRepository } from '../repositories/interfaces.js';
 import type { McpOrchestrator, ContainerSpec, ContainerInfo } from './orchestrator.js';
 import { NotFoundError } from './mcp-server.service.js';
-import { resolveServerEnv } from './env-resolver.js';
+import { resolveServerEnv, type SecretResolver } from './env-resolver.js';
 
 /** Runner images for package-based MCP servers, keyed by runtime name. */
 const RUNNER_IMAGES: Record<string, string> = {
@@ -26,7 +26,7 @@ export class InstanceService {
     private instanceRepo: IMcpInstanceRepository,
     private serverRepo: IMcpServerRepository,
     private orchestrator: McpOrchestrator,
-    private secretRepo?: ISecretRepository,
+    private secretResolver?: SecretResolver,
   ) {}
 
   async list(serverId?: string): Promise<McpInstance[]> {
@@ -284,9 +284,9 @@ export class InstanceService {
       }
 
       // Resolve env vars from inline values and secret refs
-      if (this.secretRepo) {
+      if (this.secretResolver) {
         try {
-          const resolvedEnv = await resolveServerEnv(server, this.secretRepo);
+          const resolvedEnv = await resolveServerEnv(server, this.secretResolver);
           if (Object.keys(resolvedEnv).length > 0) {
             spec.env = resolvedEnv;
           }

src/mcpd/src/services/llm.service.ts

@@ -0,0 +1,180 @@
+/**
+ * LlmService — CRUD over `Llm` rows plus credential resolution.
+ *
+ * Credentials are stored by reference: the row carries `(apiKeySecretId,
+ * apiKeySecretKey)`. Callers that need the raw key (the inference proxy, once
+ * it lands in Phase 2) call `resolveApiKey()`, which reads through the
+ * SecretService (whose own backend dispatch transparently hits plaintext or
+ * OpenBao as configured).
+ *
+ * The CLI/API accepts `apiKeyRef: { name, key }` — the service translates
+ * that to the FK pair.
+ */
+import type { Llm } from '@prisma/client';
+import type { ILlmRepository } from '../repositories/llm.repository.js';
+import type { SecretService } from './secret.service.js';
+import {
+  CreateLlmSchema,
+  UpdateLlmSchema,
+  type CreateLlmInput,
+  type ApiKeyRef,
+} from '../validation/llm.schema.js';
+import { NotFoundError, ConflictError } from './mcp-server.service.js';
+
+/** Shape returned by API layer — merges DB row with a human-readable apiKeyRef. */
+export interface LlmView {
+  id: string;
+  name: string;
+  type: string;
+  model: string;
+  url: string;
+  tier: string;
+  description: string;
+  apiKeyRef: ApiKeyRef | null;
+  extraConfig: Record<string, unknown>;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export class LlmService {
+  constructor(
+    private readonly repo: ILlmRepository,
+    private readonly secrets: SecretService,
+  ) {}
+
+  async list(): Promise<LlmView[]> {
+    const rows = await this.repo.findAll();
+    return Promise.all(rows.map((r) => this.toView(r)));
+  }
+
+  async getById(id: string): Promise<LlmView> {
+    const row = await this.repo.findById(id);
+    if (row === null) throw new NotFoundError(`Llm not found: ${id}`);
+    return this.toView(row);
+  }
+
+  async getByName(name: string): Promise<LlmView> {
+    const row = await this.repo.findByName(name);
+    if (row === null) throw new NotFoundError(`Llm not found: ${name}`);
+    return this.toView(row);
+  }
+
+  async create(input: unknown): Promise<LlmView> {
+    const data = CreateLlmSchema.parse(input);
+    const existing = await this.repo.findByName(data.name);
+    if (existing !== null) throw new ConflictError(`Llm already exists: ${data.name}`);
+
+    const apiKeyFields = await this.resolveApiKeyRefToIds(data.apiKeyRef);
+    const row = await this.repo.create({
+      name: data.name,
+      type: data.type,
+      model: data.model,
+      url: data.url ?? '',
+      tier: data.tier,
+      description: data.description,
+      apiKeySecretId: apiKeyFields.id,
+      apiKeySecretKey: apiKeyFields.key,
+      extraConfig: data.extraConfig,
+    });
+    return this.toView(row);
+  }
+
+  async update(id: string, input: unknown): Promise<LlmView> {
+    const data = UpdateLlmSchema.parse(input);
+    await this.getById(id);
+
+    const updateFields: Parameters<ILlmRepository['update']>[1] = {};
+    if (data.model !== undefined) updateFields.model = data.model;
+    if (data.url !== undefined) updateFields.url = data.url;
+    if (data.tier !== undefined) updateFields.tier = data.tier;
+    if (data.description !== undefined) updateFields.description = data.description;
+    if (data.extraConfig !== undefined) updateFields.extraConfig = data.extraConfig;
+
+    // apiKeyRef: null → explicit unlink; object → replace; undefined → leave alone.
+    if (data.apiKeyRef !== undefined) {
+      if (data.apiKeyRef === null) {
+        updateFields.apiKeySecretId = null;
+        updateFields.apiKeySecretKey = null;
+      } else {
+        const resolved = await this.resolveApiKeyRefToIds(data.apiKeyRef);
+        updateFields.apiKeySecretId = resolved.id;
+        updateFields.apiKeySecretKey = resolved.key;
+      }
+    }
+
+    const row = await this.repo.update(id, updateFields);
+    return this.toView(row);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.getById(id);
+    await this.repo.delete(id);
+  }
+
+  /**
+   * Return the raw API key string for a given Llm. Called by the inference
+   * proxy in Phase 2. Throws NotFoundError if the Llm has no apiKeyRef, or the
+   * referenced secret/key doesn't exist.
+   */
+  async resolveApiKey(llmName: string): Promise<string> {
+    const row = await this.repo.findByName(llmName);
+    if (row === null) throw new NotFoundError(`Llm not found: ${llmName}`);
+    if (row.apiKeySecretId === null || row.apiKeySecretKey === null) {
+      throw new NotFoundError(`Llm '${llmName}' has no apiKeyRef configured`);
+    }
+    const secret = await this.secrets.getById(row.apiKeySecretId);
+    const data = await this.secrets.resolveData(secret);
+    const value = data[row.apiKeySecretKey];
+    if (value === undefined) {
+      throw new NotFoundError(`Secret '${secret.name}' has no key '${row.apiKeySecretKey}'`);
+    }
+    return value;
+  }
+
+  private async resolveApiKeyRefToIds(ref: ApiKeyRef | undefined): Promise<{ id: string | null; key: string | null }> {
+    if (ref === undefined) return { id: null, key: null };
+    const secret = await this.secrets.getByName(ref.name);
+    return { id: secret.id, key: ref.key };
+  }
+
+  private async toView(row: Llm): Promise<LlmView> {
+    let apiKeyRef: ApiKeyRef | null = null;
+    if (row.apiKeySecretId !== null && row.apiKeySecretKey !== null) {
+      const secret = await this.secrets.getById(row.apiKeySecretId).catch(() => null);
+      if (secret !== null) {
+        apiKeyRef = { name: secret.name, key: row.apiKeySecretKey };
+      }
+    }
+    return {
+      id: row.id,
+      name: row.name,
+      type: row.type,
+      model: row.model,
+      url: row.url,
+      tier: row.tier,
+      description: row.description,
+      apiKeyRef,
+      extraConfig: row.extraConfig as Record<string, unknown>,
+      version: row.version,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+
+  // ── Backup/restore helpers ──
+
+  async upsertByName(input: CreateLlmInput): Promise<LlmView> {
+    const existing = await this.repo.findByName(input.name);
+    if (existing !== null) {
+      return this.update(existing.id, input);
+    }
+    return this.create(input);
+  }
+
+  async deleteByName(name: string): Promise<void> {
+    const row = await this.repo.findByName(name);
+    if (row === null) return;
+    await this.delete(row.id);
+  }
+}

src/mcpd/src/services/secret-backend.service.ts

@@ -0,0 +1,88 @@
+import type { SecretBackend } from '@prisma/client';
+import type { ISecretBackendRepository } from '../repositories/secret-backend.repository.js';
+import type { SecretBackendDriver } from './secret-backends/types.js';
+import { createDriver, type DriverFactoryDeps } from './secret-backends/factory.js';
+import { NotFoundError, ConflictError } from './mcp-server.service.js';
+
+export class SecretBackendInUseError extends Error {
+  constructor(backendName: string, count: number) {
+    super(`SecretBackend '${backendName}' is still referenced by ${String(count)} secret(s); migrate them first`);
+    this.name = 'SecretBackendInUseError';
+  }
+}
+
+export class SecretBackendService {
+  private driverCache = new Map<string, SecretBackendDriver>(); // keyed by backend id
+
+  constructor(
+    private readonly repo: ISecretBackendRepository,
+    private readonly driverDeps: DriverFactoryDeps,
+  ) {}
+
+  async list(): Promise<SecretBackend[]> {
+    return this.repo.findAll();
+  }
+
+  async getById(id: string): Promise<SecretBackend> {
+    const row = await this.repo.findById(id);
+    if (row === null) throw new NotFoundError(`SecretBackend not found: ${id}`);
+    return row;
+  }
+
+  async getByName(name: string): Promise<SecretBackend> {
+    const row = await this.repo.findByName(name);
+    if (row === null) throw new NotFoundError(`SecretBackend not found: ${name}`);
+    return row;
+  }
+
+  async getDefault(): Promise<SecretBackend> {
+    const row = await this.repo.findDefault();
+    if (row === null) {
+      throw new Error('No default SecretBackend configured. This shouldn\'t happen — the plaintext row should have been seeded on startup.');
+    }
+    return row;
+  }
+
+  async create(input: {
+    name: string;
+    type: string;
+    config?: Record<string, unknown>;
+    isDefault?: boolean;
+    description?: string;
+  }): Promise<SecretBackend> {
+    if (!input.name || !input.type) throw new Error('name and type are required');
+    const existing = await this.repo.findByName(input.name);
+    if (existing !== null) throw new ConflictError(`SecretBackend already exists: ${input.name}`);
+    return this.repo.create(input);
+  }
+
+  async update(id: string, input: { config?: Record<string, unknown>; isDefault?: boolean; description?: string }): Promise<SecretBackend> {
+    await this.getById(id);
+    const row = await this.repo.update(id, input);
+    this.driverCache.delete(id); // config may have changed; rebuild lazily
+    return row;
+  }
+
+  async setDefault(id: string): Promise<SecretBackend> {
+    await this.getById(id);
+    return this.repo.setAsDefault(id);
+  }
+
+  async delete(id: string): Promise<void> {
+    const row = await this.getById(id);
+    const count = await this.repo.countReferencingSecrets(id);
+    if (count > 0) throw new SecretBackendInUseError(row.name, count);
+    if (row.isDefault) throw new Error(`Cannot delete the default SecretBackend '${row.name}'; promote another one first`);
+    await this.repo.delete(id);
+    this.driverCache.delete(id);
+  }
+
+  /** Get the driver for a given backend id, creating + caching on first call. */
+  driverFor(backend: SecretBackend): SecretBackendDriver {
+    const cached = this.driverCache.get(backend.id);
+    if (cached) return cached;
+    const driver = createDriver(backend, this.driverDeps);
+    this.driverCache.set(backend.id, driver);
+    return driver;
+  }
+}

src/mcpd/src/services/secret-backends/factory.ts

@@ -0,0 +1,43 @@
+/**
+ * Build a `SecretBackendDriver` from a `SecretBackend` row.
+ *
+ * Lives separate from the service because it's the only place aware of every
+ * driver type — adding a new backend means adding one case here and one
+ * driver file. Everything else (service, routes, CLI) is type-agnostic.
+ */
+import type { SecretBackend } from '@prisma/client';
+import type { SecretBackendDriver, SecretRefResolver } from './types.js';
+import { PlaintextDriver, type PlaintextDriverDeps } from './plaintext.js';
+import { OpenBaoDriver, type OpenBaoConfig } from './openbao.js';
+
+export interface DriverFactoryDeps {
+  plaintext: PlaintextDriverDeps;
+  /** Resolves `{secretName, key}` against the plaintext backend — used by remote drivers' auth. */
+  secretRefResolver: SecretRefResolver;
+  /** Overridable for tests. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export function createDriver(row: SecretBackend, deps: DriverFactoryDeps): SecretBackendDriver {
+  switch (row.type) {
+    case 'plaintext':
+      return new PlaintextDriver(deps.plaintext);
+
+    case 'openbao': {
+      const cfg = row.config as unknown as OpenBaoConfig;
+      if (!cfg.url || !cfg.tokenSecretRef?.name || !cfg.tokenSecretRef?.key) {
+        throw new Error(
+          `SecretBackend '${row.name}' (openbao): config must provide url + tokenSecretRef {name, key}`,
+        );
+      }
+      const driverDeps: { fetch?: typeof globalThis.fetch; secretRefResolver: SecretRefResolver } = {
+        secretRefResolver: deps.secretRefResolver,
+      };
+      if (deps.fetch !== undefined) driverDeps.fetch = deps.fetch;
+      return new OpenBaoDriver(cfg, driverDeps);
+    }
+
+    default:
+      throw new Error(`Unknown SecretBackend type: ${row.type}`);
+  }
+}

src/mcpd/src/services/secret-backends/openbao.ts

@@ -0,0 +1,133 @@
+/**
+ * OpenBao (MPL 2.0 fork of HashiCorp Vault) driver for the KV v2 secrets engine.
+ *
+ * Uses the plain HTTP API — no third-party client — so we don't pick up a
+ * Vault SDK licensing headache. Endpoints touched:
+ *
+ *   POST   <url>/v1/<mount>/data/<path>     -- write
+ *   GET    <url>/v1/<mount>/data/<path>     -- read latest
+ *   DELETE <url>/v1/<mount>/metadata/<path> -- full delete (all versions)
+ *   LIST   <url>/v1/<mount>/metadata/        -- for migration
+ *
+ * Auth: static token for v1. The token is stored in a `Secret` on the
+ * plaintext backend (see `config.tokenSecretRef = { name, key }`); the driver
+ * resolves it on construction via the injected `SecretRefResolver`. Follow-up
+ * work (not here) adds Kubernetes ServiceAccount auth.
+ *
+ * Path layout inside OpenBao:
+ *   <mount>/<pathPrefix>/<secretName>
+ * `mount` and `pathPrefix` come from the backend's `config` JSON; defaults are
+ * `secret` and `mcpctl/`.
+ */
+import type { SecretBackendDriver, SecretData, ExternalRef, SecretRefResolver } from './types.js';
+
+export interface OpenBaoConfig {
+  url: string;
+  mount?: string;
+  pathPrefix?: string;
+  namespace?: string;
+  tokenSecretRef: { name: string; key: string };
+}
+
+export interface OpenBaoDriverDeps {
+  /** Injected HTTP fetcher — mockable in tests. */
+  fetch?: typeof globalThis.fetch;
+  secretRefResolver: SecretRefResolver;
+}
+
+export class OpenBaoDriver implements SecretBackendDriver {
+  readonly kind = 'openbao';
+
+  private readonly url: string;
+  private readonly mount: string;
+  private readonly pathPrefix: string;
+  private readonly namespace: string | undefined;
+  private readonly tokenSecretRef: { name: string; key: string };
+  private readonly fetchImpl: typeof globalThis.fetch;
+  private readonly resolver: SecretRefResolver;
+  private cachedToken: string | undefined;
+
+  constructor(config: OpenBaoConfig, deps: OpenBaoDriverDeps) {
+    this.url = config.url.replace(/\/+$/, '');
+    this.mount = (config.mount ?? 'secret').replace(/^\/|\/$/g, '');
+    this.pathPrefix = (config.pathPrefix ?? 'mcpctl').replace(/^\/|\/$/g, '');
+    if (config.namespace !== undefined) this.namespace = config.namespace;
+    this.tokenSecretRef = config.tokenSecretRef;
+    this.fetchImpl = deps.fetch ?? globalThis.fetch;
+    this.resolver = deps.secretRefResolver;
+  }
+
+  async read(input: { name: string; externalRef: ExternalRef; data: SecretData }): Promise<SecretData> {
+    const path = this.pathFor(input.name);
+    const res = await this.request('GET', `/v1/${this.mount}/data/${path}`);
+    if (res.status === 404) {
+      throw new Error(`OpenBao: secret '${input.name}' not found at ${path}`);
+    }
+    if (!res.ok) throw new Error(`OpenBao read ${path}: HTTP ${res.status}`);
+    const body = await res.json() as { data?: { data?: SecretData } };
+    return body.data?.data ?? {};
+  }
+
+  async write(input: { name: string; data: SecretData }): Promise<{ externalRef: ExternalRef; storedData: SecretData }> {
+    const path = this.pathFor(input.name);
+    const res = await this.request('POST', `/v1/${this.mount}/data/${path}`, { data: input.data });
+    if (!res.ok) throw new Error(`OpenBao write ${path}: HTTP ${res.status}`);
+    return { externalRef: `${this.mount}/${path}`, storedData: {} };
+  }
+
+  async delete(input: { name: string; externalRef: ExternalRef }): Promise<void> {
+    const path = this.pathFor(input.name);
+    const res = await this.request('DELETE', `/v1/${this.mount}/metadata/${path}`);
+    if (!res.ok && res.status !== 404) {
+      throw new Error(`OpenBao delete ${path}: HTTP ${res.status}`);
+    }
+  }
+
+  async list(): Promise<Array<{ name: string; externalRef: ExternalRef }>> {
+    const listPath = this.pathPrefix === '' ? '' : `${this.pathPrefix}/`;
+    const res = await this.request('LIST', `/v1/${this.mount}/metadata/${listPath}`);
+    if (res.status === 404) return [];
+    if (!res.ok) throw new Error(`OpenBao list: HTTP ${res.status}`);
+    const body = await res.json() as { data?: { keys?: string[] } };
+    const keys = body.data?.keys ?? [];
+    return keys
+      .filter((k) => !k.endsWith('/'))
+      .map((k) => ({
+        name: k,
+        externalRef: `${this.mount}/${this.pathPrefix === '' ? '' : `${this.pathPrefix}/`}${k}`,
+      }));
+  }
+
+  async healthCheck(): Promise<{ ok: boolean; detail?: string }> {
+    try {
+      const res = await this.request('GET', '/v1/sys/health');
+      return { ok: res.ok, detail: `HTTP ${res.status}` };
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  private pathFor(name: string): string {
+    const safe = encodeURIComponent(name);
+    return this.pathPrefix === '' ? safe : `${this.pathPrefix}/${safe}`;
+  }
+
+  private async getToken(): Promise<string> {
+    if (this.cachedToken !== undefined) return this.cachedToken;
+    const token = await this.resolver.resolve(this.tokenSecretRef.name, this.tokenSecretRef.key);
+    this.cachedToken = token;
+    return token;
+  }
+
+  private async request(method: string, path: string, body?: unknown): Promise<Response> {
+    const token = await this.getToken();
+    const headers: Record<string, string> = { 'X-Vault-Token': token };
+    if (this.namespace !== undefined) headers['X-Vault-Namespace'] = this.namespace;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) init.body = JSON.stringify(body);
+
+    return this.fetchImpl(`${this.url}${path}`, init);
+  }
+}

src/mcpd/src/services/secret-backends/plaintext.ts

@@ -0,0 +1,44 @@
+/**
+ * Plaintext backend driver — stores Secret.data directly in the DB column.
+ *
+ * This is the bootstrap/default backend. It always exists (seeded on startup)
+ * so the system can hold its own backends' auth credentials (e.g. OpenBao
+ * token) somewhere before the real backend is configured.
+ *
+ * The driver is deliberately almost a no-op: the service writes to and reads
+ * from `Secret.data` directly. We still route through the driver interface so
+ * the service layer can stay uniform.
+ */
+import type { SecretBackendDriver, SecretData, ExternalRef } from './types.js';
+
+export interface PlaintextDriverDeps {
+  /** Queries `prisma.secret.findMany(...)` for the `list` method (migration path). */
+  listAllPlaintext: () => Promise<Array<{ name: string; data: SecretData }>>;
+}
+
+export class PlaintextDriver implements SecretBackendDriver {
+  readonly kind = 'plaintext';
+
+  constructor(private readonly deps: PlaintextDriverDeps) {}
+
+  async read(input: { name: string; externalRef: ExternalRef; data: SecretData }): Promise<SecretData> {
+    return input.data;
+  }
+
+  async write(input: { name: string; data: SecretData }): Promise<{ externalRef: ExternalRef; storedData: SecretData }> {
+    return { externalRef: '', storedData: input.data };
+  }
+
+  async delete(_input: { name: string; externalRef: ExternalRef }): Promise<void> {
+    // The row deletion itself is the secret service's job; nothing remote to clean up here.
+  }
+
+  async list(): Promise<Array<{ name: string; externalRef: ExternalRef }>> {
+    const rows = await this.deps.listAllPlaintext();
+    return rows.map((r) => ({ name: r.name, externalRef: '' }));
+  }
+
+  async healthCheck(): Promise<{ ok: boolean; detail?: string }> {
+    return { ok: true, detail: 'plaintext backend (DB)' };
+  }
+}

src/mcpd/src/services/secret-backends/types.ts

@@ -0,0 +1,68 @@
+/**
+ * SecretBackend driver interface.
+ *
+ * The plaintext backend stores `data` in the DB column directly.
+ * Remote backends (openbao, vault, cloud KV) store an opaque `externalRef`
+ * and fetch the actual data on demand.
+ *
+ * Drivers are stateless factories keyed on a `SecretBackend` config row.
+ * Secret management (CRUD, naming) stays in the service layer; drivers
+ * handle only the storage I/O.
+ */
+
+/**
+ * Opaque reference written by a driver on `write` and read back on `read`.
+ *
+ * For the plaintext driver this is unused — the data itself lives in
+ * `Secret.data`. For openbao it's a string like `secret/data/mcpctl/mysecret`
+ * that tells the driver where to fetch on next `read`.
+ */
+export type ExternalRef = string;
+
+/** The shape of secret data — a flat map of key → value. */
+export type SecretData = Record<string, string>;
+
+export interface SecretBackendDriver {
+  /** Human-readable identifier, included in errors. */
+  readonly kind: string;
+
+  /**
+   * Read the stored secret. For plaintext this is a no-op — the data is
+   * already in the Secret row and passed in here for symmetry. For remote
+   * backends this makes the network call.
+   */
+  read(input: { name: string; externalRef: ExternalRef; data: SecretData }): Promise<SecretData>;
+
+  /**
+   * Store a new secret (or a new version of an existing one). Returns the
+   * reference (or an empty string for plaintext) + the `data` object that
+   * should be persisted on the Secret row (empty for remote backends).
+   */
+  write(input: { name: string; data: SecretData }): Promise<{ externalRef: ExternalRef; storedData: SecretData }>;
+
+  /** Remove the secret from the backend. Idempotent — missing is OK. */
+  delete(input: { name: string; externalRef: ExternalRef }): Promise<void>;
+
+  /** List everything the backend knows about. Used for migration + drift detection. */
+  list(): Promise<Array<{ name: string; externalRef: ExternalRef }>>;
+
+  /** Optional: health probe. Used by `mcpctl describe secretbackend`. */
+  healthCheck?(): Promise<{ ok: boolean; detail?: string }>;
+}
+
+/** Stored config for a SecretBackend row; dispatched on `type`. */
+export interface BackendRow {
+  id: string;
+  name: string;
+  type: string;
+  config: Record<string, unknown>;
+}
+
+/**
+ * Dependency passed to the openbao driver so it can resolve its own auth
+ * token (stored in the plaintext backend — chicken-and-egg bootstrap).
+ * Implemented by the SecretService so we don't have a circular import.
+ */
+export interface SecretRefResolver {
+  resolve(secretName: string, key: string): Promise<string>;
+}

src/mcpd/src/services/secret-migrate.service.ts

@@ -0,0 +1,113 @@
+/**
+ * Move secrets from one SecretBackend to another.
+ *
+ * Per-secret atomicity: for each secret we
+ *   1. resolve the data via the source driver,
+ *   2. write it to the destination driver,
+ *   3. update the Secret row (flip backendId + set new externalRef, clear data),
+ *   4. optionally delete from source.
+ *
+ * If the process dies between 2 and 3, the destination has an orphan entry
+ * but the row still points at the source — restart is idempotent (skips rows
+ * already on destination). We never run a batch-wide transaction because each
+ * remote driver write is a real HTTP call that can't roll back.
+ */
+import type { Secret } from '@prisma/client';
+import type { ISecretRepository } from '../repositories/interfaces.js';
+import type { SecretBackendService } from './secret-backend.service.js';
+
+export interface MigrateOptions {
+  /** Source backend name. */
+  from: string;
+  /** Destination backend name. */
+  to: string;
+  /** If provided, only migrate secrets with these names. Otherwise migrate all. */
+  names?: string[];
+  /** Leave the source copy intact after migration. Default false. */
+  keepSource?: boolean;
+}
+
+export interface MigrateResult {
+  migrated: Array<{ name: string }>;
+  skipped: Array<{ name: string; reason: string }>;
+  failed: Array<{ name: string; error: string }>;
+}
+
+export class SecretMigrateService {
+  constructor(
+    private readonly secretRepo: ISecretRepository,
+    private readonly backends: SecretBackendService,
+  ) {}
+
+  async migrate(opts: MigrateOptions): Promise<MigrateResult> {
+    const source = await this.backends.getByName(opts.from);
+    const dest = await this.backends.getByName(opts.to);
+    if (source.id === dest.id) {
+      return { migrated: [], skipped: [], failed: [{ name: '*', error: 'source and destination are the same backend' }] };
+    }
+
+    const sourceDriver = this.backends.driverFor(source);
+    const destDriver = this.backends.driverFor(dest);
+
+    let secrets = await this.secretRepo.findByBackend(source.id);
+    if (opts.names && opts.names.length > 0) {
+      const wanted = new Set(opts.names);
+      secrets = secrets.filter((s) => wanted.has(s.name));
+    }
+
+    const result: MigrateResult = { migrated: [], skipped: [], failed: [] };
+    for (const secret of secrets) {
+      try {
+        // Skip if somehow already on destination (re-run safety).
+        if (secret.backendId === dest.id) {
+          result.skipped.push({ name: secret.name, reason: 'already on destination' });
+          continue;
+        }
+
+        const data = await sourceDriver.read({
+          name: secret.name,
+          externalRef: secret.externalRef,
+          data: secret.data as Record<string, string>,
+        });
+        const written = await destDriver.write({ name: secret.name, data });
+
+        await this.secretRepo.update(secret.id, {
+          backendId: dest.id,
+          data: written.storedData,
+          externalRef: written.externalRef,
+        });
+
+        if (opts.keepSource !== true) {
+          await sourceDriver.delete({ name: secret.name, externalRef: secret.externalRef })
+            .catch((err: unknown) => {
+              // Destination is intact; best-effort source cleanup. Log + continue.
+              const msg = err instanceof Error ? err.message : String(err);
+              result.skipped.push({ name: secret.name, reason: `migrated OK; source cleanup failed: ${msg}` });
+            });
+        }
+
+        result.migrated.push({ name: secret.name });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result.failed.push({ name: secret.name, error: msg });
+      }
+    }
+
+    return result;
+  }
+
+  /** Track which secrets would be touched by a migrate run, without performing it. */
+  async dryRun(opts: MigrateOptions): Promise<Array<Secret>> {
+    const source = await this.backends.getByName(opts.from);
+    let secrets = await this.secretRepo.findByBackend(source.id);
+    if (opts.names && opts.names.length > 0) {
+      const wanted = new Set(opts.names);
+      secrets = secrets.filter((s) => wanted.has(s.name));
+    }
+    return secrets;
+  }
+}
+
+export interface SecretMigrateRouteDeps {
+  migrateService: SecretMigrateService;
+}

src/mcpd/src/services/secret.service.ts

@@ -1,10 +1,23 @@
+/**
+ * SecretService — CRUD over `Secret` rows.
+ *
+ * Dispatches storage I/O through the `SecretBackendService`: on create/update
+ * the default backend's driver writes, and the resulting {externalRef,
+ * storedData} is persisted on the row. On read (`resolveData`) the row's
+ * `backendId` selects the driver, which fetches the actual data.
+ */
 import type { Secret } from '@prisma/client';
 import type { ISecretRepository } from '../repositories/interfaces.js';
+import type { SecretBackendService } from './secret-backend.service.js';
 import { CreateSecretSchema, UpdateSecretSchema } from '../validation/secret.schema.js';
 import { NotFoundError, ConflictError } from './mcp-server.service.js';
+import type { SecretRefResolver } from './secret-backends/types.js';
 
-export class SecretService {
+export class SecretService implements SecretRefResolver {
-  constructor(private readonly repo: ISecretRepository) {}
+  constructor(
+    private readonly repo: ISecretRepository,
+    private readonly backends: SecretBackendService,
+  ) {}
 
   async list(): Promise<Secret[]> {
     return this.repo.findAll();
@@ -26,47 +39,79 @@ export class SecretService {
     return secret;
   }
 
+  /** Return the secret's actual data by dispatching through its backend driver. */
+  async resolveData(secret: Secret): Promise<Record<string, string>> {
+    const backend = await this.backends.getById(secret.backendId);
+    const driver = this.backends.driverFor(backend);
+    return driver.read({
+      name: secret.name,
+      externalRef: secret.externalRef,
+      data: secret.data as Record<string, string>,
+    });
+  }
+
+  /** Convenience: resolve {secretName, key} → string. Implements SecretRefResolver. */
+  async resolve(secretName: string, key: string): Promise<string> {
+    const secret = await this.getByName(secretName);
+    const data = await this.resolveData(secret);
+    const value = data[key];
+    if (value === undefined) {
+      throw new NotFoundError(`Secret '${secretName}' has no key '${key}'`);
+    }
+    return value;
+  }
+
   async create(input: unknown): Promise<Secret> {
     const data = CreateSecretSchema.parse(input);
-
     const existing = await this.repo.findByName(data.name);
     if (existing !== null) {
       throw new ConflictError(`Secret already exists: ${data.name}`);
     }
-
+    const backend = await this.backends.getDefault();
-    return this.repo.create(data);
+    const driver = this.backends.driverFor(backend);
+    const written = await driver.write({ name: data.name, data: data.data });
+    return this.repo.create({
+      name: data.name,
+      backendId: backend.id,
+      data: written.storedData,
+      externalRef: written.externalRef,
+    });
   }
 
   async update(id: string, input: unknown): Promise<Secret> {
     const data = UpdateSecretSchema.parse(input);
-
+    const existing = await this.getById(id);
-    // Verify exists
+    const backend = await this.backends.getById(existing.backendId);
-    await this.getById(id);
+    const driver = this.backends.driverFor(backend);
-
+    const written = await driver.write({ name: existing.name, data: data.data });
-    return this.repo.update(id, data);
+    return this.repo.update(id, {
+      data: written.storedData,
+      externalRef: written.externalRef,
+    });
   }
 
   async delete(id: string): Promise<void> {
-    // Verify exists
+    const existing = await this.getById(id);
-    await this.getById(id);
+    const backend = await this.backends.getById(existing.backendId);
+    const driver = this.backends.driverFor(backend);
+    await driver.delete({ name: existing.name, externalRef: existing.externalRef });
     await this.repo.delete(id);
   }
 
-  // ── Backup/restore helpers ──
+  // ── Backup/restore helpers (preserved) ──
 
   async upsertByName(data: Record<string, unknown>): Promise<Secret> {
     const name = data['name'] as string;
     const existing = await this.repo.findByName(name);
     if (existing !== null) {
-      const { name: _, ...updateFields } = data;
+      return this.update(existing.id, data);
-      return this.repo.update(existing.id, updateFields as Parameters<ISecretRepository['update']>[1]);
     }
-    return this.repo.create(data as Parameters<ISecretRepository['create']>[0]);
+    return this.create(data);
   }
 
   async deleteByName(name: string): Promise<void> {
     const existing = await this.repo.findByName(name);
     if (existing === null) return;
-    await this.repo.delete(existing.id);
+    await this.delete(existing.id);
   }
 }

src/mcpd/src/validation/llm.schema.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+export const LLM_TYPES = ['anthropic', 'openai', 'deepseek', 'vllm', 'ollama', 'gemini-cli'] as const;
+export const LLM_TIERS = ['fast', 'heavy'] as const;
+
+/**
+ * Reference to a key inside a Secret. `name` is the Secret resource name;
+ * `key` is the JSON key inside that secret's `data` map. mcpd resolves the
+ * pair through SecretService at inference time, so credentials never leave
+ * the server.
+ */
+export const ApiKeyRefSchema = z.object({
+  name: z.string().min(1),
+  key: z.string().min(1),
+});
+
+export const CreateLlmSchema = z.object({
+  name: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/, 'Name must be lowercase alphanumeric with hyphens'),
+  type: z.enum(LLM_TYPES),
+  model: z.string().min(1),
+  url: z.string().url().optional(),
+  tier: z.enum(LLM_TIERS).default('fast'),
+  description: z.string().max(500).default(''),
+  apiKeyRef: ApiKeyRefSchema.optional(),
+  extraConfig: z.record(z.unknown()).default({}),
+});
+
+export const UpdateLlmSchema = z.object({
+  model: z.string().min(1).optional(),
+  url: z.string().url().or(z.literal('')).optional(),
+  tier: z.enum(LLM_TIERS).optional(),
+  description: z.string().max(500).optional(),
+  apiKeyRef: ApiKeyRefSchema.nullable().optional(),
+  extraConfig: z.record(z.unknown()).optional(),
+});
+
+export type CreateLlmInput = z.infer<typeof CreateLlmSchema>;
+export type UpdateLlmInput = z.infer<typeof UpdateLlmSchema>;
+export type ApiKeyRef = z.infer<typeof ApiKeyRefSchema>;

src/mcpd/src/validation/rbac-definition.schema.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 export const RBAC_ROLES = ['edit', 'view', 'create', 'delete', 'run', 'expose'] as const;
-export const RBAC_RESOURCES = ['*', 'servers', 'instances', 'secrets', 'projects', 'templates', 'users', 'groups', 'rbac', 'prompts', 'promptrequests', 'mcptokens'] as const;
+export const RBAC_RESOURCES = ['*', 'servers', 'instances', 'secrets', 'secretbackends', 'llms', 'projects', 'templates', 'users', 'groups', 'rbac', 'prompts', 'promptrequests', 'mcptokens'] as const;
 
 /** Singular→plural map for resource names. */
 const RESOURCE_ALIASES: Record<string, string> = {
@@ -15,6 +15,8 @@ const RESOURCE_ALIASES: Record<string, string> = {
   prompt: 'prompts',
   promptrequest: 'promptrequests',
   mcptoken: 'mcptokens',
+  secretbackend: 'secretbackends',
+  llm: 'llms',
 };
 
 /** Normalize a resource name to its canonical plural form. */

src/mcpd/tests/backup.test.ts

@@ -9,6 +9,25 @@ import type { IProjectRepository } from '../src/repositories/project.repository.
 import type { IUserRepository } from '../src/repositories/user.repository.js';
 import type { IGroupRepository } from '../src/repositories/group.repository.js';
 import type { IRbacDefinitionRepository } from '../src/repositories/rbac-definition.repository.js';
+import type { SecretService } from '../src/services/secret.service.js';
+
+/**
+ * Minimal SecretService shim over a mock repo — just the `.create()` / `.update()`
+ * methods that RestoreService calls. We don't need the backend-dispatch path
+ * here since the restore happy-path tests don't exercise remote backends.
+ */
+function mockSecretService(repo: ISecretRepository): SecretService {
+  return {
+    create: vi.fn(async (input: unknown) => {
+      const data = input as { name: string; data: Record<string, string> };
+      return repo.create({ name: data.name, backendId: 'backend-plaintext', data: data.data, externalRef: '' });
+    }),
+    update: vi.fn(async (id: string, input: unknown) => {
+      const data = input as { data: Record<string, string> };
+      return repo.update(id, { data: data.data });
+    }),
+  } as unknown as SecretService;
+}
 
 // Mock data
 const mockServers = [
@@ -295,7 +314,7 @@ describe('RestoreService', () => {
     (userRepo.findByEmail as ReturnType<typeof vi.fn>).mockResolvedValue(null);
     (groupRepo.findByName as ReturnType<typeof vi.fn>).mockResolvedValue(null);
     (rbacRepo.findByName as ReturnType<typeof vi.fn>).mockResolvedValue(null);
-    restoreService = new RestoreService(serverRepo, projectRepo, secretRepo, userRepo, groupRepo, rbacRepo);
+    restoreService = new RestoreService(serverRepo, projectRepo, secretRepo, mockSecretService(secretRepo), userRepo, groupRepo, rbacRepo);
   });
 
   const validBundle = {
@@ -576,7 +595,7 @@ describe('Backup Routes', () => {
     (rGroupRepo.findByName as ReturnType<typeof vi.fn>).mockResolvedValue(null);
     const rRbacRepo = mockRbacRepo();
     (rRbacRepo.findByName as ReturnType<typeof vi.fn>).mockResolvedValue(null);
-    restoreService = new RestoreService(rSRepo, rPrRepo, rSecRepo, rUserRepo, rGroupRepo, rRbacRepo);
+    restoreService = new RestoreService(rSRepo, rPrRepo, rSecRepo, mockSecretService(rSecRepo), rUserRepo, rGroupRepo, rRbacRepo);
   });
 
   async function buildApp() {

src/mcpd/tests/env-resolver.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { resolveServerEnv } from '../src/services/env-resolver.js';
+import { resolveServerEnv, type SecretResolver } from '../src/services/env-resolver.js';
-import type { ISecretRepository } from '../src/repositories/interfaces.js';
 import type { McpServer } from '@prisma/client';
 
 function makeServer(env: unknown[]): McpServer {
@@ -23,18 +22,16 @@ function makeServer(env: unknown[]): McpServer {
   } as McpServer;
 }
 
-function mockSecretRepo(secrets: Record<string, Record<string, string>>): ISecretRepository {
+/** A SecretResolver backed by a {secretName: {key: value}} map. */
+function mockResolver(secrets: Record<string, Record<string, string>>): SecretResolver {
   return {
-    findAll: vi.fn(async () => []),
+    resolve: vi.fn(async (name: string, key: string): Promise<string> => {
-    findById: vi.fn(async () => null),
-    findByName: vi.fn(async (name: string) => {
       const data = secrets[name];
-      if (!data) return null;
+      if (!data) throw new Error(`Secret '${name}' not found`);
-      return { id: `sec-${name}`, name, data, version: 1, createdAt: new Date(), updatedAt: new Date() };
+      const value = data[key];
+      if (value === undefined) throw new Error(`Key '${key}' not found in secret '${name}'`);
+      return value;
     }),
-    create: vi.fn(async () => ({} as never)),
-    update: vi.fn(async () => ({} as never)),
-    delete: vi.fn(async () => {}),
   };
 }
 
@@ -44,8 +41,7 @@ describe('resolveServerEnv', () => {
       { name: 'FOO', value: 'bar' },
       { name: 'BAZ', value: 'qux' },
     ]);
-    const repo = mockSecretRepo({});
+    const result = await resolveServerEnv(server, mockResolver({}));
-    const result = await resolveServerEnv(server, repo);
     expect(result).toEqual({ FOO: 'bar', BAZ: 'qux' });
   });
 
@@ -53,10 +49,8 @@ describe('resolveServerEnv', () => {
     const server = makeServer([
       { name: 'TOKEN', valueFrom: { secretRef: { name: 'ha-creds', key: 'HOMEASSISTANT_TOKEN' } } },
     ]);
-    const repo = mockSecretRepo({
+    const resolver = mockResolver({ 'ha-creds': { HOMEASSISTANT_TOKEN: 'secret-token-123' } });
-      'ha-creds': { HOMEASSISTANT_TOKEN: 'secret-token-123' },
+    const result = await resolveServerEnv(server, resolver);
-    });
-    const result = await resolveServerEnv(server, repo);
     expect(result).toEqual({ TOKEN: 'secret-token-123' });
   });
 
@@ -65,48 +59,42 @@ describe('resolveServerEnv', () => {
       { name: 'URL', value: 'https://ha.local' },
       { name: 'TOKEN', valueFrom: { secretRef: { name: 'creds', key: 'TOKEN' } } },
     ]);
-    const repo = mockSecretRepo({
+    const resolver = mockResolver({ creds: { TOKEN: 'my-token' } });
-      creds: { TOKEN: 'my-token' },
+    const result = await resolveServerEnv(server, resolver);
-    });
-    const result = await resolveServerEnv(server, repo);
     expect(result).toEqual({ URL: 'https://ha.local', TOKEN: 'my-token' });
   });
 
-  it('caches secret lookups', async () => {
+  it('calls the resolver once per distinct ref', async () => {
     const server = makeServer([
       { name: 'A', valueFrom: { secretRef: { name: 'shared', key: 'KEY_A' } } },
       { name: 'B', valueFrom: { secretRef: { name: 'shared', key: 'KEY_B' } } },
     ]);
-    const repo = mockSecretRepo({
+    const resolver = mockResolver({ shared: { KEY_A: 'val-a', KEY_B: 'val-b' } });
-      shared: { KEY_A: 'val-a', KEY_B: 'val-b' },
+    const result = await resolveServerEnv(server, resolver);
-    });
-    const result = await resolveServerEnv(server, repo);
     expect(result).toEqual({ A: 'val-a', B: 'val-b' });
-    expect(repo.findByName).toHaveBeenCalledTimes(1);
+    // Resolver is called per-entry now — caching moved to the SecretService layer,
+    // which is where downstream drivers can be hit at most once per (name, key) pair.
+    expect(resolver.resolve).toHaveBeenCalledTimes(2);
   });
 
   it('throws when secret not found', async () => {
     const server = makeServer([
       { name: 'TOKEN', valueFrom: { secretRef: { name: 'missing', key: 'TOKEN' } } },
     ]);
-    const repo = mockSecretRepo({});
+    await expect(resolveServerEnv(server, mockResolver({}))).rejects.toThrow(/Secret 'missing' not found/);
-    await expect(resolveServerEnv(server, repo)).rejects.toThrow("Secret 'missing' not found");
   });
 
   it('throws when secret key not found', async () => {
     const server = makeServer([
       { name: 'TOKEN', valueFrom: { secretRef: { name: 'creds', key: 'NONEXISTENT' } } },
     ]);
-    const repo = mockSecretRepo({
+    const resolver = mockResolver({ creds: { OTHER_KEY: 'val' } });
-      creds: { OTHER_KEY: 'val' },
+    await expect(resolveServerEnv(server, resolver)).rejects.toThrow(/Key 'NONEXISTENT' not found/);
-    });
-    await expect(resolveServerEnv(server, repo)).rejects.toThrow("Key 'NONEXISTENT' not found in secret 'creds'");
   });
 
   it('returns empty map for empty env', async () => {
     const server = makeServer([]);
-    const repo = mockSecretRepo({});
+    const result = await resolveServerEnv(server, mockResolver({}));
-    const result = await resolveServerEnv(server, repo);
     expect(result).toEqual({});
   });
 });

src/mcpd/tests/llm-routes.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyInstance } from 'fastify';
+import { registerLlmRoutes } from '../src/routes/llms.js';
+import { LlmService } from '../src/services/llm.service.js';
+import { errorHandler } from '../src/middleware/error-handler.js';
+import type { ILlmRepository } from '../src/repositories/llm.repository.js';
+import type { Llm, Secret } from '@prisma/client';
+
+let app: FastifyInstance;
+
+function makeLlm(overrides: Partial<Llm> = {}): Llm {
+  return {
+    id: 'llm-1',
+    name: 'claude',
+    type: 'anthropic',
+    model: 'claude-3-5-sonnet-20241022',
+    url: '',
+    tier: 'heavy',
+    description: '',
+    apiKeySecretId: null,
+    apiKeySecretKey: null,
+    extraConfig: {},
+    version: 1,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function mockRepo(initial: Llm[] = []): ILlmRepository {
+  const rows = new Map(initial.map((r) => [r.id, r]));
+  return {
+    findAll: vi.fn(async () => [...rows.values()]),
+    findById: vi.fn(async (id: string) => rows.get(id) ?? null),
+    findByName: vi.fn(async (name: string) => {
+      for (const r of rows.values()) if (r.name === name) return r;
+      return null;
+    }),
+    findByTier: vi.fn(async () => []),
+    create: vi.fn(async (data) => {
+      const row = makeLlm({ id: 'new-id', name: data.name, type: data.type, model: data.model });
+      rows.set(row.id, row);
+      return row;
+    }),
+    update: vi.fn(async (id, data) => {
+      const existing = rows.get(id)!;
+      const next: Llm = {
+        ...existing,
+        ...(data.model !== undefined ? { model: data.model } : {}),
+      };
+      rows.set(id, next);
+      return next;
+    }),
+    delete: vi.fn(async (id) => { rows.delete(id); }),
+  };
+}
+
+function mockSecretService() {
+  const sec: Secret = {
+    id: 'sec-1', name: 'anthropic-key', backendId: 'b', data: {}, externalRef: '',
+    version: 1, createdAt: new Date(), updatedAt: new Date(),
+  };
+  return {
+    getById: vi.fn(async (id: string) => {
+      if (id === sec.id) return sec;
+      throw new Error('not found');
+    }),
+    getByName: vi.fn(async (name: string) => {
+      if (name === sec.name) return sec;
+      throw new Error('not found');
+    }),
+    resolveData: vi.fn(async () => ({ token: 'sk-ant-xyz' })),
+  };
+}
+
+afterEach(async () => {
+  if (app) await app.close();
+});
+
+async function createApp(repo: ILlmRepository): Promise<FastifyInstance> {
+  app = Fastify({ logger: false });
+  app.setErrorHandler(errorHandler);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const service = new LlmService(repo, mockSecretService() as any);
+  registerLlmRoutes(app, service);
+  await app.ready();
+  return app;
+}
+
+describe('Llm Routes', () => {
+  it('GET /api/v1/llms returns a list', async () => {
+    await createApp(mockRepo([makeLlm()]));
+    const res = await app.inject({ method: 'GET', url: '/api/v1/llms' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json<Array<{ name: string }>>();
+    expect(body).toHaveLength(1);
+    expect(body[0]!.name).toBe('claude');
+  });
+
+  it('GET /api/v1/llms/:id returns 404 when missing', async () => {
+    await createApp(mockRepo());
+    const res = await app.inject({ method: 'GET', url: '/api/v1/llms/missing' });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('POST /api/v1/llms creates and returns 201', async () => {
+    await createApp(mockRepo());
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/llms',
+      payload: {
+        name: 'ollama-local',
+        type: 'ollama',
+        model: 'llama3',
+        url: 'http://localhost:11434',
+      },
+    });
+    expect(res.statusCode).toBe(201);
+    expect(res.json<{ name: string }>().name).toBe('ollama-local');
+  });
+
+  it('POST /api/v1/llms rejects bad input with 400', async () => {
+    await createApp(mockRepo());
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/llms',
+      payload: { name: '', type: 'anthropic', model: 'x' },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('POST /api/v1/llms returns 409 when name exists', async () => {
+    await createApp(mockRepo([makeLlm({ name: 'claude' })]));
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/llms',
+      payload: { name: 'claude', type: 'anthropic', model: 'x' },
+    });
+    expect(res.statusCode).toBe(409);
+  });
+
+  it('PUT /api/v1/llms/:id updates model', async () => {
+    await createApp(mockRepo([makeLlm({ id: 'llm-1' })]));
+    const res = await app.inject({
+      method: 'PUT',
+      url: '/api/v1/llms/llm-1',
+      payload: { model: 'claude-3-opus' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json<{ model: string }>().model).toBe('claude-3-opus');
+  });
+
+  it('PUT /api/v1/llms/:id returns 404 when missing', async () => {
+    await createApp(mockRepo());
+    const res = await app.inject({
+      method: 'PUT',
+      url: '/api/v1/llms/missing',
+      payload: { model: 'x' },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('DELETE /api/v1/llms/:id returns 204', async () => {
+    await createApp(mockRepo([makeLlm({ id: 'llm-1' })]));
+    const res = await app.inject({ method: 'DELETE', url: '/api/v1/llms/llm-1' });
+    expect(res.statusCode).toBe(204);
+  });
+
+  it('DELETE /api/v1/llms/:id returns 404 when missing', async () => {
+    await createApp(mockRepo());
+    const res = await app.inject({ method: 'DELETE', url: '/api/v1/llms/missing' });
+    expect(res.statusCode).toBe(404);
+  });
+});

src/mcpd/tests/llm-service.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, vi } from 'vitest';
+import { LlmService } from '../src/services/llm.service.js';
+import type { ILlmRepository } from '../src/repositories/llm.repository.js';
+import type { Llm, Secret } from '@prisma/client';
+
+function makeLlm(overrides: Partial<Llm> = {}): Llm {
+  return {
+    id: 'llm-1',
+    name: 'claude',
+    type: 'anthropic',
+    model: 'claude-3-5-sonnet-20241022',
+    url: '',
+    tier: 'heavy',
+    description: '',
+    apiKeySecretId: null,
+    apiKeySecretKey: null,
+    extraConfig: {},
+    version: 1,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function makeSecret(overrides: Partial<Secret> = {}): Secret {
+  return {
+    id: 'sec-anthropic',
+    name: 'anthropic-key',
+    backendId: 'backend-plaintext',
+    data: {},
+    externalRef: '',
+    version: 1,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function mockRepo(initial: Llm[] = []): ILlmRepository {
+  const rows = new Map<string, Llm>(initial.map((r) => [r.id, r]));
+  return {
+    findAll: vi.fn(async () => [...rows.values()]),
+    findById: vi.fn(async (id: string) => rows.get(id) ?? null),
+    findByName: vi.fn(async (name: string) => {
+      for (const r of rows.values()) if (r.name === name) return r;
+      return null;
+    }),
+    findByTier: vi.fn(async (tier: string) => [...rows.values()].filter((r) => r.tier === tier)),
+    create: vi.fn(async (data) => {
+      const row = makeLlm({
+        id: `llm-${String(rows.size + 1)}`,
+        name: data.name,
+        type: data.type,
+        model: data.model,
+        url: data.url ?? '',
+        tier: data.tier ?? 'fast',
+        description: data.description ?? '',
+        apiKeySecretId: data.apiKeySecretId ?? null,
+        apiKeySecretKey: data.apiKeySecretKey ?? null,
+        extraConfig: (data.extraConfig ?? {}) as Llm['extraConfig'],
+      });
+      rows.set(row.id, row);
+      return row;
+    }),
+    update: vi.fn(async (id, data) => {
+      const existing = rows.get(id);
+      if (!existing) throw new Error('not found');
+      const next: Llm = {
+        ...existing,
+        ...(data.model !== undefined ? { model: data.model } : {}),
+        ...(data.url !== undefined ? { url: data.url } : {}),
+        ...(data.tier !== undefined ? { tier: data.tier } : {}),
+        ...(data.description !== undefined ? { description: data.description } : {}),
+        ...(data.apiKeySecretId !== undefined ? { apiKeySecretId: data.apiKeySecretId } : {}),
+        ...(data.apiKeySecretKey !== undefined ? { apiKeySecretKey: data.apiKeySecretKey } : {}),
+        ...(data.extraConfig !== undefined ? { extraConfig: data.extraConfig as Llm['extraConfig'] } : {}),
+      };
+      rows.set(id, next);
+      return next;
+    }),
+    delete: vi.fn(async (id) => { rows.delete(id); }),
+  };
+}
+
+function mockSecrets(secretByName: Record<string, Secret>, resolved: Record<string, string> = {}): {
+  getById: ReturnType<typeof vi.fn>;
+  getByName: ReturnType<typeof vi.fn>;
+  resolveData: ReturnType<typeof vi.fn>;
+} {
+  return {
+    getById: vi.fn(async (id: string) => {
+      for (const s of Object.values(secretByName)) if (s.id === id) return s;
+      throw new Error(`secret not found: ${id}`);
+    }),
+    getByName: vi.fn(async (name: string) => {
+      const s = secretByName[name];
+      if (!s) throw new Error(`secret not found: ${name}`);
+      return s;
+    }),
+    resolveData: vi.fn(async () => resolved),
+  };
+}
+
+describe('LlmService', () => {
+  it('create parses input and resolves apiKeyRef → secret id', async () => {
+    const repo = mockRepo();
+    const sec = makeSecret();
+    const secrets = mockSecrets({ 'anthropic-key': sec });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, secrets as any);
+
+    const view = await svc.create({
+      name: 'claude',
+      type: 'anthropic',
+      model: 'claude-3-5-sonnet-20241022',
+      tier: 'heavy',
+      apiKeyRef: { name: 'anthropic-key', key: 'token' },
+    });
+
+    expect(view.name).toBe('claude');
+    expect(view.apiKeyRef).toEqual({ name: 'anthropic-key', key: 'token' });
+    expect(secrets.getByName).toHaveBeenCalledWith('anthropic-key');
+    expect(repo.create).toHaveBeenCalledWith(expect.objectContaining({
+      apiKeySecretId: sec.id,
+      apiKeySecretKey: 'token',
+    }));
+  });
+
+  it('create without apiKeyRef leaves FK columns null', async () => {
+    const repo = mockRepo();
+    const secrets = mockSecrets({});
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, secrets as any);
+
+    const view = await svc.create({
+      name: 'ollama-local',
+      type: 'ollama',
+      model: 'llama3',
+      url: 'http://localhost:11434',
+      tier: 'fast',
+    });
+
+    expect(view.apiKeyRef).toBeNull();
+    expect(secrets.getByName).not.toHaveBeenCalled();
+  });
+
+  it('create rejects duplicate name', async () => {
+    const repo = mockRepo([makeLlm({ name: 'claude' })]);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, mockSecrets({}) as any);
+    await expect(svc.create({
+      name: 'claude', type: 'anthropic', model: 'x',
+    })).rejects.toThrow(/already exists/);
+  });
+
+  it('update with apiKeyRef null unlinks the secret', async () => {
+    const sec = makeSecret();
+    const repo = mockRepo([makeLlm({ apiKeySecretId: sec.id, apiKeySecretKey: 'token' })]);
+    const secrets = mockSecrets({ 'anthropic-key': sec });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, secrets as any);
+
+    await svc.update('llm-1', { apiKeyRef: null });
+    expect(repo.update).toHaveBeenCalledWith('llm-1', expect.objectContaining({
+      apiKeySecretId: null,
+      apiKeySecretKey: null,
+    }));
+  });
+
+  it('resolveApiKey reads through SecretService', async () => {
+    const sec = makeSecret();
+    const repo = mockRepo([makeLlm({ apiKeySecretId: sec.id, apiKeySecretKey: 'token' })]);
+    const secrets = mockSecrets({ 'anthropic-key': sec }, { token: 'sk-ant-xyz' });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, secrets as any);
+
+    const key = await svc.resolveApiKey('claude');
+    expect(key).toBe('sk-ant-xyz');
+  });
+
+  it('resolveApiKey throws when Llm has no apiKeyRef', async () => {
+    const repo = mockRepo([makeLlm()]);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, mockSecrets({}) as any);
+    await expect(svc.resolveApiKey('claude')).rejects.toThrow(/no apiKeyRef/);
+  });
+
+  it('resolveApiKey throws when the secret key is missing', async () => {
+    const sec = makeSecret();
+    const repo = mockRepo([makeLlm({ apiKeySecretId: sec.id, apiKeySecretKey: 'missing-key' })]);
+    const secrets = mockSecrets({ 'anthropic-key': sec }, { token: 'x' });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, secrets as any);
+    await expect(svc.resolveApiKey('claude')).rejects.toThrow(/no key 'missing-key'/);
+  });
+
+  it('list returns views with apiKeyRef rendered from secret name', async () => {
+    const sec = makeSecret();
+    const repo = mockRepo([makeLlm({ apiKeySecretId: sec.id, apiKeySecretKey: 'token' })]);
+    const secrets = mockSecrets({ 'anthropic-key': sec });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, secrets as any);
+
+    const items = await svc.list();
+    expect(items).toHaveLength(1);
+    expect(items[0]!.apiKeyRef).toEqual({ name: 'anthropic-key', key: 'token' });
+  });
+
+  it('delete happy path', async () => {
+    const repo = mockRepo([makeLlm()]);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, mockSecrets({}) as any);
+    await svc.delete('llm-1');
+    expect(repo.delete).toHaveBeenCalledWith('llm-1');
+  });
+
+  it('validation: rejects invalid type', async () => {
+    const repo = mockRepo();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, mockSecrets({}) as any);
+    await expect(svc.create({ name: 'x', type: 'bogus', model: 'y' })).rejects.toThrow();
+  });
+
+  it('validation: rejects invalid tier', async () => {
+    const repo = mockRepo();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const svc = new LlmService(repo, mockSecrets({}) as any);
+    await expect(svc.create({
+      name: 'x', type: 'openai', model: 'gpt-4', tier: 'warp-speed',
+    })).rejects.toThrow();
+  });
+});

src/mcpd/tests/secret-backends.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PlaintextDriver } from '../src/services/secret-backends/plaintext.js';
+import { OpenBaoDriver } from '../src/services/secret-backends/openbao.js';
+
+describe('PlaintextDriver', () => {
+  const driver = new PlaintextDriver({ listAllPlaintext: async () => [{ name: 'a', data: { k: 'v' } }] });
+
+  it('read returns the data passed in', async () => {
+    const result = await driver.read({ name: 's', externalRef: '', data: { token: 'abc' } });
+    expect(result).toEqual({ token: 'abc' });
+  });
+
+  it('write returns storedData = input, externalRef = empty', async () => {
+    const result = await driver.write({ name: 's', data: { k: 'v' } });
+    expect(result).toEqual({ externalRef: '', storedData: { k: 'v' } });
+  });
+
+  it('list delegates to the injected dep', async () => {
+    const list = await driver.list();
+    expect(list).toEqual([{ name: 'a', externalRef: '' }]);
+  });
+
+  it('delete is a no-op', async () => {
+    await expect(driver.delete({ name: 's', externalRef: '' })).resolves.toBeUndefined();
+  });
+});
+
+describe('OpenBaoDriver', () => {
+  function makeFetch(responses: Array<{ url: RegExp; status: number; body?: unknown }>): ReturnType<typeof vi.fn> {
+    return vi.fn(async (url: string | URL, _init?: RequestInit) => {
+      const urlStr = String(url);
+      const match = responses.find((r) => r.url.test(urlStr));
+      if (!match) throw new Error(`unexpected fetch: ${urlStr}`);
+      return new Response(match.body ? JSON.stringify(match.body) : '', { status: match.status });
+    });
+  }
+
+  const resolver = { resolve: vi.fn(async () => 'test-vault-token') };
+
+  it('write sends POST to .../data/<path> with {data: ...}', async () => {
+    const fetchFn = makeFetch([{ url: /\/v1\/secret\/data\/mcpctl\/mytoken$/, status: 200 }]);
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: resolver },
+    );
+    const result = await driver.write({ name: 'mytoken', data: { api_key: 'secret-xyz' } });
+    expect(result.externalRef).toBe('secret/mcpctl/mytoken');
+    expect(result.storedData).toEqual({});
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    const [, init] = fetchFn.mock.calls[0] as [unknown, RequestInit];
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body as string)).toEqual({ data: { api_key: 'secret-xyz' } });
+    const headers = init.headers as Record<string, string>;
+    expect(headers['X-Vault-Token']).toBe('test-vault-token');
+  });
+
+  it('read returns body.data.data', async () => {
+    const fetchFn = makeFetch([{
+      url: /\/v1\/secret\/data\/mcpctl\/mytoken$/,
+      status: 200,
+      body: { data: { data: { api_key: 'secret-xyz' } } },
+    }]);
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: resolver },
+    );
+    const result = await driver.read({ name: 'mytoken', externalRef: 'secret/mcpctl/mytoken', data: {} });
+    expect(result).toEqual({ api_key: 'secret-xyz' });
+  });
+
+  it('read throws when the path 404s', async () => {
+    const fetchFn = makeFetch([{ url: /\/data\//, status: 404 }]);
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: resolver },
+    );
+    await expect(driver.read({ name: 'missing', externalRef: '', data: {} })).rejects.toThrow(/not found/);
+  });
+
+  it('delete swallows 404', async () => {
+    const fetchFn = makeFetch([{ url: /\/metadata\//, status: 404 }]);
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: resolver },
+    );
+    await expect(driver.delete({ name: 'gone', externalRef: '' })).resolves.toBeUndefined();
+  });
+
+  it('list returns names from the metadata LIST call', async () => {
+    const fetchFn = makeFetch([{
+      url: /\/v1\/secret\/metadata\/mcpctl\/$/,
+      status: 200,
+      body: { data: { keys: ['token1', 'token2', 'sub-folder/'] } },
+    }]);
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: resolver },
+    );
+    const result = await driver.list();
+    // Sub-folders (trailing slash) are excluded; only leaf keys are returned.
+    expect(result).toEqual([
+      { name: 'token1', externalRef: 'secret/mcpctl/token1' },
+      { name: 'token2', externalRef: 'secret/mcpctl/token2' },
+    ]);
+  });
+
+  it('caches the vault token after first resolve', async () => {
+    const fetchFn = makeFetch([
+      { url: /\/v1\/secret\/data\/mcpctl\//, status: 200, body: { data: { data: { k: 'v' } } } },
+    ]);
+    const singleResolver = { resolve: vi.fn(async () => 'test-vault-token') };
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: singleResolver },
+    );
+    await driver.read({ name: 'a', externalRef: '', data: {} });
+    await driver.read({ name: 'a', externalRef: '', data: {} });
+    expect(singleResolver.resolve).toHaveBeenCalledTimes(1);
+  });
+
+  it('propagates X-Vault-Namespace when configured', async () => {
+    const fetchFn = makeFetch([{ url: /\/v1\/secret\/data\/mcpctl\//, status: 200 }]);
+    const driver = new OpenBaoDriver(
+      { url: 'http://bao.example:8200', namespace: 'myteam', tokenSecretRef: { name: 'bao', key: 'token' } },
+      { fetch: fetchFn as unknown as typeof fetch, secretRefResolver: resolver },
+    );
+    await driver.write({ name: 'x', data: { k: 'v' } });
+    const [, init] = fetchFn.mock.calls[0] as [unknown, RequestInit];
+    const headers = init.headers as Record<string, string>;
+    expect(headers['X-Vault-Namespace']).toBe('myteam');
+  });
+});

src/mcpd/tests/secret-routes.test.ts

@@ -3,43 +3,68 @@ import Fastify from 'fastify';
 import type { FastifyInstance } from 'fastify';
 import { registerSecretRoutes } from '../src/routes/secrets.js';
 import { SecretService } from '../src/services/secret.service.js';
+import { SecretBackendService } from '../src/services/secret-backend.service.js';
 import { errorHandler } from '../src/middleware/error-handler.js';
 import type { ISecretRepository } from '../src/repositories/interfaces.js';
+import type { ISecretBackendRepository } from '../src/repositories/secret-backend.repository.js';
+import type { SecretBackend } from '@prisma/client';
 
 let app: FastifyInstance;
 
-function mockRepo(): ISecretRepository {
+const PLAINTEXT_BACKEND: SecretBackend = {
-  let lastCreated: Record<string, unknown> | null = null;
+  id: 'backend-plaintext',
-  return {
+  name: 'default',
-    findAll: vi.fn(async () => [
+  type: 'plaintext',
-      { id: '1', name: 'ha-creds', data: { TOKEN: 'abc' }, version: 1, createdAt: new Date(), updatedAt: new Date() },
+  config: {},
-    ]),
+  isDefault: true,
-    findById: vi.fn(async (id: string) => {
+  description: '',
-      if (lastCreated && (lastCreated as { id: string }).id === id) return lastCreated as never;
-      return null;
-    }),
-    findByName: vi.fn(async () => null),
-    create: vi.fn(async (data) => {
-      const secret = {
-        id: 'new-id',
-        name: data.name,
-        data: data.data ?? {},
   version: 1,
   createdAt: new Date(),
   updatedAt: new Date(),
 };
+
+function makeSecret(overrides: Partial<{ id: string; name: string; data: Record<string, string>; externalRef: string; backendId: string }> = {}) {
+  return {
+    id: overrides.id ?? 'sec-1',
+    name: overrides.name ?? 'ha-creds',
+    backendId: overrides.backendId ?? PLAINTEXT_BACKEND.id,
+    data: overrides.data ?? { TOKEN: 'abc' },
+    externalRef: overrides.externalRef ?? '',
+    version: 1,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function mockRepo(): ISecretRepository {
+  let lastCreated: ReturnType<typeof makeSecret> | null = null;
+  return {
+    findAll: vi.fn(async () => [makeSecret()]),
+    findById: vi.fn(async (id: string) => {
+      if (lastCreated && lastCreated.id === id) return lastCreated;
+      return null;
+    }),
+    findByName: vi.fn(async () => null),
+    findByBackend: vi.fn(async () => []),
+    create: vi.fn(async (data) => {
+      const secret = makeSecret({
+        id: 'new-id',
+        name: data.name,
+        data: data.data ?? {},
+        externalRef: data.externalRef ?? '',
+        backendId: data.backendId,
+      });
       lastCreated = secret;
       return secret;
     }),
     update: vi.fn(async (id, data) => {
-      const secret = {
+      const secret = makeSecret({
         id,
-        name: 'ha-creds',
+        name: lastCreated?.name ?? 'ha-creds',
         data: data.data,
-        version: 2,
+        externalRef: data.externalRef,
-        createdAt: new Date(),
+        backendId: data.backendId ?? PLAINTEXT_BACKEND.id,
-        updatedAt: new Date(),
+      });
-      };
       lastCreated = secret;
       return secret;
     }),
@@ -47,14 +72,32 @@ function mockRepo(): ISecretRepository {
   };
 }
 
+function mockBackendRepo(): ISecretBackendRepository {
+  return {
+    findAll: vi.fn(async () => [PLAINTEXT_BACKEND]),
+    findById: vi.fn(async (id) => (id === PLAINTEXT_BACKEND.id ? PLAINTEXT_BACKEND : null)),
+    findByName: vi.fn(async (name) => (name === PLAINTEXT_BACKEND.name ? PLAINTEXT_BACKEND : null)),
+    findDefault: vi.fn(async () => PLAINTEXT_BACKEND),
+    create: vi.fn(async () => PLAINTEXT_BACKEND),
+    update: vi.fn(async () => PLAINTEXT_BACKEND),
+    setAsDefault: vi.fn(async () => PLAINTEXT_BACKEND),
+    delete: vi.fn(async () => {}),
+    countReferencingSecrets: vi.fn(async () => 0),
+  };
+}
+
 afterEach(async () => {
   if (app) await app.close();
 });
 
-function createApp(repo: ISecretRepository) {
+async function createApp(repo: ISecretRepository) {
   app = Fastify({ logger: false });
   app.setErrorHandler(errorHandler);
-  const service = new SecretService(repo);
+  const backends = new SecretBackendService(mockBackendRepo(), {
+    plaintext: { listAllPlaintext: async () => [] },
+    secretRefResolver: { resolve: async () => '' },
+  });
+  const service = new SecretService(repo, backends);
   registerSecretRoutes(app, service);
   return app.ready();
 }
@@ -129,7 +172,7 @@ describe('Secret Routes', () => {
   describe('PUT /api/v1/secrets/:id', () => {
     it('updates a secret', async () => {
       const repo = mockRepo();
-      vi.mocked(repo.findById).mockResolvedValue({ id: '1', name: 'ha-creds' } as never);
+      vi.mocked(repo.findById).mockResolvedValue(makeSecret({ id: '1' }) as never);
       await createApp(repo);
       const res = await app.inject({
         method: 'PUT',
@@ -154,7 +197,7 @@ describe('Secret Routes', () => {
   describe('DELETE /api/v1/secrets/:id', () => {
     it('deletes a secret and returns 204', async () => {
       const repo = mockRepo();
-      vi.mocked(repo.findById).mockResolvedValue({ id: '1', name: 'ha-creds' } as never);
+      vi.mocked(repo.findById).mockResolvedValue(makeSecret({ id: '1' }) as never);
       await createApp(repo);
       const res = await app.inject({ method: 'DELETE', url: '/api/v1/secrets/1' });
       expect(res.statusCode).toBe(204);

src/mcplocal/src/audit/collector.ts

@@ -41,11 +41,6 @@ export class AuditCollector {
     this.sessionPrincipals.set(sessionId, { ...existing, tokenName: token.tokenName, tokenSha: token.tokenSha });
   }
 
-  /** Look up the McpToken SHA for a session. Returns undefined for non-HTTP-mode sessions. */
-  getSessionMcpTokenSha(sessionId: string): string | undefined {
-    return this.sessionPrincipals.get(sessionId)?.tokenSha;
-  }
-
   /** Queue an audit event. Auto-fills projectName, userName, tokenName, and tokenSha. */
   emit(event: Omit<AuditEvent, 'projectName'>): void {
     const enriched: AuditEvent = { ...event, projectName: this.projectName };

src/mcplocal/src/gate/session-gate.ts

@@ -3,21 +3,6 @@
  *
  * Tracks whether a session has gone through the prompt selection flow.
  * When gated, only begin_session is accessible. After ungating, all tools work.
- *
- * Per-token ungate cache:
- * When the caller authenticated via an `McpToken` (HTTP-mode service agent),
- * we also remember the ungate keyed on the token's SHA. Subsequent sessions
- * from the same token automatically start ungated for a TTL window.
- *
- * Why: LiteLLM and similar MCP-proxying clients don't preserve the
- * `mcp-session-id` header across chat completion calls, so every tool call
- * lands on a fresh upstream session — which would otherwise be gated anew,
- * forcing the agent into a begin_session loop. Keying on the token (which IS
- * preserved, because it's in the Authorization header) gives us a stable
- * identity that survives stateless proxies.
- *
- * Claude Code's stdio path keeps its session-id, so this code is a no-op for
- * that case (session-id ungate still applies, token ungate is purely additive).
  */
 
 import type { PromptIndexEntry, TagMatchResult } from './tag-matcher.js';
@@ -29,37 +14,15 @@ export interface SessionState {
   briefing: string | null;
 }
 
-interface TokenUngateEntry {
-  tokenSha: string;
-  tags: string[];
-  ungatedAt: number;
-  retrievedPrompts: Set<string>;
-}
-
-/** Default TTL for per-token ungate cache (1 hour). Tunable via env for testing. */
-const DEFAULT_TOKEN_UNGATE_TTL_MS = Number(process.env['MCPLOCAL_TOKEN_UNGATE_TTL_MS']) || 60 * 60 * 1000;
-
 export class SessionGate {
   private sessions = new Map<string, SessionState>();
-  private tokenUngates = new Map<string, TokenUngateEntry>();
-  private readonly tokenUngateTtlMs: number;
 
-  constructor(tokenUngateTtlMs = DEFAULT_TOKEN_UNGATE_TTL_MS) {
+  /** Create a new session. Starts gated if the project is gated. */
-    this.tokenUngateTtlMs = tokenUngateTtlMs;
+  createSession(sessionId: string, projectGated: boolean): void {
-  }
-
-  /**
-   * Create a new session. Starts gated if the project is gated, UNLESS the
-   * caller's McpToken already ungated within the last TTL window — in which
-   * case the session inherits the previous tags + retrievedPrompts so the
-   * agent doesn't get the full gated greeting on every fresh session.
-   */
-  createSession(sessionId: string, projectGated: boolean, tokenSha?: string): void {
-    const priorEntry = tokenSha ? this.getActiveTokenEntry(tokenSha) : null;
     this.sessions.set(sessionId, {
-      gated: projectGated && priorEntry === null,
+      gated: projectGated,
-      tags: priorEntry ? [...priorEntry.tags] : [],
+      tags: [],
-      retrievedPrompts: priorEntry ? new Set(priorEntry.retrievedPrompts) : new Set(),
+      retrievedPrompts: new Set(),
       briefing: null,
     });
   }
@@ -74,37 +37,18 @@ export class SessionGate {
     return this.sessions.get(sessionId)?.gated ?? false;
   }
 
-  /** True when a token has an active (non-expired) ungate entry. */
+  /** Ungate a session after prompt selection is complete. */
-  isTokenUngated(tokenSha: string): boolean {
+  ungate(sessionId: string, tags: string[], matchResult: TagMatchResult): void {
-    return this.getActiveTokenEntry(tokenSha) !== null;
-  }
-
-  /**
-   * Ungate a session after prompt selection is complete.
-   *
-   * When `tokenSha` is supplied, also remember the ungate keyed on the token
-   * so future sessions from the same token start ungated (survives proxies
-   * that drop `mcp-session-id`).
-   */
-  ungate(sessionId: string, tags: string[], matchResult: TagMatchResult, tokenSha?: string): void {
     const session = this.sessions.get(sessionId);
     if (!session) return;
 
     session.gated = false;
     session.tags = [...session.tags, ...tags];
 
+    // Track which prompts have been sent
     for (const p of matchResult.fullContent) {
       session.retrievedPrompts.add(p.name);
     }
-
-    if (tokenSha !== undefined && tokenSha !== '') {
-      this.tokenUngates.set(tokenSha, {
-        tokenSha,
-        tags: [...session.tags],
-        ungatedAt: Date.now(),
-        retrievedPrompts: new Set(session.retrievedPrompts),
-      });
-    }
   }
 
   /** Record additional prompts retrieved via read_prompts. */
@@ -129,19 +73,4 @@ export class SessionGate {
   removeSession(sessionId: string): void {
     this.sessions.delete(sessionId);
   }
-
-  /** Forget a token's ungate entry (e.g. on revocation signal). */
-  revokeToken(tokenSha: string): void {
-    this.tokenUngates.delete(tokenSha);
-  }
-
-  private getActiveTokenEntry(tokenSha: string): TokenUngateEntry | null {
-    const entry = this.tokenUngates.get(tokenSha);
-    if (!entry) return null;
-    if (Date.now() - entry.ungatedAt > this.tokenUngateTtlMs) {
-      this.tokenUngates.delete(tokenSha);
-      return null;
-    }
-    return entry;
-  }
 }

src/mcplocal/src/proxymodel/plugin-context.ts

@@ -25,13 +25,6 @@ export interface PluginContextDeps {
   queueNotification: (notification: JsonRpcNotification) => void;
   postToMcpd: (path: string, body: Record<string, unknown>) => Promise<unknown>;
   auditCollector?: AuditCollector;
-  /**
-   * Resolves the principal's McpToken SHA for this session, if the caller
-   * authenticated via an McpToken. Called lazily so the value reflects the
-   * session's current state even when the token is attached after the plugin
-   * context is created.
-   */
-  getMcpTokenSha?: () => string | undefined;
 }
 
 /**
@@ -62,11 +55,6 @@ export class PluginContextImpl implements PluginSessionContext {
     this.deps = deps;
   }
 
-  /** McpToken SHA for the current caller, or undefined for STDIO/session-auth callers. */
-  getMcpTokenSha(): string | undefined {
-    return this.deps.getMcpTokenSha?.();
-  }
-
   registerTool(tool: ToolDefinition, handler: VirtualToolHandler): void {
     this.virtualTools.set(tool.name, { definition: tool, handler });
   }

src/mcplocal/src/proxymodel/plugin.ts

@@ -50,14 +50,6 @@ export interface PluginSessionContext {
 
   // Audit event emission (auto-fills sessionId and projectName)
   emitAuditEvent(event: Omit<AuditEvent, 'sessionId' | 'projectName'>): void;
-
-  /**
-   * McpToken SHA for the current caller, or undefined if the session was
-   * authenticated via a User session (STDIO/Claude Code path). Plugins can use
-   * this to key state on the token principal rather than the session-id —
-   * useful when the session-id doesn't survive a proxy (e.g. LiteLLM).
-   */
-  getMcpTokenSha(): string | undefined;
 }
 
 // ── Virtual Server ──────────────────────────────────────────────────

src/mcplocal/src/proxymodel/plugins/gate.ts

@@ -40,11 +40,7 @@ export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugi
     description: 'Gated session flow: begin_session → prompt selection → ungate.',
 
     async onSessionCreate(ctx) {
-      // Pass the caller's McpToken SHA so the gate can honor a cross-session
+      sessionGate.createSession(ctx.sessionId, isGated);
-      // ungate cache keyed on the token principal. Fixes the LiteLLM case where
-      // each tool call lands on a fresh mcp-session-id → would otherwise loop
-      // on begin_session forever.
-      sessionGate.createSession(ctx.sessionId, isGated, ctx.getMcpTokenSha());
 
       // Register begin_session virtual tool
       ctx.registerTool(getBeginSessionTool(llmSelector), async (args, callCtx) => {
@@ -268,9 +264,8 @@ async function handleBeginSession(
     matchResult = tagMatcher.match(tags, promptIndex);
   }
 
-  // Ungate the session (and remember the ungate per McpToken if this is a
+  // Ungate the session
-  // service-token request, so the next session from the same token skips the gate).
+  sessionGate.ungate(ctx.sessionId, tags, matchResult);
-  sessionGate.ungate(ctx.sessionId, tags, matchResult, ctx.getMcpTokenSha());
   ctx.queueNotification('notifications/tools/list_changed');
 
   // Audit: gate_decision for begin_session
@@ -456,8 +451,8 @@ async function handleGatedIntercept(
     const promptIndex = await ctx.fetchPromptIndex();
     const matchResult = tagMatcher.match(tags, promptIndex);
 
-    // Ungate the session (and remember per-token if the caller is a McpToken).
+    // Ungate the session
-    sessionGate.ungate(ctx.sessionId, tags, matchResult, ctx.getMcpTokenSha());
+    sessionGate.ungate(ctx.sessionId, tags, matchResult);
     ctx.queueNotification('notifications/tools/list_changed');
 
     // Audit: gate_decision for auto-intercept
@@ -527,7 +522,7 @@ async function handleGatedIntercept(
     return response;
   } catch {
     // If prompt retrieval fails, just ungate and route normally
-    sessionGate.ungate(ctx.sessionId, tags, { fullContent: [], indexOnly: [], remaining: [] }, ctx.getMcpTokenSha());
+    sessionGate.ungate(ctx.sessionId, tags, { fullContent: [], indexOnly: [], remaining: [] });
     ctx.queueNotification('notifications/tools/list_changed');
     return ctx.routeToUpstream(request);
   }

src/mcplocal/src/router.ts

@@ -198,10 +198,6 @@ export class McpRouter {
         return this.mcpdClient.post(path, body);
       },
       ...(this.auditCollector ? { auditCollector: this.auditCollector } : {}),
-      // Lazily resolve the caller's McpToken SHA via the audit collector's
-      // session principal map. The token is attached in onsessioninitialized,
-      // which runs before any plugin context is created, so this is stable.
-      getMcpTokenSha: () => this.auditCollector?.getSessionMcpTokenSha(sessionId),
     };
 
     ctx = new PluginContextImpl(deps);

src/mcplocal/tests/session-gate.test.ts

@@ -152,76 +152,4 @@ describe('SessionGate', () => {
     expect(gate.isGated('s1')).toBe(false);
     expect(gate.getSession('s2')!.tags).toEqual([]); // s2 untouched
   });
-
-  describe('per-McpToken ungate cache', () => {
-    it('new session from an already-ungated token starts ungated, with prior tags + prompts', () => {
-      const gate = new SessionGate();
-      gate.createSession('session-1', true, 'tokA');
-      expect(gate.isGated('session-1')).toBe(true);
-
-      gate.ungate('session-1', ['ops'], makeMatchResult(['runbook']), 'tokA');
-      expect(gate.isTokenUngated('tokA')).toBe(true);
-
-      // LiteLLM semantics: same token, brand-new session-id.
-      gate.createSession('session-2', true, 'tokA');
-      expect(gate.isGated('session-2')).toBe(false);
-      const s2 = gate.getSession('session-2')!;
-      expect(s2.tags).toContain('ops');
-      expect(s2.retrievedPrompts.has('runbook')).toBe(true);
-    });
-
-    it('does not persist across tokens', () => {
-      const gate = new SessionGate();
-      gate.createSession('s1', true, 'tokA');
-      gate.ungate('s1', ['ops'], makeMatchResult(['p']), 'tokA');
-
-      // Different token → fresh gated session.
-      gate.createSession('s2', true, 'tokB');
-      expect(gate.isGated('s2')).toBe(true);
-      expect(gate.isTokenUngated('tokB')).toBe(false);
-    });
-
-    it('is not triggered when no tokenSha is supplied (STDIO path)', () => {
-      const gate = new SessionGate();
-      gate.createSession('s1', true);
-      gate.ungate('s1', ['ops'], makeMatchResult(['p']));
-
-      // A second session with no token starts gated — STDIO semantics preserved.
-      gate.createSession('s2', true);
-      expect(gate.isGated('s2')).toBe(true);
-    });
-
-    it('honors the TTL window and expires', () => {
-      const gate = new SessionGate(50); // 50ms TTL for the test
-      gate.createSession('s1', true, 'tokA');
-      gate.ungate('s1', ['ops'], makeMatchResult(['p']), 'tokA');
-      expect(gate.isTokenUngated('tokA')).toBe(true);
-
-      return new Promise<void>((resolve) => setTimeout(() => {
-        expect(gate.isTokenUngated('tokA')).toBe(false);
-        gate.createSession('s2', true, 'tokA');
-        expect(gate.isGated('s2')).toBe(true);
-        resolve();
-      }, 70));
-    });
-
-    it('revokeToken clears the ungate entry immediately', () => {
-      const gate = new SessionGate();
-      gate.createSession('s1', true, 'tokA');
-      gate.ungate('s1', ['ops'], makeMatchResult(['p']), 'tokA');
-      expect(gate.isTokenUngated('tokA')).toBe(true);
-
-      gate.revokeToken('tokA');
-      expect(gate.isTokenUngated('tokA')).toBe(false);
-      gate.createSession('s2', true, 'tokA');
-      expect(gate.isGated('s2')).toBe(true);
-    });
-
-    it('empty-string tokenSha does not register an ungate entry', () => {
-      const gate = new SessionGate();
-      gate.createSession('s1', true, '');
-      gate.ungate('s1', ['ops'], makeMatchResult(['p']), '');
-      expect(gate.isTokenUngated('')).toBe(false);
-    });
-  });
 });