# Connect an AI Client

Follow the steps for your AI client below. All clients connect to the same server URL: `https://mcp.us-1.kognitos.com/`.

## Prerequisites

* A Kognitos account
* One of the supported MCP clients installed
* An [API key](https://docs.kognitos.com/guides/api-reference/api-keys) *(only if you plan to authenticate with a key instead of OAuth)*

## Claude Desktop

{% stepper %}
{% step %}
**Open the configuration file**

On your machine, open the Claude Desktop configuration file:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

If the file does not exist, create it with an empty `{}` object.
{% endstep %}

{% step %}
**Add the Kognitos server**

Add the `kognitos` entry to the `mcpServers` object. Choose the tab that matches your preferred authentication method.

{% tabs %}
{% tab title="OAuth" %}

```json
{
  "mcpServers": {
    "kognitos": {
      "url": "https://mcp.us-1.kognitos.com/",
      "oauth": {
        "callbackPort": 3777
      }
    }
  }
}
```

{% endtab %}

{% tab title="API Key" %}

```json
{
  "mcpServers": {
    "kognitos": {
      "url": "https://mcp.us-1.kognitos.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Restart Claude Desktop**

Quit and reopen Claude Desktop. The first time you use a Kognitos tool with the OAuth variant, your browser will open to the Kognitos login screen. Sign in and approve the connection.
{% endstep %}

{% step %}
**Verify the connection**

In a new Claude Desktop chat, send:

> *List my Kognitos workspaces.*

Claude will use the `kognitos_list_workspaces` tool to respond. If the tool does not appear to run, see the sign-in note below.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
If your OAuth session expires, Claude Desktop will prompt you to sign in again the next time you use a Kognitos tool. No configuration change is needed.
{% endhint %}

## Claude Code

{% stepper %}
{% step %}
**Add the MCP server**

Run one of the following commands from your terminal.

{% tabs %}
{% tab title="OAuth" %}

```bash
claude mcp add --transport http --callback-port 3777 kognitos https://mcp.us-1.kognitos.com/
```

{% endtab %}

{% tab title="API Key" %}

```bash
claude mcp add --transport http kognitos https://mcp.us-1.kognitos.com/ \
  --header "Authorization: Bearer YOUR_API_KEY"
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Verify the connection**

List your configured MCP servers to confirm `kognitos` is registered:

```bash
claude mcp list
```

Then start Claude Code and send:

> *List my Kognitos workspaces.*

If you chose OAuth, Claude Code opens your browser on the first tool call so you can sign in and approve the connection.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
The `--callback-port 3777` flag (or `callbackPort` in Claude Desktop) tells the client which port to use for the OAuth callback. This port is pre-registered with the Kognitos authentication service. Omitting it may cause a "Callback URL mismatch" error during sign-in.
{% endhint %}

## Claude.ai

{% stepper %}
{% step %}
**Open Connectors**

In Claude.ai, open **Settings** → **Connectors**.
{% endstep %}

{% step %}
**Add the Kognitos connector**

Click <kbd>**Add custom connector**</kbd> and fill in the form:

* **Name**: `Kognitos`
* **Remote MCP server URL**: `https://mcp.us-1.kognitos.com/`

Leave the other fields at their defaults. The server URL is the only value you need to provide. Claude.ai discovers the rest automatically.
{% endstep %}

{% step %}
**Sign in to Kognitos**

Click <kbd>**Connect**</kbd>. Claude.ai will redirect you to the Kognitos login screen. Sign in with your Kognitos account and approve the connection.

You do not share any Kognitos credentials with Claude.ai. Authentication happens in your browser, and Claude.ai only receives a short-lived access token tied to your user account.
{% endstep %}

{% step %}
**Verify the connection**

Start a new chat, enable the **Kognitos** connector in the chat composer, and send:

> *List my Kognitos workspaces.*
> {% endstep %}
> {% endstepper %}

## Other MCP clients

The Kognitos MCP server uses the standard Streamable HTTP transport and works with any compliant MCP client, including Cursor, Visual Studio Code, and Windsurf. In the client's MCP configuration, use:

* **Server URL**: `https://mcp.us-1.kognitos.com/`
* **Transport**: Streamable HTTP
* **Authentication**: OAuth (automatic discovery) or an `Authorization: Bearer YOUR_API_KEY` header
* **OAuth callback port**: `3777` (configure in your client's MCP settings when using OAuth)

Refer to your client's documentation for where to enter these values.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/guides/mcp/clients.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.