MCP server configuration (mcp.json)

MCP configuration lives in a separate mcp.json file rather than the main config.json.

Level	Path
Global	<config-dir>/mcp.json
Project	<workspace>/.mogick/mcp.json
Host	ACP session injection, no writing to local files

For servers with the same name, precedence is ACP host > project > global. Servers with different names are merged. MOGICK_CONFIG_FILE does not change where Mogick loads MCP configuration.

Recommended structure

servers uses objects whose keys are server names. Legacy arrays can still be read, but Mogick uses the object format for new writes.

{
  "servers": {
    "local-tool": {
      "type": "local",
      "transport": "stdio",
      "enabled": true,
      "command": ["python3", "-m", "my_mcp_server", "--port", "8080"],
      "env": { "API_KEY": "<api-key>" }
    }
  }
}

Choose a transport

Scenario	type	transport	Required fields
Local child process	local	stdio	command
Remote Streamable HTTP	remote	http	url
Compatible with legacy SSE	remote	sse	url

When transport is omitted, local servers default to stdio and remote servers default to http. Use SSE only when a legacy server explicitly requires it.

Remote example

{
  "servers": {
    "remote-api": {
      "type": "remote",
      "transport": "http",
      "enabled": true,
      "url": "https://mcp.example.com/api",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

headers containing credentials should not be committed to version control.

Field reference

Common fields

Field	Type	Required	Default value/Description
type	string	Recommended	local or remote; otherwise inferred from url and transport
transport	string	No	stdio, http, or sse
enabled	bool	No	Default false; will not connect if not enabled
startup	string	No	eager (default) or lazy
timeout	int	No	Connection/wait timeout in milliseconds; 0 uses the client default

Local fields

Field	Type	Required	Description
command	string[]	Yes	The first element is the executable; remaining elements are arguments
env	object	No	Append or overwrite literal environment variables to the child process

Local processes inherit Mogick's process environment. env values do not expand ${VAR}; to inject secrets from outside, let the server read inherited environment variables directly instead of writing placeholders into the configuration.

Relative command paths are resolved according to the current working directory when Mogick is started, rather than according to the mcp.json directory. It is recommended to use absolute paths.

Remote fields

Field	Type	Required	Description
url	string	Yes	MCP service address
headers	object	No	HTTP request headers sent with the request

Eager and lazy startup

• startup: "eager": Connect when the process or session starts.
• startup: "lazy": Keep cold until triggered by mcp.connect, Skill or first call.
• Unknown startup value falls back to eager and logs a warning.

Lazy startup works well for slow, infrequently used servers or servers with large tool schemas. When a session closes, Mogick disconnects an on-demand server if no other session is using it.

Management and hot updates

mogick mcp list
mogick mcp setup

mogick mcp setup is an interactive wizard; it does not accept server names or legacy configuration flags. In the TUI, use /mcp to view server sources and connection status or to start and stop servers.

When MCP configuration changes during a session, Mogick reconciles added, removed, enabled, disabled, or modified servers while preserving unchanged connections. The active task keeps its current tool snapshot; the next turn uses the updated toolset.

Status

Status	Meaning
disabled	enabled is false
cold	Lazy server has not connected yet
connecting	Starting or handshaking
connected	Connected and ready
failed	Startup, network, or protocol handshake failed

Troubleshooting

Run mogick mcp list and mogick doctor. For step-by-step diagnosis, see Troubleshoot MCP connections and tools.

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