External MCP Servers

You can connect MCP servers in any language capable of writing to stdout or hosting an HTTP endpoint — Python, JavaScript, Go, and more.

How it works

MCP servers expose capabilities through the protocol to connect Kombai with external tools or data sources. Kombai supports three transport methods: stdio, SSE, and streamable HTTP.

Installing MCP servers

Open the MCP server settings

Click the icon in the top bar to open the Settings page, then select the External MCP Servers tab from the left menu.

Open the MCP configuration file

Click the + Add MCP button to open the mcp.json file.

Configure your MCP server

Add your MCP server configuration inside the mcpServers object and save the file. The mcpServers wrapper is optional: Kombai also reads servers listed at the top level of the file. The file can contain comments.See the examples below for common server configurations.

Verify your MCP server

After saving, the External MCP Servers tab will display your configured server along with its connection status.

Examples

Set up custom MCP servers using a JSON configuration file:

CLI Server - Node.js

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

CLI Server - Python

{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Remote Server

// MCP server using HTTP or SSE - hosted on a server
{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

Static OAuth for remote servers

For MCP servers that rely on OAuth, you can supply static OAuth client credentials in mcp.json rather than using dynamic client registration. This is useful when:

The MCP provider supplies you with a fixed Client ID (and optionally a Client Secret)
The provider requires whitelisting a redirect URL (e.g. Figma, Linear). Use http://127.0.0.1:19876/mcp/oauth/callback.
The provider does not support OAuth 2.0 Dynamic Client Registration

Remote Server with Static OAuth

Include an auth object in remote server entries that specify a url:

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Field	Required	Description
CLIENT_ID	No	OAuth 2.0 Client ID provided by the MCP provider
CLIENT_SECRET	No	OAuth 2.0 Client Secret, for providers that use confidential clients. Used only when `CLIENT_ID` is also set.

If you leave out CLIENT_ID, Kombai registers itself with the provider through OAuth 2.0 Dynamic Client Registration.

Values are used literally

Kombai uses the values in mcp.json exactly as written. It doesn’t expand variable references such as ${env:MCP_CLIENT_ID}, so write the actual value. In a chat with the Kombai Agent, a stdio server process also inherits Kombai’s environment variables, so a key it reads from the environment doesn’t need to be in mcp.json. Codex starts servers with a minimal environment, so for chats that use Codex, put every variable the server needs in env.

STDIO server configuration

For STDIO servers (local command-line servers), set the following fields in your mcp.json:

Field	Required	Description	Examples
type	No	Accepted for compatibility and ignored. Kombai treats any entry with a `command` as a stdio server.	`"stdio"`
command	Yes	Command to launch the server executable. Must be accessible on your system path or specified as a full path. Can also be an array of the command and its arguments.	`"npx"`, `"node"`, `"python"`, `"docker"`
args	No	Array of arguments passed to the command	`["server.py", "--port", "3000"]`
env	No	Environment variables for the server process, added to the ones it inherits from Kombai. `environment` is accepted as an alias.	`{"API_KEY": "<YOUR_API_KEY>"}`
timeout	No	Timeout in milliseconds. See Timeouts.	`120000`

Remote server configuration

For remote servers, set the following fields:

Field	Required	Description
url	Yes	URL of the server’s endpoint
type	No	`"streamable-http"` or `"sse"` to force a transport. If left out, Kombai tries streamable HTTP first, then SSE. Codex chats skip servers set to `"sse"`.
headers	No	HTTP headers sent with every request
auth	No	Static OAuth client credentials. See Static OAuth for remote servers.
timeout	No	Timeout in milliseconds. See Timeouts.

Timeouts

What timeout controls depends on the agent running the chat:

Kombai Agent: How long Kombai waits to connect to the server and load its tools. Defaults to 60000. It doesn’t apply to tool calls, which time out after 60 seconds by default.
Claude Code and Codex (Local agents): How long each tool call can take. Defaults to 120000.

Configuration locations

Project Configuration

Place .kombai/mcp.json in your project root for project-specific tools.

Global Configuration

Place ~/.kombai/mcp.json in your home directory for tools accessible across all projects.

If both files define a server with the same name, the project entry is used. The + Add MCP button opens the global file.

Manage servers

Each server on the External MCP Servers tab shows its status and a badge for where it’s configured: Project for the project file, or User for the global file. Hover over a server for these actions:

Reconnect server: reconnect to the server.
Edit mcp.json: open the configuration file that defines the server.
Remove server: delete the server’s entry from that file and sign out of the server.

Use the toggle next to a server to disable or enable it. Disabling a server keeps its entry in mcp.json. To turn off individual tools, click a connected server to expand it, then click a tool to disable it. Click it again to enable it. If the server’s status reads Needs authentication, click Sign in to sign in to the provider in your browser. The other statuses are Connected, Connecting…, Disabled, Failed, and Needs client ID. If mcp.json can’t be parsed, the tab shows an Invalid mcp.json banner with the error.

Get Started

Features

Browser

Context

Kombai for Teams

Design Mode

Account

Troubleshooting

How it works

Installing MCP servers

Examples

CLI Server - Node.js

CLI Server - Python

Remote Server

Static OAuth for remote servers

Remote Server with Static OAuth

Values are used literally

STDIO server configuration

Remote server configuration

Timeouts

Configuration locations

Project Configuration

Global Configuration

Manage servers

​How it works

​Installing MCP servers

​Examples

​CLI Server - Node.js

​CLI Server - Python

​Remote Server

​Static OAuth for remote servers

​Remote Server with Static OAuth

​Values are used literally

​STDIO server configuration

​Remote server configuration

​Timeouts

​Configuration locations

Project Configuration

Global Configuration

​Manage servers

How it works

Installing MCP servers

Examples

CLI Server - Node.js

CLI Server - Python

Remote Server

Static OAuth for remote servers

Remote Server with Static OAuth

Values are used literally

STDIO server configuration

Remote server configuration

Timeouts

Configuration locations

Manage servers