MCP integrations

MCP (Model Context Protocol) lets Mogick use external tools and resources. Connect enterprise systems, document retrieval, simulation tools, or project-specific services to the agent.

Quickly add a local server

Add the following to your project's .mogick/mcp.json:

{
  "servers": {
    "my-tool": {
      "type": "local",
      "transport": "stdio",
      "enabled": true,
      "command": ["npx", "-y", "@my/mcp-server"],
      "env": { "API_KEY": "<api-key>" }
    }
  }
}

Verify the configuration:

mogick mcp list
mogick

In the TUI, use /mcp to check server status. See MCP server configuration for all available fields.

Manage servers

Entry point	Action
mogick mcp list	List configuration, enabled state and source; does not test connectivity. Check live connections in TUI /mcp
mogick mcp setup	Interactively add or modify configurations
/mcp	View source, start, stop and restart in TUI
Ctrl+P	Open MCP servers and tools from the command palette

When the same server name appears in multiple sources, precedence is ACP host, project, then global configuration. In-session updates refresh tools at task boundaries without restarting the Mogick process.

Lazy loading

Servers that start slowly or are rarely used can be configured:

{
  "startup": "lazy"
}

The server appears as cold and does not block startup. The agent can call mcp.connect when needed, and the first mcp.call can also establish the connection on demand. When a session ends, Mogick releases on-demand connections that no other session uses.

Omit startup to use the default eager connection.

Progressive tool discovery

When connected MCP tool schemas exceed the context budget, Mogick switches to progressive discovery instead of placing every tool definition in the model context. The agent uses:

mcp.search → mcp.help → mcp.call

It searches for a tool, reads its parameters, and then calls it. This reduces token usage and keeps the tool prefix stable as connections change. If individual remote tools do not appear in the model's tool list, progressive mode may be active; check mcp.list and mcp.status first.

MCP meta-tools

Tool	Action
mcp.list	List servers, tools and resources overview
mcp.status	View connection details
mcp.wait_ready	Wait for a server to finish initializing
mcp.connect	Connect a cold or lazy server
mcp.disconnect	Disconnect on-demand connections and release the context
mcp.reconnect	Initiate a reconnection to the failed server
mcp.search	Search for tools across servers
mcp.help	View a tool's parameter documentation
mcp.call	Invoke a tool in progressive mode
mcp.read	Read resources exposed by a server

mcp.call can wrap remote tools with side effects and should not be considered a read-only entry; actual execution is still subject to permission approval.

When tools become available

Before the first request, Mogick briefly waits for eager local servers to become ready. If a server connects after that window, its tools are added to the session and become available on the next turn after the current task finishes.

When schemas fit within the budget, connected tools can appear directly in the tool list. When they exceed the budget, the agent accesses them through progressive meta-tools.

Recommendations

• Use eager startup for frequently used servers that start quickly.
• Use lazy startup for infrequently used or slow servers, or servers with many tools.
• Use absolute paths in a local server's command.
• Prefer HTTP for remote services; use SSE only for compatibility with older servers.
• Do not store secrets in project configuration that may be committed.

Troubleshooting

Run in order:

mogick mcp list
mogick doctor

If a server is missing, disabled, cold, failed, or exposes no tools, see Troubleshoot MCP connections and tools.