Semble MCP

Connect your agent to Semble's MCP server.

What Can You Do?

The Semble MCP server lets you interact with Semble through you AI agent in a conversational way.

You can ask things like: - "What's been happening in my network recently?" - "Go through all my uncollected cards and suggest collections to add them to." - "who are the top curators on the future of open social? Are there any collections I should subscribe to?" If anything interesting comes up, you can take actions directly in the chat, save cards, follow collections, build connections, and anything else you can do in the app.

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.

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):

{
  "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.

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.

{
  "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)

{
  "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)

{
  "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):

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.

{
  "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

{
  "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 as a bridge:

{
  "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.