Troubleshoot MCP connections and tools

Use this guide when an MCP server or tool configured in mcp.json does not appear in mogick mcp list, the TUI's /mcp panel, or the agent's tools. For configuration fields, see MCP server configuration.

Run a quick check

mogick mcp list
mogick doctor

In the TUI, also enter /mcp to check the server's configuration source, enabled state, and connection state.

MCP configuration is merged by server name. A project server in .mogick/mcp.json overrides a global server with the same name in <config-dir>/mcp.json; differently named servers remain available together. Configuration injected by an ACP host has the highest precedence.

Troubleshoot by status

The server does not appear in the list

First check whether the configuration is loaded into the current workspace:

1. The file name must be mcp.json.
2. The top-level structure should be the servers object.
3. The project configuration path is .mogick/mcp.json in the working directory when starting Mogick.
4. A server with the same name may be overridden by project configuration or the ACP host.
5. MOGICK_CONFIG_FILE only replaces the main config.json and does not change the MCP configuration file location.

If mogick doctor reports a JSON parsing error, fix the corresponding mcp.json first.

The server is displayed as disabled

Omitting enabled leaves the server disabled. Set it explicitly for a server that should connect:

{
  "enabled": true
}

You can also enable the server from the TUI's /mcp panel.

The server is displayed as cold

cold is usually not an error. It means that the server has startup: "lazy" enabled and no connection has been initiated yet.

Choose one of these approaches:

• If you want to connect immediately after startup, change startup to "eager", or omit this field.
• To keep lazy startup, let the agent use MCP meta-tools to connect and call the server on demand.

The server is displayed as connecting

connecting means Mogick recognizes the enabled server, but initialization has not yet completed or failed.

Common reasons:

• Local stdio process starts slowly.
• The command path or parameters are incorrect and the process cannot complete MCP initialization.
• The remote url is unreachable or the protocol does not match.

Verify that type, transport, command, and url match the server's actual startup method. timeout is measured in milliseconds; increase it only when initialization is genuinely slow.

The server is displayed as failed

failed means the latest connection attempt failed. After you correct the configuration, Mogick reconciles the connection automatically. For a temporary outage, the agent can call mcp.reconnect for the affected server.

Don't simply interpret repeated failures as requiring longer timeouts. More common are command, path, permission, URL, authentication, or protocol mismatches.

Check a local stdio server

A local server uses type: "local" and transport: "stdio". command is an array whose first element is the executable and remaining elements are arguments.

Check the following:

1. command[0] runs in the same terminal used to start Mogick.
2. Required runtimes such as Node.js or Python are on that terminal's PATH.
3. Relative command paths resolve from Mogick's working directory.
4. env includes every environment variable required by the server.

The local process will inherit the process environment of Mogick; the value in env is appended or overwritten literally, and the ${VAR} placeholder will not be expanded.

Check a remote HTTP or SSE server

A remote server uses type: "remote" and connects through url.

Priority checks:

1. transport matches the server. Prefer http; use sse only when the server requires it.
2. url is the endpoint actually exposed by the MCP server.
3. Credentials in headers are still valid.
4. The URL is reachable from the current network.

headers containing credentials should not be submitted to version control or pasted into issue reports.

Connected, but the agent cannot see a tool

First distinguish a disconnected server from tools hidden by progressive discovery.

Ask the agent to use these MCP meta-tools:

mcp.list
mcp.status
mcp.search
mcp.help
mcp.call

When MCP schemas would consume too much context, Mogick enables progressive discovery. Instead of adding every server tool to the model's tool list, it uses mcp.search, mcp.help, and mcp.call to discover and invoke tools on demand. A missing tool name therefore does not necessarily indicate a connection failure.

If mcp.status shows that the server is connected but the number of tools is 0 or the expected tools are missing, go back to the MCP server itself and verify that it is implemented and returns tools/list.

Confirm that the problem has been solved

mogick mcp list
mogick doctor

Interpret server states as follows:

Status	Meaning
connected	Connected, you can continue to check whether the tools and resources are as expected
cold	Normal state for a lazy server; connect when needed
disabled	The configuration exists but is not enabled
connecting	Still connecting or initializing, continue to see commands, URLs, timeout
failed	The latest connection failed, please check the error message and configuration

Still unresolved

When reporting a problem, please provide:

• Operating system and Mogick working directory.
• mogick mcp list output.
• Relevant output from mogick doctor.
• Server configuration with secrets redacted.
• Manual startup output for a local server, or reachability results for a remote server.

Remove API keys, Authorization headers, cookies, internal URLs, and sensitive environment variables.

Related documents

• MCP extension
• MCP Configuration
• List of built-in tools

Path placeholders <config-dir> and <db-path> refer to the effective profile/channel paths; see Data directories.