Skip to content

A person's own MCP servers and skills live in two layers beside config.yaml, import from the files other tools keep, and a workspace's servers run only once somebody attached has said so

Decision 700 · accepted · 2026-09-26 · issue #60

Superseded in part

In part by 820.

  • Layers. <config>/mcp.json and <config>/skills/ for the user, .troupe/mcp.json and .troupe/skills/ for the workspace: the mcpServers shape every other tool reads and writes, plus an include list that reads another file in place — a link; skills.json does the same for directories of skills. They stack over config.yaml's mcp: as the config files stack (686): merged by name, key by key, the workspace's over the user's, null removing and a list replacing, so {"disabled": true} alone turns a lower layer's server off. Each server and skill carries its layer and its file, since that is what a person needs to know to change it (Troupe.MCP.Local, Troupe.Skills.Local).
  • Import. Troupe.MCP.Import reads the four shapes: ${VAR} and ${env:VAR} become {env:VAR}, which the loader refuses when unset instead of sending an empty string; a VS Code ${input:…} skips that server and says so, since only VS Code could fill it in; headers are dropped with a warning, a credential this slice does not carry. mcp.add with from copies, or links; skills.add copies a directory of SKILL.mds or one skill's directory, or links it.
  • Trust. A .troupe/mcp.json arrives with a clone. Its servers start only after the session's question, through Troupe.Session.Questions under mcp-trust-<hash>, so any client that answers an ask_user answers this; deny is the first option, so a runner with nobody to ask runs nothing. allow is remembered in <state>/mcp-trust.json per checkout (Troupe.MCP.Trust), beside a fingerprint of the command, its arguments, environment, directory or URL, so a changed command is a new question and a re-ordered file is not; once runs them for the session; deny leaves them stopped until the next session or a reload. A workspace on trusted_workspaces is not asked, since trusting it already lets its config.yaml name what runs; the user's layer asks nothing, since the person wrote it. A pod session reads no layer at all, and managed_mcp_servers_only starts nothing local and says so in each server's status.
  • Skills. A bundle's skills stay gated by the profile's skills: list and the team's entitlements; a person's own are offered to every agent of the session, because the person put them there and a skill nobody can call is not one. They are read beside the workspace wherever the session runs, as .troupe/agents/ is. A local skill's files are listed by their path, and the user's directory and every linked root are read roots of the session.
  • Protocol. Env values never go over the wire: mcp.list and mcp.add answer with the names.

Governs: apps/troupe_core/lib/troupe/commands/local.ex, apps/troupe_core/lib/troupe/mcp/import.ex, apps/troupe_core/lib/troupe/mcp/local.ex, apps/troupe_core/lib/troupe/mcp/trust.ex, apps/troupe_core/lib/troupe/skills/local.ex, apps/troupe_gateway/lib/troupe/gateway/local_sources.ex