Skip to main content

​
Overview

The bloom-mcp package wraps any MCP (Model Context Protocol) server with Bloom’s security layer. This provides:
  • Authentication for every tool call
  • Tool-level permissions (allow/block specific tools)
  • Audit logging of all MCP interactions
  • Kill switch support
Package: bloom-mcp on NPM

​
Quick Start

​
1. Install

npm install -g bloom-mcp

​
2. Configure Environment

export BLOOM_API_KEY="bloom_org_xxxxx"    # From Dashboard > Profile > API Keys
export BLOOM_AGENT_ID="agent_xxxxx"       # From Dashboard > Agents

​
3. Wrap Your MCP Server

# Wrap the GitHub MCP server
npx bloom-mcp secure npx @modelcontextprotocol/server-github

# Wrap any MCP server
npx bloom-mcp secure <your-mcp-server-command>

​
How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Claude/   │────▶│   bloom-mcp  │────▶│  MCP Server │
│   Agent     │     │   wrapper    │     │  (GitHub)   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │   Bloom     │
                    │   Proxy     │
                    └─────────────┘
                           │
              ┌────────────┴────────────┐
              │  • Validate tool call   │
              │  • Check permissions    │
              │  • Log to audit trail   │
              │  • Check kill switch    │
              └─────────────────────────┘

​
Claude Desktop Configuration

Add to your claude_desktop_config.json: 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["bloom-mcp", "secure", "npx", "@modelcontextprotocol/server-github"],
      "env": {
        "BLOOM_API_KEY": "bloom_org_xxxxx",
        "BLOOM_AGENT_ID": "agent_xxxxx",
        "GITHUB_TOKEN": "ghp_xxxxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["bloom-mcp", "secure", "npx", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
      "env": {
        "BLOOM_API_KEY": "bloom_org_xxxxx",
        "BLOOM_AGENT_ID": "agent_xxxxx"
      }
    }
  }
}

​
Tool-Level Permissions

Control which MCP tools your agent can use.

​
Dashboard Configuration

  1. Go to Scopes
  2. Create or edit a scope
  3. Set Scope Type to “MCP”
  4. Configure:
    • Allowed Tools: ["*"] for all, or ["create_issue", "list_repos"]
    • Blocked Tools: ["delete_repo", "force_push"]

​
API Configuration

curl -X POST https://api.bloomtechnologies.app/scopes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-safe",
    "scope_type": "mcp",
    "allowed_tools": ["create_issue", "list_repos", "get_file_contents"],
    "blocked_tools": ["delete_repo", "force_push"]
  }'

​
Permission Logic

1. Check blocked_tools first → if tool in blocked_tools → DENY
2. Check allowed_tools:
   - If ["*"] → ALLOW
   - If tool in allowed_tools → ALLOW
   - Otherwise → DENY

​
Monitoring MCP Calls

​
Dashboard

Go to Activity > MCP Tools tab to see:
  • All tool calls with timestamps
  • Allow/block status for each call
  • Agent and tool name
  • Latency metrics

​
Webhooks

Subscribe to MCP events: 
{
  "events": ["mcp_tool_blocked", "mcp_tool_allowed"]
}
Webhook Payload: 
{
  "event": "mcp_tool_blocked",
  "timestamp": "2026-02-01T15:30:00Z",
  "agent_id": "agent_abc123",
  "data": {
    "tool_name": "delete_repo",
    "mcp_server": "github",
    "reason": "Tool in blocked_tools list",
    "scope_id": "scope_xyz"
  }
}

​
Supported MCP Servers

Works with any stdio-based MCP server:
ServerPackage
GitHub@modelcontextprotocol/server-github
Filesystem@modelcontextprotocol/server-filesystem
Slack@modelcontextprotocol/server-slack
Google Drive@modelcontextprotocol/server-gdrive
PostgreSQL@modelcontextprotocol/server-postgres
CustomAny stdio MCP server

​
CLI Commands

# Wrap and run an MCP server
npx bloom-mcp secure <mcp-command>

# Show help
npx bloom-mcp --help

# Validate a tool (for testing)
npx bloom-mcp validate --tool create_issue --server github

​
Environment Variables

VariableRequiredDescription
BLOOM_API_KEYYesYour organization API key
BLOOM_AGENT_IDYesThe agent ID to use
BLOOM_PROXY_URLNoCustom proxy URL (default: iam.bloomtechnologies.app)

​
Troubleshooting

  1. Check the agent has an MCP-type scope assigned
  2. Verify the tool is in allowed_tools (or allowed_tools is ["*"])
  3. Verify the tool is NOT in blocked_tools
  4. Check Activity > MCP Tools for the denial reason
  • Verify BLOOM_API_KEY and BLOOM_AGENT_ID are set correctly
  • Check the agent exists and is active in the dashboard
  • Ensure the API key hasn’t been revoked
  • Check the underlying MCP server command works without bloom-mcp
  • Verify all required environment variables for the MCP server are set
  • Check for port conflicts if running multiple servers

​
Example: Secure GitHub Agent

Complete setup for a GitHub-enabled Claude agent: 
# 1. Set environment
export BLOOM_API_KEY="bloom_org_abc123"
export BLOOM_AGENT_ID="agent_github_bot"
export GITHUB_TOKEN="ghp_xxxxx"

# 2. Create MCP scope in dashboard with:
#    - allowed_tools: ["create_issue", "list_repos", "get_file_contents", "search_code"]
#    - blocked_tools: ["delete_repo", "create_or_update_file"]

# 3. Assign scope to agent

# 4. Run secured MCP server
npx bloom-mcp secure npx @modelcontextprotocol/server-github
Now your agent can only use the allowed GitHub tools, and all calls are logged.