---
title: "Connect to an AI agent"
url: "https://docs.mekodata.ai/integrations/connect-to-ai-agent/"
---

# Connect to an AI agent

Integrate Meko with Cursor, Claude Desktop, Claude Code, Codex, Kiro, OpenCode, and more

Integrate with AI agents for interactive use cases, such as saving personal, team, and organizational preferences, standards, and policies.

Free tier

Every MCP call from an external client counts toward your account's Free tier quotas (conversations, retrievals, and related caps). See [Meko pricing](https://mekodata.ai/pricing/) for plan details.

## Before you connect

Every client uses the MCP server URL `https://mcp.mekodata.ai/mcp`. The **Datapacks > Connect** dialog also shows this URL.

The automated installer requires Node.js 20.18.1 or newer.

The installer stores an API key in the client. You can let installer 2.5.0 create that key, or paste one you already have.

- **Browser sign-in (installer):** In a terminal, run the installer with no `--api-key` and with `MEKO_API_KEY` unset. A command that includes `--url` opens the Meko sign-in page and creates a key. A command with no `--url` asks you to choose **Sign in with browser** or **Paste an API key**. Sign in with the same method you use for the portal. The key is named `Meko installer (<computer>) <time>`, counts toward your 10 active keys, and expires after one year. Manage it under **Settings > API Keys**. `--no-browser` prints the URL instead of opening a browser. A run with no terminal, such as CI, does not open a browser and still needs a key. `--yes` in a terminal still signs in through the browser.
- **API key you create:** In the portal, open **Settings > API Keys > Generate API key**. Name the key, then copy or download it before you close the dialog. The key starts with `mko_tkn_`, and Meko shows it only once. In the instructions below, replace `<paste-your-api-key>` with this key. The **Connect** dialog still shows a command that includes `--api-key`.
- **OAuth:** Add the MCP server URL without an API key or authentication headers. The client opens your browser so you can sign in to the Meko portal. OAuth works only when the client registers a callback that Meko accepts. Use an API key for command-line clients and Kiro. Browser sign-in is not this OAuth path: the installer discards the sign-in session and keeps only the API key.

Use a pasted API key for CI and scripts. Command-line OAuth uses a local callback that Meko currently rejects, and unattended clients can't open a browser when an OAuth session expires.

Don't configure OAuth and an API key for the same client. The client may choose OAuth and ignore your API key.

