Skip to content

MCP servers

How CompozyOS gives agent sessions MCP tools, when a change reaches a session that is already open, and how to fix a tool the agent can't call.

4 min read4 pages in MCP servers

On this page5

An MCP server gives agents extra tools: a Linear server lets an agent read your issues, a Sentry server lets it look at errors. CompozyOS sessions see two kinds of MCP servers:

  • CompozyOS servers are the ones CompozyOS manages: added in Settings → MCP servers, written in mcp.json or config.toml, or shipped by an extension. CompozyOS starts them, signs in to them and passes their tools to every session through its own MCP proxy.
  • Runtime servers are the ones a coding agent CLI loads from its own files, for example the servers in Claude Code's ~/.claude.json or Codex's ~/.codex/config.toml. CompozyOS lists them read-only so you can see what each runtime loads. See Runtime servers.

Changes reach open sessions on the next message

You don't need to stop, restart or fork a session to give it a new server. After you add, enable, approve or sign in to a server, or install or enable an extension, the session you already have open can use the new tools from your next message. Removing a server, disabling it, revoking its approval or signing out takes its tools away on the next call.

When a change is waiting, the session shows Applies on your next message. When you send the message, CompozyOS reloads the agent's runtime first if the runtime can't pick up new tools by itself, keeping the whole conversation. A turn that is already running is never interrupted. The transcript then shows one quiet line:

LineWhat happened
MCP servers updated · sentry addedThe runtime reloaded with the new tools.
MCP servers updated · conversation continued from historyThe runtime couldn't resume its own conversation, so CompozyOS continued it from the transcript.
Couldn't start Claude Code with the new MCP servers · your message wasn't sentNo runtime could start. The message goes back to the composer; send it again to retry.

Forks, continued sessions and child sessions follow the current server set too. A child session stays limited only when it was started with an explicit list of MCP servers.

Who can turn a server on

Adding a server through CompozyOS is your consent. These servers are usable right away:

  • servers you add in Settings, or copy in from a runtime;
  • servers in your own files under ~/.compozy (personal and profile mcp.json or config.toml);
  • servers of an extension you installed and enabled.

Servers declared in a project's files (<project>/.compozy/mcp.json, the project's config.toml, or an agent or skill folder inside the project) arrive with the repository, so a commit could add them without you knowing. They wait for your approval and never start until you allow them. See Project servers need approval.

Check what a session can use

The composer of every session with MCP servers has an MCP servers control: the plug icon at the end of the composer's toolbar. Hover it to see how many servers the session can use right now. It shows a dot in its top corner when a server needs attention and one in its bottom corner when a change applies on your next message. Open it to see:

  • CompozyOS: each server with its state and the one action that fixes it (Sign in or Allow);
  • the runtime's own servers (for example Claude Code): read-only, with Manage in Settings;
  • Not available in this session: servers the session is limited from, collapsed.

The same list is available from the CLI:

compozy session mcp <session-id>
Terminal
SESSION sess-27200ac31012601a · claude · 2 usable
COMPOZYOS SERVERS
  github                   Ready                        26 tools
  linear                   Needs sign-in                0 tools
    Sign in to linear in CompozyOS
  branas-dashboard         Applies on your next message 0 tools
RUNTIME SERVERS (Claude Code)
  cua-driver               Loaded by Claude Code

Agents read it with the compozy__session_mcp_list native tool, and apps with GET /api/workspaces/{workspace_id}/sessions/{session_id}/mcp. None of them start or contact a server; they report what CompozyOS already knows.

States and fixes

StateMeaningFix
ReadyThe agent can call its tools.—
Applies on your next messageAdded or changed since the runtime started.Send your next message.
Needs sign-inThe server uses OAuth and has no valid sign-in.Sign in in the MCP control or Settings, or compozy mcp auth login <name>.
Waiting for approvalA project-file server you haven't allowed, or one that changed.Allow, or compozy mcp allow <name> --workspace <project>.
Failed (Couldn't connect)CompozyOS couldn't start or reach the server.Open the server in Settings → MCP servers and read its status.
Not available in this sessionThe session was started with a list of servers that leaves it out.Start a new session without that limit.
Loaded by Claude CodeA runtime server the runtime loads by itself.Manage it in the runtime, or copy it to CompozyOS.
Off in CompozyOS sessionsA runtime server that runtime_mcp = "off" keeps out of sessions.Turn the runtime's switch back on.

When an agent calls a tool it can't use, the error names the fix, for example sentry is waiting for approval in compozy. Allow it in Settings → MCP servers. or linear needs sign-in. Sign in to linear in CompozyOS (Settings → MCP servers).

Next steps