> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External MCP Servers

> MCP lets Kombai connect with external systems and data sources. Instead of describing the project structure each time, integrate the tools you already use.

You can build 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:

| Transport       | Execution environment | Deployment       | Users          | Input                   | Auth   |
| --------------- | --------------------- | ---------------- | -------------- | ----------------------- | ------ |
| stdio           | Local                 | Kombai manages   | Single user    | Shell command           | Manual |
| SSE             | Local/Remote          | Deploy as server | Multiple users | URL to an SSE endpoint  | OAuth  |
| Streamable HTTP | Local/Remote          | Deploy as server | Multiple users | URL to an HTTP endpoint | OAuth  |

## Installing MCP servers

<Steps>
  <Step title="Open the MCP server settings">
    Click the <Icon icon="gear" size={18} /> icon in the top bar to open the [Settings](/account/settings) page, then select the **External MCP Servers** tab from the left menu.
  </Step>

  <Step title="Open the MCP configuration file">
    Click the **+ Add MCP** button to open the `mcp.json` file.
  </Step>

  <Step title="Configure your MCP server">
    Add your MCP server configuration inside the `mcpServers` object and save the file.

    See the [examples below](#examples) for common server configurations.
  </Step>

  <Step title="Verify your MCP server">
    After saving, the **External MCP Servers** tab will display your configured server along with its connection status.
  </Step>
</Steps>

### Examples

Set up custom MCP servers using a JSON configuration file:

#### CLI Server - Node.js

```json theme={null}
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}
```

#### CLI Server - Python

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

#### Remote Server

```json theme={null}
// 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)
* 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:

```json theme={null}
{
  "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     | Yes      | OAuth 2.0 Client ID provided by the MCP provider                                                                            |
| CLIENT\_SECRET | No       | OAuth 2.0 Client Secret (applicable when the provider uses confidential clients)                                            |
| scopes         | No       | OAuth scopes to request. If left out, Kombai will use /.well-known/oauth-authorization-server to discover scopes\_supported |

#### Combining with config interpolation

`auth` values support the same interpolation syntax as other fields:

```json theme={null}
{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"
      }
    }
  }
}
```

<Note>
  Instead of hardcoding the Client ID and Client Secret in the `mcp.json` file, it is recommended to use environment variables.
</Note>

## STDIO server configuration

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

| Field   | Required | Description                                                                                                  | Examples                                  |
| ------- | -------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| type    | Yes      | Server connection type                                                                                       | `"stdio"`                                 |
| command | Yes      | Command to launch the server executable. Must be accessible on your system path or specified as a full path. | `"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                                                                 | `{"API_KEY": "${env:api-key}"}`           |

## Configuration locations

<Columns cols={2}>
  <Card title="Project Configuration" icon="folder" color="#6366f1">
    Place `.kombai/mcp.json` in your project root for project-specific tools.
  </Card>

  <Card title="Global Configuration" icon="globe" color="#22c55e">
    Place `~/.kombai/mcp.json` in your home directory for tools accessible across all projects.
  </Card>
</Columns>