Configuring MCP Servers

Global MCP server settings live in the active profile’s mcp.json. Open it from the Kodik panel via MCP Servers → Installed → Configure MCP Servers, or edit it directly. For a local window, the file is stored in your local Kodik global storage directory (…/User/globalStorage/kodik.chat/settings/mcp.json). When the window is connected to a remote environment, Kodik uses that remote environment’s global storage path instead, so the global MCP config follows the machine where servers run.

Workspace MCP servers are defined in <workspace>/.kodik/mcp.json and load only when the workspace is trusted. For chat, the path shown to the agent follows the folder selected for that conversation. If that folder is contained in the trusted IDE workspace (including its contained worktrees), MCP discovery and server launch paths follow it too. An external chat folder is shown with an inactive-path notice, but its MCP processes are not auto-loaded under the IDE workspace’s trust. Plugin-provided MCP servers remain in the owning plugin’s <Kodik plugin directory>/<plugin-id>/.mcp.json; edit that file rather than copying the server into the global configuration.

Kodik gives its agent the absolute active paths and these scope rules. This keeps agent-driven setup aligned with the current runtime: development builds use their code-oss-dev profile data directory, installed builds use their .kodik profile data directory, remote windows use the remote configuration location, and installed plugins remain under the user-level Kodik plugin directory.

The file is parsed as JSONC — you can use // line comments, /* */ block comments, and trailing commas freely.

Top-level structure

{
  "servers": {
    // named server entries go here
  },
  "inputs": [
    // optional: prompt-once variables for secrets/paths
  ],
}

Note: the top-level key is servers, not mcpServers. Configs written for other tools that use mcpServers will need that key renamed.

Per-server fields

Every server entry shares these common fields, regardless of transport type.

Common fields

Field	Type	Default	Description
disabled	boolean	false	Set to true to deactivate the server without removing it
timeout	number (seconds)	60	How long to wait for a tool call response. Minimum 30 s
autoApprove	string[]	[]	Tool names that are auto-approved without prompting the user
enabledTools	string[]	—	When set, only these tools are exposed to the agent
disabledTools	string[]	—	Tools to hide from the agent
defaultToolsApprovalMode	"always-ask" | "auto-approve"	—	Default approval mode for all tools on this server. Per-tool entries in autoApprove take precedence
auth	object	—	OAuth 2.1 config for HTTP/SSE servers (see below)

Transport-specific fields

The type field selects the transport. If omitted, Kodik infers the type: a config with command is stdio; a config with url and type: "sse" is SSE; type: "http" or type: "streamableHttp" is streamable HTTP.

stdio — local process

Launches a command on your machine and communicates over stdin/stdout.

On Windows, package-manager shims such as npx, uvx, .cmd, and .bat are resolved and launched through the Windows command shell automatically.

Field	Type	Required	Description
command	string	yes	Executable to run (e.g., node, python, npx)
args	string[]	no	Command-line arguments
env	object	no	Extra environment variables merged with the inherited environment
cwd	string	no	Working directory for the spawned process

{
  "servers": {
    "my-local-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "your_api_key",
      },
      "timeout": 60,
      "autoApprove": ["read_file", "list_dir"],
      "disabled": false,
    },
  },
}

sse — Server-Sent Events

Connects to a remote server over HTTP using the SSE transport. Requires type: "sse" when the server entry also has a url field (to distinguish it from streamable HTTP).

Field	Type	Required	Description
url	string (URL)	yes	SSE endpoint URL
headers	object	no	Extra HTTP request headers

{
  "servers": {
    "my-sse-server": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": {
        "X-Custom-Header": "value",
      },
    },
  },
}

http — Streamable HTTP (recommended for new servers)

The modern MCP transport. Use type: "http" (or the alias "streamableHttp"). Both spellings are accepted and normalized internally.

Field	Type	Required	Description
url	string (URL)	yes	Streamable HTTP endpoint URL
headers	object	no	Extra HTTP request headers

{
  "servers": {
    "my-http-server": {
      "type": "http",
      "url": "https://example.com/mcp",
    },
  },
}

Runtime behavior

