Configuring MCP Servers

All MCP server settings live in a single file: mcp.json. Open it from the Kodik panel via MCP Servers → Installed → Configure MCP Servers, or edit it directly. The file is stored in your Kodik global storage directory (…/User/globalStorage/kodik.chat/settings/mcp.json).

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.

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",
    },
  },
}

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.

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",
      },
    },
  },
}

When Kodik receives a 401 from a server it will trigger the OAuth flow automatically, prompting you to 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