Explore: project- and directory-scoped MCP servers #271

mini's servers are all user-scoped (~/.mini/servers/). Clients also support servers scoped to a project or directory: Claude Code's local scope (projects[<path>].mcpServers in ~/.claude.json) and project scope (.mcp.json in the repo). mini has no equivalent, so those servers either get flattened into the user scope or left behind. This issue is to explore whether mini should support directory-scoped servers, how, and what it would cost. The direction for now is to stay focused on user-scoped servers.

What happens today

mini init and mini add --from-claude read ~/.claude.json through ExtractClaudeMCPServers:

• If there are any user-scope servers (top-level mcpServers), only those are imported, and every project's servers are ignored without a message.
• If there are none, every project's servers are merged into one global set. On a name clash between projects the code keeps the "first seen", but Go map iteration is random, so which project's server (URL, headers, token) wins can change between runs. The one that loses is reported only as a stderr warning.

In both cases, a server configured for one project either never reaches mini or becomes available in every project.

.mcp.json (Claude Code's in-repo project scope) is not read at all.

Can mini tell which project a client is in?

Observed on macOS, 2026-10-01:

No client passed the project through environment variables. MCP's roots feature, which lets a client report its workspace folders, is deprecated as of protocol 2026-07-28 (SEP-2577). The spec points servers to tool parameters, resource URIs, or server configuration instead.

ChatGPT desktop starts a fresh mini connect for every session, so several projects can share one daemon at the same time.

Questions to answer

• Demand: how often do users rely on project-scoped servers, versus user-scoped ones?
• Where project config would live:
  • private to the machine, like Claude Code's local scope;
  • in the repo, like .mcp.json. Config from a cloned repo can launch stdio commands, so it needs a trust and approval step;
  • or both.
• How a session learns its project: the working directory (verified above for Claude Code and ChatGPT's Codex), an explicit flag such as --project DIR for clients that don't spawn in the project, or something else. How do nested directories resolve?
• Daemon sessions: one shared daemon serves sessions from different projects. What does each session see?
  • name-clash precedence between project and user servers;
  • when project upstreams start and stop;
  • tool-list changes per session;
  • token and OAuth storage per scope.
• Import and init: how project-scoped servers in other clients map into mini, and what a "move these servers into mini" step would remove from each client's scope.
• Effort:
  • config layout and loading (overlaps the config work in refactor: config - a server lives only in its own file, named by that file #257–fix: config - add_server and remove_server save to config through ops #261 and mini connect exits when any server references an environment variable the agent's process doesn't have #265);
  • daemon session server sets;
  • connect;
  • import;
  • tests.

Related: #265 (per-server load isolation), #270 (Codex import).