Kodik discovers configured MCP servers in parallel so one slow server does not block the rest of the tool list. Local stdio servers are kept alive and reused across tool listing and tool calls, then cleaned up when idle; cleanup tears down the server process tree rather than only the direct child. Streamable HTTP responses are bounded, so an oversized JSON or inline SSE response fails the MCP request instead of filling the agent host process.

Tool approval

Kodik asks for confirmation before running any tool by default. You can change this globally per server or per tool.

{
  "servers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      // Auto-approve every tool on this server without prompting:
      "defaultToolsApprovalMode": "auto-approve",
    },
  },
}

Alternatively, add specific tool names to autoApprove to approve just those tools while leaving others on always-ask:

{
  "servers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "autoApprove": ["read_file", "search"],
    },
  },
}

See Auto-Approve for the full approval workflow.

When you change MCP server state or tool approval from the UI, Kodik reports persistence or sign-in failures back to that action instead of treating the server list as successfully refreshed.

Filtering tools

Use enabledTools to expose only a subset of what the server provides, or disabledTools to hide specific tools:

{
  "servers": {
    "big-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      // Only expose these two tools to the agent:
      "enabledTools": ["search", "read_document"],
    },
  },
}

OAuth 2.1 authentication (HTTP/SSE servers)

Remote servers can require OAuth. Kodik supports OAuth 2.1 with automatic discovery via Protected Resource Metadata. The auth block lets you override specific values when auto-discovery is not available (e.g., self-hosted servers without .well-known endpoints).

Field	Type	Description
disabled	boolean	Set to true to skip OAuth entirely for this server
clientId	string	Pre-registered OAuth client ID
clientSecret	string	Client secret (stored in SecretStorage when entered via UI)
scopes	string[]	Requested OAuth scopes
authorizationServer	string (URL)	Override the authorization server URL

{
  "servers": {
    "protected-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "auth": {
        "clientId": "my-client-id",
        "scopes": ["mcp:read", "mcp:write"],
        "authorizationServer": "https://auth.example.com",
      },
    },
  },
}

A server that answers 401 appears in Settings → MCP Servers with a Requires authentication status and a Sign in button next to its toggle. Sign in runs the OAuth flow — your browser opens on the vendor’s consent page, and the server flips to Connected once you approve. Alternatively, put a token in the server’s headers (for example "Authorization": "Bearer <token>") or use the Configure prompt of a Marketplace plugin server that declares a token in its user configuration; a header whose token resolves empty is not sent, so an unconfigured token falls through to the OAuth path. When the agent calls a tool on an unauthenticated server, the failed tool card in chat offers the same Sign in.

Kodik resolves the OAuth client in this order: an explicit auth.clientId from your config, a Kodik app bundled for the vendor (GitHub, Slack, Google Drive, Figma), the client registered on a previous sign-in, and finally automatic Dynamic Client Registration. If the vendor blocks automatic registration (Figma does), Kodik asks you for a client ID once and remembers it. Completed sign-ins are stored securely and reused across editor restarts — tokens refresh silently until you sign out of the server.

Input variables

The inputs array defines variables that Kodik prompts for once and then substitutes into server config values. This avoids hardcoding secrets in mcp.json. Use ${input:<id>} anywhere in args, env, headers, or url.

{
  "inputs": [
    {
      "id": "api_key",
      "type": "promptString",
      "description": "Enter your API key",
      "password": true,
    },
  ],
  "servers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${input:api_key}",
      },
    },
  },
}

password: true routes the cached answer to SecretStorage so it is never stored in plain text.

Managing servers from the UI

You can do most things without editing the file manually:

• Enable/disable: toggle the switch next to a server in the Installed tab
• Restart: click the Restart button next to a server, or the “Restart Server” button inside the server’s settings panel
• Remove: click the red “Remove Server” button inside the server settings panel
• Timeout: use the “Request timeout” dropdown in the server settings panel (30 s to 1 h)

Troubleshooting

Symptom	Likely cause
Server not connecting	Wrong command/path, or a required runtime (Node, Python) not installed
Tool not visible	disabled: true, tool name in disabledTools, or not in enabledTools
Slow responses	Increase timeout; check network latency for remote servers
Auth failure on remote server	Check auth fields or re-run the OAuth flow by restarting the server