For the full workflow, see [MCP server URL](/integrations/#mcp-server-url) and [Choose an authentication method](/integrations/#choose-an-authentication-method).

### OAuth and Manual setup

When you connect with OAuth or using the Manual setup, your agent interacts with Meko *on demand* only: you need to mention "Meko" in your prompt (for example, *"save this to Meko,"* *"search my Meko knowledge base"*) for the agent to call the tools. The agent won't proactively save conversations or capture memories *unless you ask.*

To get automatic behavior, use the **Automated setup** instead, or write your own skills to teach your agent when to call Meko tools. Claude Desktop has no session hooks, so its automatic capture still depends on the model. See [Claude Desktop](#claude-desktop).

## Cursor Desktop

##### Automated setup

In the Meko portal, select **Connect** and follow the steps.

##### OAuth

In Cursor Desktop:

1. Open **Cursor > Settings > Cursor Settings > Tools & MCPs > New MCP Server**.
2. Add to `mcp.json` without any auth headers:
   
   ```json
   {
     "mcpServers": {
       "meko": {
         "url": "https://mcp.mekodata.ai/mcp"
       }
     }
   }
   ```
3. Complete the OAuth handshake when the browser opens.

##### Manual setup

In Cursor Desktop:

1. Choose **Cursor>Settings>Cursor Settings>Tools & MCPs>New MCP Server**.
2. Modify the `mcp.json` file that Cursor opens to add the following MCP server configuration.
   
   ```json
   {
     "mcpServers": {
       "meko": {
         "url": "https://mcp.mekodata.ai/mcp",
         "headers": {
           "Authorization": "Bearer <paste-your-api-key>",
           "User-Agent": "meko-mcp-installer/1.0"
         }
       }
     }
   }
   ```
   
   Replace `<paste-your-api-key>` with the API key you saved from **Settings>API Keys**. Keep the `Bearer` prefix, and keep the `User-Agent` header — see [Choose an authentication method](/integrations/#choose-an-authentication-method).
   
   The result should look like the following:
   
   ![Cursor Desktop](/images/integrations-cursor-settings.png)
3. Verify the Connection by entering the following in chat.
   
   ```text
   List my datapacks in Meko
   ```

## Cursor Web

Coming soon

This section is under development. Check back soon.

## Claude Desktop

Pick a method to connect the MCP server.

Install Method Use when Builds skills files 

1\. Automated installer You want Claude to follow Meko guidance Yes  
You must still import them 

2\. Desktop extension You want the MCP server without a terminal No 

3\. OAuth You want OAuth, or you want to edit the config yourself No 

4\. Manual You want to edit the config yourself No

Only the automated installer builds the Desktop skills. The skills are `meko-mcp-tools-desktop` and `meko-select-datapack-desktop`; the second skill keeps a pinned datapack across chats. They tell Claude when to call Meko tools. Without them, Claude calls Meko only when you ask.

Automatic capture

Claude Desktop has no session hooks, so even with the skills installed, automatic capture depends on the model you are using. If Claude recalls memories but doesn't save new ones, see [Troubleshooting](/troubleshooting/#common-problems-installing-and-connecting).

##### Automated setup

Remove the Desktop extension in **Settings > Extensions** before you run the installer. Otherwise you can end up with the extension and a second MCP server entry.

The installer asks before it replaces an entry it finds in `claude_desktop_config.json`, but it doesn't remove the extension.

To run the automated setup:

1. In the Meko portal, select **Connect** and follow the steps.
   
   Alternately, run the following command:
   
   ```sh
   npx @yugabytedb/meko-mcp@latest --client claude-desktop --url "https://mcp.mekodata.ai/mcp"
   ```
   
   With `MEKO_API_KEY` unset, the installer opens your browser and creates an API key. If `MEKO_API_KEY` is already set, it uses that key and does not open a browser. To use a key you already saved, add `--api-key <paste-your-api-key>`. See [Before you connect](#before-you-connect).
   
   The installer writes `mcpServers.meko` in `claude_desktop_config.json`, builds two `.skill` files, `meko-mcp-tools-desktop.skill` and `meko-select-datapack-desktop.skill`, and prints a path for each on a line that starts with `Built Meko skill bundle:`.
   
   Claude Desktop has no API the installer can use to import skills, so you must import both files.
2. Import the skills files into Claude Desktop by dragging each file onto the Claude Desktop window, or using **Settings > Skills**.
3. Quit and restart Claude Desktop.
4. Ask Claude:
   
   ```text
   Which Meko skills do you have available?
   ```
   
   The reply should name `meko-mcp-tools-desktop` and `meko-select-datapack-desktop`.

When upgrading the installer, run the installer again and import the new `.skill` files. Desktop keeps using the copies you already imported until you replace them.

##### Desktop extension

The `.mcpb` extension installs the MCP server only. It doesn't install the skills.

You need Node.js 20.18.1 or newer on your `PATH`. The extension runs `npx mcp-remote`.

1. Download [meko-2.5.1.mcpb](/downloads/meko-2.5.1.mcpb). This is the Desktop extension for installer 2.5.1, the same version as `npx @yugabytedb/meko-mcp@2.5.1`. The extension asks you to paste an API key. It does not sign in through the browser.
2. In Claude Desktop, open **Settings > Extensions > Install from file** and select the file. You can also drag the file onto that pane.
3. When prompted, paste `https://mcp.mekodata.ai/mcp` and your API key.
4. Quit and restart Claude Desktop.
5. Verify the connection:
   
   ```text
   List my datapacks in Meko
   ```

##### OAuth

In Claude Desktop:

1. Navigate to **Settings**, and under **Customize** select **Connectors**.
2. Search for **Meko** in the Connectors search box, and add it as a custom MCP connector with the URL `https://mcp.mekodata.ai/mcp`.
3. Complete the OAuth handshake when the browser opens.

##### Manual setup

In Claude Desktop (whether used for Chat, Cowork, or Code):

1. Navigate to **Settings**, and under **Desktop app** select **Developer**, then click **Edit Config**.
2. Edit the `claude_desktop_config.json` file to add the following MCP Server entry. Replace `<paste-your-api-key>` with the token you saved.
   
   ```json
   {
     "mcpServers": {
       "meko": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote@0.1.38",
           "https://mcp.mekodata.ai/mcp",
           "--transport",
           "http-only",
           "--header",
           "Authorization:${AUTH_HEADER}",
           "--header",
           "User-Agent:meko-mcp-installer/1.0"
         ],
         "env": {
           "AUTH_HEADER": "Bearer <paste-your-api-key>"
         }
       }
     }
   }
   ```
   
   **Why split the key between `args` and `env`:** The `Bearer <key>` header value contains a space. Environment variable values can safely contain spaces, but some clients mishandle spaces in `args` entries. The configuration keeps the argument space-free as `Authorization:${AUTH_HEADER}` and stores `Bearer <key>` in `env`. This is the pattern `mcp-remote` expects.
   
   **How the substitution works:** Claude Desktop doesn't expand `${AUTH_HEADER}`. It passes the `args` array as written and sets `AUTH_HEADER` in the `mcp-remote` process environment. When `mcp-remote` parses the `Authorization` header, it replaces `${AUTH_HEADER}` with the `Bearer <key>` value.
   
   **Why the name matters:** `mcp-remote` substitutes only environment variables that are explicitly referenced in `args`. The `AUTH_HEADER` name in `env` must match `${AUTH_HEADER}` in `args`. A different or unreferenced variable name doesn't authenticate the connection.
3. Quit and restart Claude Desktop.
   
   The result should look like the following:
   
   ![Claude Desktop](/images/integrations-claude-desktop.png)
   
   Handling errors
   
   If you see errors when restarting Claude, examine the log file that appears. Verify that you have the correct version of node.js binaries in your path, use absolute paths, and consult online MCP Server configuration troubleshooting guides.
4. Verify the connection by entering the following in chat:
   
   ```text
   List my datapacks in Meko
   ```

### Uninstall

How you remove Meko from Claude Desktop depends on how you installed it, because each installation method creates a different artifact.

##### Automated setup

Run the following:

```bash
npx @yugabytedb/meko-mcp@latest --client claude-desktop --uninstall
```

If you installed under a non-default server name, pass `--server-name <name>`. The uninstall removes only that MCP server entry. If you imported the skill files, remove `meko-mcp-tools-desktop` and `meko-select-datapack-desktop` in **Settings > Skills**.

##### Desktop extension

In Claude Desktop, open **Settings > Extensions** and remove the Meko extension. If you imported the skill files, remove them in **Settings > Skills**.

##### OAuth

In Claude Desktop:

1. Navigate to **Settings**, and under **Customize** select **Connectors**.
2. Search for **Meko** in the Connectors search box and delete it.

##### Manual setup

In Claude Desktop:

1. Navigate to **Settings**, and under **Desktop app** select **Developer**, then click **Edit Config**.
2. Edit the `claude_desktop_config.json` file to delete the `mcpServers.meko` entry.
3. Restart Claude Desktop.

## Claude Code

##### Automated setup

In the Meko portal, select **Connect** and follow the steps.

##### OAuth

1. Run the setup command in your shell to add the Meko MCP server:
   
   ```sh
   claude mcp add --scope user --transport http meko https://mcp.mekodata.ai/mcp
   ```
2. Complete the OAuth handshake when the browser opens.

##### Manual setup

1. Run the setup command in your shell to add the Meko MCP server to Claude Code:
   
   ```sh
   claude mcp add --scope user --transport http meko https://mcp.mekodata.ai/mcp \
     --header "Authorization: Bearer <paste-your-api-key>" \
     --header "User-Agent: meko-mcp-installer/1.0"
   ```
   
   Replace `<paste-your-api-key>` with the API key you saved from **Settings>API Keys**. Keep the `Bearer` prefix — see [Choose an authentication method](/integrations/#choose-an-authentication-method).
2. Verify the connection by entering the following at the command-line console:
   
   ```txt
   List my datapacks in Meko
   ```

### Updating the skills plugin

Skill content (the behavioral guides that teach the agent how to use Meko's MCP tools) ships in the `meko-agent-skills` plugin and versions independently of the MCP server. The marketplace source is `https://github.com/yugabyte/meko-skills.git`.

##### Inside an active Claude Code session

```text
/plugin marketplace update meko-agent-skills
/plugin update meko-agent-skills@meko-agent-skills
/reload-plugins
```

If `/reload-plugins` warns that it would re-read the conversation, rerun it as `/reload-plugins --force`. Then run `/doctor` to confirm there are no plugin load errors.

##### From the shell

```sh
claude plugin marketplace update meko-agent-skills
claude plugin update meko-agent-skills@meko-agent-skills
```

The qualified `plugin@marketplace` form is required. Re-running the installer (`npx @yugabytedb/meko-mcp@latest`) updates an existing install. That rerun is what installs capture repair. For Claude Code, pass `--statusline` on a one-liner that already includes `--url`, or accept the status line prompt when you run the installer with no `--url`. Updating only the skills plugin does not add the capture status text.

##### Enable auto-update

Auto-update is per-marketplace and **disabled by default** for third-party marketplaces. To opt in:

1. Open `/plugin`, switch to the **Marketplaces** tab, select `meko-agent-skills`, and toggle **Enable auto-update**.
2. Or add `"autoUpdate": true` to the existing `meko-agent-skills` entry in `~/.claude/settings.json` (user scope) or a project's `.claude/settings.json`. Keep the `source` field — an `autoUpdate`-only replacement drops the marketplace source:
   
   ```json
   {
     "extraKnownMarketplaces": {
       "meko-agent-skills": {
         "source": {
           "source": "git",
           "url": "https://github.com/yugabyte/meko-skills.git"
         },
         "autoUpdate": true
       }
     }
   }
   ```

Once enabled, Claude Code refreshes the marketplace and updates installed plugins in the background after startup. The running session keeps the versions it loaded at launch; you'll be prompted to `/reload-plugins`, or the new versions load on the next launch.

## Open AI Codex Desktop

##### Automated setup

In the Meko portal, select **Connect** and follow the steps.

When you provide an API key on macOS, the installer adds `MEKO_API_KEY` to the launchd environment used by apps opened from Spotlight or Alfred. Quit every running Codex process and relaunch Codex after installation. A running process keeps the environment it had when it started.

##### OAuth

In Codex Desktop:

1. Choose **Codex>Settings>MCP servers>Add server>Streamable HTTP**.
2. Enter the URL `https://mcp.mekodata.ai/mcp` and leave the Bearer token field empty.
3. Click **Authenticate** beside Meko in the list of MCP servers and complete the OAuth handshake when the browser opens.

##### Manual setup

In Codex Desktop:

1. Choose **Codex>Settings>MCP servers>Add server>Streamable HTTP**.
2. Enter a name for the Meko MCP server.
3. Enter the Meko MCP server URL (`https://mcp.mekodata.ai/mcp`).
4. Enter a name (such as `MEKO_MCP_TOKEN`) for the Bearer token environment variable, and click **Save**.
   
   The result should look like the following:
   
   ![Codex Desktop](/images/integrations-codex-desktop.png)
5. Set the `MEKO_MCP_TOKEN` environment variable with your Meko API key in your terminal using the following command:
   
   ```sh
   launchctl setenv MEKO_MCP_TOKEN <paste-your-api-key>
   ```
6. Verify that you set `MEKO_MCP_TOKEN` correctly with your API key.
   
   ```sh
   launchctl getenv MEKO_MCP_TOKEN
   ```
7. Quit and restart Codex Desktop.
8. Verify the connection by entering the following in chat:
   
   ```text
   List my datapacks in Meko
   ```

## Kiro IDE and CLI

Kiro IDE and `kiro-cli` share their MCP configuration, skills, and hooks. One install configures both:

```bash
npx @yugabytedb/meko-mcp@latest --client kiro
```

The `kiro-cli` and `kiro-ide` aliases run the same install. If you set `$KIRO_HOME`, the installer uses that directory instead of `~/.kiro`.

The command above has no `--url`, so the installer asks for the MCP URL, then asks you to choose **Sign in with browser** or **Paste an API key**. Either way Kiro stores an API key. Kiro's own OAuth callback is rejected, so don't add an OAuth connector for Kiro. The installer also installs the Meko skill, steering, and both Kiro hook formats for durable capture.

### Manual setup

If you only need an on-demand MCP connection, add this entry to `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "meko": {
      "url": "https://mcp.mekodata.ai/mcp",
      "headers": {
        "Authorization": "Bearer <paste-your-api-key>",
        "User-Agent": "meko-mcp-installer/1.0"
      }
    }
  }
}
```

Replace `<paste-your-api-key>` with the key you saved from **Settings > API Keys**, then protect the file because it contains the key:

```bash
chmod 600 ~/.kiro/settings/mcp.json
```

Manual setup doesn't install the Meko skill, steering, or capture hooks. Use the automated installer when you want Meko to capture conversations and apply its behavioral guidance.

Kiro hooks expose user prompts and final assistant responses. They don't expose tool calls or hidden reasoning, so those details aren't included in automatic capture.

### Uninstall

```bash
npx @yugabytedb/meko-mcp@latest --client kiro --uninstall
```

## OpenCode CLI and TUI

The installer supports OpenCode CLI and TUI 1.18.x. Choose one installation scope:

- **User scope** makes Meko available in every OpenCode project.
- **Project scope** installs Meko only in the current project.

Use only one scope for a project.

##### User scope

```bash
npx @yugabytedb/meko-mcp@latest --client opencode --scope user
```

##### Project scope

Run this command from the project root:

```bash
npx @yugabytedb/meko-mcp@latest --client opencode --scope project
```

These commands omit `--url`, so the installer asks for the MCP URL, then asks you to choose **Sign in with browser** or **Paste an API key**. If `MEKO_API_KEY` is already set, it uses that key and skips the question. It installs the Meko skill and adds an installer-owned plugin. The plugin supplies the MCP configuration when OpenCode starts, so the installer doesn't rewrite `opencode.json` or `opencode.jsonc`. It stores the API key in a private file with mode `0600`.

The first OpenCode start after install can take up to 2 minutes while OpenCode installs its plugin. The installer says why it is waiting.

Restart OpenCode after installation, then verify the connection:

```text
List my datapacks in Meko
```

OpenCode automatically captures visible user text and the first visible assistant message for each completed turn. It doesn't capture tool calls, hidden reasoning, files, attachments, or streaming output. Check queued work with:

```bash
npx @yugabytedb/meko-mcp@latest --capture-status
```

To preview and import existing local OpenCode sessions:

```bash
npx @yugabytedb/meko-mcp@latest --migrate --dry-run
npx @yugabytedb/meko-mcp@latest --migrate
```

Migration imports local root sessions returned by the OpenCode CLI. OpenCode 1.18.x doesn't expose child sessions through that interface. Installer 2.5.0 doesn't support OpenCode Desktop, V2 preview APIs, or headless or remote sessions. OpenCode capture uses your account's default datapack and doesn't read the pin. `--datapack` applies to `--migrate` only.

### Uninstall

Uninstall using the same scope you used during installation. For user scope, run:

```bash
npx @yugabytedb/meko-mcp@latest --client opencode --scope user --uninstall
```

For a project installation, run the command from the project root and replace `--scope user` with `--scope project`. Uninstall removes installer-owned configuration and credentials. It keeps queued capture data so you can recover unsent exchanges.

## VS Code

1. Run the following command:
   
   ```sh
   echo "### Installing the latest Node.js ###"
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
   source ~/.$(basename $SHELL)rc
   nvm install --lts
   echo "### Registering the Meko MCP server ###"
   npx mcp-add@latest \
     --name meko \
     --type http \
     --url 'https://mcp.mekodata.ai/mcp' \
     --headers 'Authorization=Bearer <paste-your-api-key>,User-Agent=meko-mcp-installer/1.0' \
     --scope global \
     --clients 'vscode'
   ```
   
   VS Code can connect to a remote MCP server on its own, so this registers the URL and its headers directly. Unlike Claude Desktop, it needs no local `mcp-remote` helper.
   
   Replace `<paste-your-api-key>` with the API key you saved from **Settings>API Keys**.
2. Verify the connection by entering the following in chat:
   
   ```text
   List my datapacks in Meko
   ```