Using MCP in Kilo Code

MCP server configurations are stored inside the main Kilo config file. There are two levels:

1. Global Configuration: ~/.config/kilo/kilo.jsonc — applies to all projects.
2. Project-level Configuration: kilo.jsonc in your project root, or .kilo/kilo.jsonc for a cleaner setup.

Precedence: Project-level configuration takes precedence over global configuration.

Editing MCP Settings

You can edit MCP settings from the Kilo Code settings UI:

1. Click the icon in the sidebar toolbar to open Settings.
2. Click the Agent Behaviour tab on the left side.
3. Select the MCP Servers sub-tab.

From here you can add, edit, enable/disable, and delete MCP servers. Changes are written directly to the appropriate config file.

Config Format

MCP servers are configured under the mcp key in kilo.jsonc:

Local (STDIO) server:

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["node", "/path/to/server.js"],
      "environment": {
        "API_KEY": "your_api_key"
      },
      "enabled": true,
      "timeout": 10000
    }
  }
}

Remote (HTTP/SSE) server:

{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "url": "https://your-server-url.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      },
      "enabled": true,
      "timeout": 15000
    }
  }
}

Remote servers support OAuth 2.0 authentication. If the server supports it, Kilo Code will automatically start the OAuth flow when you connect. You can also disable OAuth with "oauth": false.

Both global and project-level files use a JSON format with a mcpServers object containing named server configurations:

{
  "mcpServers": {
    "server1": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

Example of MCP Server config in Kilo Code (STDIO Transport)

Editing MCP Settings Files

You can edit both global and project-level MCP configuration files directly from the Kilo Code settings.

1. Click the icon in the top navigation of the Kilo Code pane to open Settings.
2. Click the Agent Behaviour tab on the left side
3. Select the MCP Servers sub-tab
4. Click the appropriate button:
   • Edit Global MCP: Opens the global mcp_settings.json file.
   • Edit Project MCP: Opens the project-specific .kilocode/mcp.json file. If this file doesn't exist, Kilo Code will create it for you.

Deleting a Server

1. Press the next to the MCP server you would like to delete
2. Press the Delete button on the confirmation box

Restarting a Server

1. Press the button next to the MCP server you would like to restart

Enabling or Disabling a Server

1. Press the toggle switch next to the MCP server to enable/disable it

Set the timeout field (in milliseconds) in the server's config entry. The default is 10 seconds for local servers and 15 seconds for remote servers.

MCP tool calls use the same permission system as built-in tools. Each MCP tool's permission key is its namespaced name: {server}_{tool} (e.g. my_server_do_something).

At runtime: When an MCP tool is called, the Permission Dock shows an approval prompt. Click Approve Always to save an allow rule to your config so future calls to that tool are auto-approved.

In your config file: Add the tool name (or a wildcard pattern) to the permission key in kilo.jsonc:

{
  "permission": {
    "my_server_do_something": "allow",
    "my_server_*": "allow"
  }
}

Windows Configuration Example

When setting up MCP servers on Windows, you'll need to use the Windows Command Prompt (cmd) to execute commands. Here's an example of configuring a Puppeteer MCP server on Windows:

{
  "mcpServers": {
    "puppeteer": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

This Windows-specific configuration:

• Uses the cmd command to access the Windows Command Prompt
• Uses /c to tell cmd to execute the command and then terminate
• Uses npx to run the package without installing it permanently
• The -y flag automatically answers "yes" to any prompts during installation
• Runs the @modelcontextprotocol/server-puppeteer package which provides browser automation capabilities

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

• Server Not Responding: Check if the server process is running and verify network connectivity. Review server status in Settings > Agent Behaviour > MCP Servers.
• needs_auth status: For remote servers with OAuth, the extension will show a notification to start the auth flow. Click it to authenticate.
• failed status: Check the CLI output for error details. Ensure commands and paths are correct.
• Tool Not Available: Confirm the server is properly implementing the tool and it's not disabled in settings.