@infralayers/pumble-mcp

Universal, production-ready Model Context Protocol (MCP) server for Pumble. It connects autonomous AI agents and LLMs to your Pumble workspace with 100% official REST API coverage (26 tools), sub-millisecond in-memory entity resolution, affirmative execution receipts, and built-in anti-loop security guardrails.

Works seamlessly across Cursor, Cline / Roo Code, Windsurf, Claude Desktop, Claude Code CLI, Google Antigravity, Zed, and any custom agent framework.

Security note: the Pumble API key you configure grants broad, workspace-wide access. Read the Security / Permissions section before installing.

⚡ Highlights & Performance

• 100% Official REST API Coverage: 26 autonomous tools covering messaging, threads, scheduling, reactions, channel operations, user directories, and status updates.

• Ultra-Low Latency (~0.05ms Resolution): Standard API calls take ~1,500ms to resolve user and channel identifiers over the network. Our in-memory RAM cache reduces steady-state lookups to ~0.05ms (30,000x faster), completely eliminating network penalties.

• Boot-Time Prefetching: Users and channels are prefetched in parallel during server startup without blocking the client MCP handshake.

• Write-Through In-Place Updates: Channel creation, member additions/removals, and custom status updates sync directly to the local RAM cache in 0ms.

• Affirmative Execution Receipts: Mutation tools return structured receipts (ok: true, delivered: true, status: "Verification complete") that eliminate compulsive post-action read loops (e.g. list_messages spam).

• Loop-Prevention Circuit Breaker: Finite State Machine (FSM) guardrail locks out speculative reconnaissance and fast-fails missing entities with actionable guidance.

• Security Challenge Gate (AUTH-XXXX): Destructive actions (deleting messages, removing members) require single-use, time-limited confirmation codes, stopping accidental deletions.

Related MCP server: plutio-mcp

💾 Memory Footprint: Scaling in Large Workspaces

A common concern with in-memory caching is memory consumption in large organizations. This server uses an optimized, lean data model that retains only essential routing identifiers (id, name, email for users; id, name, channelType, userIds for channels):

Takeaway: Even in an enterprise workspace with thousands of users and hundreds of channels, the cache consumes less than 5 MB of RAM—a microscopic fraction of Node.js's standard baseline memory (~30 MB). The cache operates with a 60-second TTL, ensuring fresh data without memory leaks or bloat.

🚀 Quick Start (Zero-Install via npx)

Run directly with npx in any MCP-compliant client without cloning or manual building:

Standard MCP Configuration

Works out of the box in Cursor, Cline / Roo Code, Windsurf, Claude Desktop, and Antigravity.

Add this block to your client's MCP configuration file (e.g. claude_desktop_config.json, .cursor/mcp.json, or Cline MCP settings):

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@infralayers/pumble-mcp"],
      "env": {
        "PUMBLE_API_KEY": "<your-pumble-api-key>"
      }
    }
  }
}

CLI Agents (Claude Code, Gemini CLI, Terminal)

Register directly from your shell:

# Claude Code CLI
claude mcp add pumble --env PUMBLE_API_KEY="<your-pumble-api-key>" -- npx -y @infralayers/pumble-mcp

Verify your registered tools:

claude mcp list

🔑 Getting Your Pumble API Key

1. In your Pumble workspace, install the API Key addon (Apps & Integrations).

2. Generate a key from the addon's settings. Pumble shows it once as an ephemeral message — copy it immediately.

3. Pass the key in your client's env configuration as PUMBLE_API_KEY.

🛠️ Complete 26-Tool Reference

Architecture Note: All tools natively accept human-readable fuzzy names, emails, and exact IDs, automatically resolving them via the backend to prevent the AI from wasting context tokens on manual lookups. Ambiguous names will safely throw an error requesting clarification.

1. Messages & Threads (8 Tools)

2. Scheduled Messages (5 Tools)

3. Reactions (2 Tools)

4. Channels & Membership (5 Tools)

5. Workspace, Users & Status (6 Tools)

🛡️ Security / Permissions

This server hands a single static Pumble API key to an MCP server that any connected client or LLM session can invoke. Understand the blast radius before installing:

Blast Radius & Capabilities

The API key inherits the full visibility and privileges of the Pumble user who generated it. It is a password-equivalent secret.

With these twenty-six tools, anyone able to invoke this server can, as you:

• Messages: Read, send, edit, delete, and reply to messages in any channel or DM the key can access.

• Scheduled Messages: Queue messages to post later in any channel or DM, and read, rewrite, redirect, or delete anything already queued.

• Workspace Search: Search across workspace history by text, author, or channel.

• Direct Messages: Send 1-on-1 and group DMs to any user in the workspace.

• User Directory: Enumerate every workspace member's name and email address.

• Channel Membership: Create channels, add users to channels, or remove users from channels.

• Reactions & Status: Add/remove emoji reactions and modify your profile's custom status.

Built-in Agent Defenses

1. Destructive Challenge Gates (AUTH-XXXX): Destructive operations (remove_user_from_channel, delete_scheduled_message, delete_message) cannot be executed speculatively by autonomous agents. If called without human authorization, the server intercepts execution and issues a dynamic 60-second runtime confirmation token challenge requiring human verification.

2. Missing Entity Fast-Fail: Missing users or channels fail immediately with a strict directive stopping partial batches or hallucinations.

Recommendations & Best Practices

• Never commit .env: .env is gitignored by default. Never paste your API key into logs, commit messages, or chat transcripts.

• Key Rotation: If a key is ever exposed, rotate it immediately in Pumble (Apps & Integrations > API Key Addon), update your environment, and revoke the old key.

• Dedicated Service Account: If your Pumble workspace allows it, generate the key from a dedicated service account rather than an individual admin user's personal account.

💻 Local Development

1. Clone & Install

git clone https://github.com/infralayers/pumble-mcp.git
cd pumble-mcp
npm install

2. Configure Environment

The server reads PUMBLE_API_KEY from its environment. It does not load a .env file on its own.

For development, export it in your shell (or add to ~/.bashrc):

export PUMBLE_API_KEY="<your-pumble-api-key>"

3. Development Scripts

npm run dev         # Watch mode via tsx
npm run typecheck   # Typecheck without emitting (tsc --noEmit)
npm test            # Run unit tests via vitest
npm run build       # Compile TypeScript to dist/
npm start           # Run compiled server (node dist/index.js)

To run your local build directly in an MCP client:

{
  "command": "node",
  "args": ["/absolute/path/to/pumble-mcp/dist/index.js"],
  "env": {
    "PUMBLE_API_KEY": "<your-pumble-api-key>"
  }
}

📄 License

MIT License. Copyright (c) 2026 InfraLayers.