Subio MCP

What is a Bubble?

A Bubble is a group of independent internet conversations converging around the same emerging topic. Subio collects public signals, removes noise, groups related discussions, scores momentum, and preserves the sources behind every result.

This MCP server lets your AI client ask questions such as:

• “What are today’s strongest Bubbles for my workspace?”
• “Why is this conversation growing?”
• “Which of my opportunities is worth acting on?”
• “Turn this opportunity into an evidence-based X post.”

Tools

It also exposes subio://workspace/profile, a non-sensitive MCP resource containing the company and audience context used for personalization.

Bubbles cannot yet be filtered or searched server-side beyond pagination - get_bubbles returns them in the order your workspace ranks them.

Quick start

No-code installation

Download the instruction file for Claude, Codex, Cursor, or another AI agent, attach it to your agent, and say: “Install Subio MCP for me and verify it works.” The agent will handle the configuration and ask only for your Subio MCP access token.

Requirements

• Node.js 20 or newer
• A Subio workspace
• An MCP access token, issued from Subio under Connections > MCP

The token is shown only once. Never commit it to a repository or paste it into a prompt.

If you run npx -y subio-mcp without a token in an interactive terminal, the command opens subio.space so you can sign in and create one. Add it to your MCP client as SUBIO_MCP_TOKEN, then run the command again.

Claude Desktop

Open Claude Desktop settings, choose Developer → Edit Config, and add:

{
  "mcpServers": {
    "subio": {
      "command": "npx",
      "args": ["-y", "subio-mcp"],
      "env": {
        "SUBIO_MCP_TOKEN": "your_workspace_mcp_token"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Copy examples/claude-code.mcp.json to .mcp.json in your project, replace the placeholder, then start Claude Code.

Codex

codex mcp add subio \
  --env SUBIO_MCP_TOKEN=your_workspace_mcp_token \
  -- npx -y subio-mcp

Or copy the TOML from examples/codex.config.toml into ~/.codex/config.toml.

Cursor

Copy examples/cursor.mcp.json to .cursor/mcp.json in your project and replace the placeholder.

Any MCP client

Use the standard stdio transport:

command: npx
args: -y subio-mcp

Set SUBIO_MCP_TOKEN in the server environment.

Verify the connection

Run the built-in doctor before configuring your client:

SUBIO_MCP_TOKEN=your_workspace_mcp_token \
npx -y subio-mcp doctor

Architecture

Claude / Codex / Cursor / MCP client
                 │
                 │ stdio
                 ▼
             Subio MCP server
                 │
                 │ HTTPS + workspace-scoped bearer token
                 ▼
              Subio API (/v1/mcp/*)
              ├─ this workspace's ranked Bubbles
              ├─ this workspace's opportunities
              ├─ evidence-based content drafts
              └─ workspace profile

The open-source package is intentionally thin. It does not contain scraper credentials, database access, private scoring prompts, or provider secrets.

Security

• The MCP token is issued by Subio itself (not pasted in from elsewhere) and resolves server-side to exactly one workspace - there is nothing else for the client to configure or scope by.
• Credentials are read from the MCP process environment, never from tool arguments.
• The token is sent only to the configured Subio API over HTTPS.
• Non-HTTPS remote API URLs are rejected.
• The package has no telemetry and does not persist conversation data.
• Errors never include the token.
• Generated content remains a draft and is never auto-published.
• Tokens are workspace-scoped and can be rotated or revoked independently by disconnecting MCP in Subio.

Read the full policy in SECURITY.md.

Local development

git clone https://github.com/alijancb/subio-mcp.git
cd subio-mcp
pnpm install
cp .env.example .env
pnpm check

Run locally:

SUBIO_MCP_TOKEN=your_workspace_mcp_token \
pnpm dev

Project principles

1. Evidence before summaries.
2. Read-only by default.
3. No publishing without explicit user action.
4. No provider secrets in the open-source client.
5. Stable tools that work across MCP clients.

License

MIT © 2026 Subio.