Proposal: MCP server configuration at server level and role level (dedicated plugin)

[zarch]

What I'd like to achieve

I want MCP server configuration to work at two levels:

1. Server level — installation-wide defaults. Admin configures a set of MCP servers that are available to everyone. (This partially exists today as MCPServerManager.)
2. Role level — roles (admin, developer, guest, etc.) get additional MCP servers or can override/deny servers from the server-level config. For example: admins get access to internal MCP servers, guests only see the public ones.

The goal is to make this configurable through the existing /settings CRUD, with no code changes per deployment.

How I'd approach it

A dedicated plugin (mcp_manager) that owns all MCP configuration policy. Core stays a dumb consumer.

The key idea: core's MCPClients should not know where server configs come from — DB, roles, env vars, a registry. It shouI'd do this via a hook:

# core — MCPClients.need_new_client()
servers = await agent.ccat.mad_hatter.execute_hook(
    "mcp_servers_for_user",
    [],  # default: no servers (plugin not installed → MCP disabled)
    caller=agent,
)

The plugin implements the hook and owns the resolution logic:

mcp_manager/
├── plugin.json
├── hooks.py          # mcp_servers_for_user — single integration point
├── services.py       # ServerMcpSettings (server-level) + RoleMcpSettings (role-level)
├── endpoints.py      # public MCP registry browser (the orphaned route, moved here)
├── models.py         # RoleMcpConfig
└── tests/

Two services, both SingletonService subclasses with a nested Settings model:

• ServerMcpSettings (slug="server") — installation-wide defaults. Admin configures via /settings. Env-var seed CCAT_MCP_SERVERS) on first boot. Essentially the current MCPServerManager logic, relocated.

• RoleMcpSettings (slug="role") — maps each role to additional servers and a deny-list. Merge precedence: deny > role override > server default.

Since both subclass SingletonService with a Settings model, the existing /settings CRUD auto-discovers them — no new route code for the config UI.

Side benefit: the public MCP registry route (currently orphaned at cat/routes/mcp/registry.py, not mounted anywhere) moves into the plugin as an @endpoint.

Why a hook instead of core calling the service directly

• Core has zero imports of any MCP settings service. If the plugin isn't installed, the hook returns [] and MCP is cleanly disabled.
• If someone wants a completely different config strategy (file-based, Consul, Kubernetes ConfigMap), they write their own plugin implementing the same hook. Core doesn't change.
• The contract is just the hook name + return type. Core can be refactored freely without touching MCP config.

Core changes (minimal)

• Simplify MCPClients.need_new_client() to call the hook instead of hardcoding await agent.ccat.get("mcp_servers", "system").
• Move MCPServerManager out of core into the plugin.
• Move the orphaned registry route into the plugin as an @endpoint.
• MCPServer (pydantic model) stays in cat/protocols/model_context/server.py as a shared type.

Open questions

1. Hook async support — can mcp_servers_for_user be async def? The settings services do async DB reads. If async hooks are supported, the plugin code is much cleaner. If not, I can work around it.

2. Hook return type — list[MCPServer] (I build the fastmcp config dict in core) or the raw {"mcpServers": {...}} dict (what MCPClient.__init__ expects today)? I'd prefer list[MCPServer] so the model is the single source of truth.

3. Role access in hooks — is cat.user.role the right way to get the current user's role inside a hook? Any example or best practice that I should follow?

4. Scope — I'd ship Tier 1 (server-level) + Tier 2 (role-level) first and leave user-level enable/disable (the existing TODOV2 in need_new_client) for later. Agree, or do you want all three at once?

Conclusion

Is the described plan sound? Should I consider a different approach? Do you know if there's already someone working on this? Any thoughts?

If there are no blockers, I'd start scaffolding the mcp_manager plugin.

[pieroit]

Too early to design MCP attribution / stratification / hooking.
Not sure what has to stay in core and what in plugins

Leaving the discussion open to gather suggestions on MCP server management and attribution (to users, but also to agents)