> ## 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.

# MCP

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

export const MCPServerIcon = props => {
  return <div style={{
    display: "inline",
    justifyContent: "center",
    alignItems: "center"
  }}>
      <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" style={{
    display: "inline"
  }} {...props}>
        <rect width="20" height="8" x="2" y="2" rx="2" ry="2"></rect>
        <rect width="20" height="8" x="2" y="14" rx="2" ry="2"></rect>
        <line x1="6" x2="6.01" y1="6" y2="6"></line>
        <line x1="6" x2="6.01" y1="18" y2="18"></line>
      </svg>
    </div>;
};

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 setting">
    Click the <MCPServerIcon /> icon below the chat input box to open the **MCP Servers** popover. Then Click the **+ Add MCP** button to open the **MCP Servers** tab in the [Settings](/account/settings) page.
  </Step>

  <Step title="Open the MCP server setting">
    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 **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>