> For the complete documentation index, see [llms.txt](https://docs.cosmik.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cosmik.network/semble-mcp/semble-mcp.md).

# Semble MCP

## Connecting Your Agent to Semble MCP

Every Semble MCP connection uses the same three pieces of info:

| Setting         | Value                       |
| --------------- | --------------------------- |
| **Server URL**  | `https://api.semble.so/mcp` |
| **Transport**   | Streamable HTTP (stateless) |
| **Auth header** | `X-API-Key: sk_...`         |

Get your API key at [semble.so/settings/api-keys](https://semble.so/settings/api-keys).

> **OAuth-only clients** (Claude Desktop, ChatGPT) cannot use API-key auth directly. See their specific sections below — they require either a bridge or an OAuth layer.

***

### Claude Code (Plugin)

The Semble Claude Code plugin handles API key storage in your OS keychain and includes skills for deep research and activity digests.

**Via marketplace:**

```
/plugin marketplace add https://raw.githubusercontent.com/cosmik-network/semble-claude-plugin/main/marketplace/marketplace.json
/plugin install semble
```

You'll be prompted for your Semble API key on enable. It's stored in your OS keychain and sent as the `X-API-Key` header — never written to disk in plaintext.

**Manual config** (`.mcp.json`, if you prefer not to use the plugin):

```json
{
  "mcpServers": {
    "semble": {
      "type": "streamableHttp",
      "url": "https://api.semble.so/mcp",
      "headers": {
        "X-API-Key": "sk_your_key_here"
      }
    }
  }
}
```

> **Skills** (semble-getting-started, semble-deep-research, semble-activity-digest) are only available through the plugin install, not the manual config.

***

### Claude Desktop (Desktop Extension)

Claude Desktop's Custom Connectors only support OAuth — it cannot send API-key headers to a remote server directly. The Semble desktop extension works around this by running a thin local bridge (`mcp-remote`) that injects your key.

1. Download `semble.mcpb` from the [latest release](https://github.com/cosmik-network/semble-claude-plugin/releases).
2. Double-click it — Claude Desktop opens an install dialog.
3. Enter your Semble API key when prompted (stored in your OS keychain).

The extension forwards requests to `https://api.semble.so/mcp` with your key injected as the `X-API-Key` header.

> Skills are a Claude Code feature and are not available in Claude Desktop.

***

### Cursor

**Config file:** `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project)

Add via UI: **Settings → Tools & MCP → New MCP Server**, or create the file manually.

```json
{
  "mcpServers": {
    "semble": {
      "url": "https://api.semble.so/mcp",
      "headers": {
        "X-API-Key": "sk_your_key_here"
      }
    }
  }
}
```

Restart Cursor after editing the config.

***

### Windsurf (Codeium)

**Config file:** `~/.codeium/windsurf/mcp_config.json` (global only — no per-project support)

```json
{
  "mcpServers": {
    "semble": {
      "serverUrl": "https://api.semble.so/mcp",
      "headers": {
        "X-API-Key": "sk_your_key_here"
      }
    }
  }
}
```

Windsurf supports environment variable interpolation, so you can write `"X-API-Key": "${SEMBLE_API_KEY}"` instead of hardcoding the key.

> **Gotcha:** Windsurf uses `serverUrl` (not `url`) for remote Streamable HTTP servers.

***

### Gemini CLI

**Config file:** `~/.gemini/settings.json` (global) or `.gemini/settings.json` (per-project)

```json
{
  "mcpServers": {
    "semble": {
      "type": "http",
      "url": "https://api.semble.so/mcp",
      "headers": {
        "X-API-Key": "sk_your_key_here"
      }
    }
  }
}
```

**Via CLI command** (alternative to editing JSON):

```bash
gemini mcp add -t http semble https://api.semble.so/mcp --header "X-API-Key: sk_your_key_here"
```

Restart Gemini CLI after adding the config.

***

### Zed

**Config file:** `~/.config/zed/settings.json`

Add via UI: **Settings → AI → MCP Servers → Add Server → Add Remote Server**.

```json
{
  "context_servers": {
    "semble": {
      "url": "https://api.semble.so/mcp",
      "headers": {
        "X-API-Key": "sk_your_key_here"
      }
    }
  }
}
```

> **Note:** Zed uses `context_servers` as the top-level key, not `mcpServers`.

***

### VS Code (GitHub Copilot)

**Config file:** `.vscode/mcp.json` (workspace) or user profile `mcp.json`

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "semble-api-key",
      "description": "Semble API Key",
      "password": true
    }
  ],
  "servers": {
    "semble": {
      "type": "http",
      "url": "https://api.semble.so/mcp",
      "headers": {
        "X-API-Key": "${input:semble-api-key}"
      }
    }
  }
}
```

VS Code uses an `inputs` section to reference secrets without hardcoding them — it prompts for the value on first use and stores it securely.

> **Note:** VS Code uses `"servers"` (not `"mcpServers"`) as the top-level key.

***

### ChatGPT (OpenAI)

ChatGPT requires **OAuth** for remote MCP servers — it does not support API-key auth via headers.

To connect directly, you'd need to implement the MCP OAuth authorization spec on your server. Then users would:

1. Enable Developer Mode: **Settings → Connected Data → Developer mode → Create custom MCP connectors**.
2. Go to **Settings → Connectors → Create**.
3. Enter `https://api.semble.so/mcp` as the server URL.
4. ChatGPT follows the OAuth flow.

Until OAuth is implemented, ChatGPT users cannot connect directly. This is the same limitation your Claude Desktop `.mcpb` bridge solves for that client.

***

### Any Other stdio-Only Client (mcp-remote bridge)

For any client that only supports local `stdio` servers (no remote HTTP support), use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge:

```json
{
  "mcpServers": {
    "semble": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.semble.so/mcp",
        "--header",
        "X-API-Key: sk_your_key_here"
      ]
    }
  }
}
```

This is the same approach the Claude Desktop extension uses internally.

***

### Quick Reference

| Client               | Config file                           | URL field              | Auth method          | Notes                                  |
| -------------------- | ------------------------------------- | ---------------------- | -------------------- | -------------------------------------- |
| **Claude Code**      | `.mcp.json` or plugin                 | `url`                  | `X-API-Key` header   | Plugin recommended (keychain + skills) |
| **Claude Desktop**   | N/A (`.mcpb` install)                 | N/A                    | Bridge injects key   | OAuth-only; use desktop extension      |
| **Cursor**           | `~/.cursor/mcp.json`                  | `url`                  | `headers` object     | Restart after editing                  |
| **Windsurf**         | `~/.codeium/windsurf/mcp_config.json` | `serverUrl`            | `headers` object     | Use `serverUrl`, not `url`             |
| **Gemini CLI**       | `~/.gemini/settings.json`             | `url` + `type: "http"` | `headers` object     | Or use `gemini mcp add` CLI            |
| **Zed**              | `~/.config/zed/settings.json`         | `url`                  | `headers` object     | Key is `context_servers`               |
| **VS Code**          | `.vscode/mcp.json`                    | `url` + `type: "http"` | `headers` + `inputs` | Key is `servers`                       |
| **ChatGPT**          | N/A (UI only)                         | N/A                    | OAuth required       | Needs OAuth impl on server             |
| **Any stdio client** | Client-specific                       | N/A                    | `mcp-remote` bridge  | `npx mcp-remote` as command            |

The main gotchas across clients are the different top-level key names (`mcpServers` vs `servers` vs `context_servers`) and the URL field name (`url` vs `serverUrl`). The auth pattern — a `headers` object with `X-API-Key: sk_...` — is consistent across all coding-agent clients that support remote HTTP.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.cosmik.network/semble-mcp/semble-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.