Roadmap: deliver first-class MCP support across Atlas agents

[uzayer]

Why this is a roadmap, not one implementation ticket

MCP is a foundational cross-agent capability. Atlas needs a coherent MCP experience for its native agent and external ACP agents; it should be planned as a sequence of deliverable milestones, not collapsed into a single “MCP support” task.

Zed’s current documentation provides the relevant model: its configured MCP servers are used by its native Agent, may be forwarded to external ACP agents, and those agents can also load their own native MCP configuration. That means Atlas must make source ownership and tool availability explicit rather than silently duplicating servers or tools.

Current Atlas baseline

• Native Cersei reads an app-level mcp-servers.json, connects configured servers once, and proxies discovered tools into the native agent.
• Changes take effect only after app restart.
• The current bridge is stdio-oriented; its underlying SDK path notes SSE as unimplemented.
• The Tauri layer can read/write the raw list, but there is no discovered settings UI, connection health/status, OAuth flow, lifecycle controls, or server-level diagnostics.
• The ACP integration contains no Atlas-managed MCP forwarding, capability detection, source reconciliation, or duplicate-tool policy. Claude Code, Codex, and other ACP agents may already own independent MCP configuration.

Desired outcome

Atlas becomes the clear place to inspect, configure, scope, and understand MCP access without breaking agent-native setups:

• The user can see which MCP servers and tools are available to each agent, where each came from, and whether it is healthy.
• Atlas-native and ACP sessions receive only the intended servers/tools, with explicit capability-aware delivery.
• Existing Claude Code/Codex MCP configuration remains respected; Atlas must not create duplicate tool definitions by default.
• Credentials, authorisation, and permission boundaries are safe and auditable.

Proposed milestone breakdown

1. MCP architecture RFC — define server sources (Atlas global/project vs agent-native), scope/precedence, ACP capability matrix, forwarding contract, tool naming/provenance, collisions/deduplication, lifecycle/reload behavior, and migration from the current JSON file.
2. Configuration and secret model — create a schema-backed, config-file-first representation aligned with ATL-109; avoid plaintext secrets, define OAuth/headers/env handling, and support global/project scopes.
3. Native-agent reliability — replace restart-only behavior with safe reload/reconnect, server-level enablement, structured errors, and transport support based on the RFC.
4. MCP management UI — add/create/edit/remove/import servers; show connection state, tools, provenance, scope, logs, and repair actions. Make unsupported transports or auth states understandable.
5. ACP delivery layer — detect each external agent’s MCP/ACP capabilities, forward only Atlas-managed servers when supported, and report the resulting tools per session.
6. Native-config coexistence — model agent-native MCP separately from Atlas-managed MCP. Provide a non-destructive discovery/status path where possible; do not edit Claude/Codex config unless the user explicitly asks.
7. Tool collision and permission policy — prevent or clearly disambiguate duplicate server/tool names; preserve origin metadata; apply user-level permission mode and per-tool/server consent consistently.
8. Observability, tests, and migration — cover connection/auth/reload/failure paths and ACP/native matrices; migrate existing mcp-servers.json users without losing configuration.

Acceptance criteria for this parent issue

• An approved RFC turns the milestones above into independently scoped child issues with ownership and ordering.
• Atlas documents its MCP behavior at the point users configure or start agents: native vs ACP, Atlas-managed vs agent-native, forwarding support, and duplicate handling.
• The shipped design has a defined policy for secrets, permission prompts, tool provenance, collisions, server health, and configuration reloads.
• No implementation claims “MCP support” complete until the native and ACP capability matrices are verified with integration coverage.

Related work

• ATL-109 — config-driven settings and agent self-configuration: the MCP schema and safe user-facing configuration workflow should build on this rather than add another ad-hoc settings format.

References

• Zed MCP documentation
• Zed external-agent documentation