MCP Server Integration

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

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

Go to Scopes
Create or edit a scope
Set Scope Type to “MCP”
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:

Server	Package
GitHub	`@modelcontextprotocol/server-github`
Filesystem	`@modelcontextprotocol/server-filesystem`
Slack	`@modelcontextprotocol/server-slack`
Google Drive	`@modelcontextprotocol/server-gdrive`
PostgreSQL	`@modelcontextprotocol/server-postgres`
Custom	Any 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

Variable	Required	Description
`BLOOM_API_KEY`	Yes	Your organization API key
`BLOOM_AGENT_ID`	Yes	The agent ID to use
`BLOOM_PROXY_URL`	No	Custom proxy URL (default: iam.bloomtechnologies.app)

Troubleshooting

Tool calls being blocked unexpectedly

Check the agent has an MCP-type scope assigned
Verify the tool is in allowed_tools (or allowed_tools is ["*"])
Verify the tool is NOT in blocked_tools
Check Activity > MCP Tools for the denial reason

Authentication errors

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

MCP server not starting

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.

Get Started

Guides

Integration Methods

Security

Overview

Quick Start

1. Install

2. Configure Environment

3. Wrap Your MCP Server

How It Works

Claude Desktop Configuration

Tool-Level Permissions

Dashboard Configuration

API Configuration

Permission Logic

Monitoring MCP Calls

Dashboard

Webhooks

Supported MCP Servers

CLI Commands

Environment Variables

Troubleshooting

Example: Secure GitHub Agent

​Overview

​Quick Start

​1. Install

​2. Configure Environment

​3. Wrap Your MCP Server

​How It Works

​Claude Desktop Configuration

​Tool-Level Permissions

​Dashboard Configuration

​API Configuration

​Permission Logic

​Monitoring MCP Calls

​Dashboard

​Webhooks

​Supported MCP Servers

​CLI Commands

​Environment Variables

​Troubleshooting

​Example: Secure GitHub Agent

Overview

Quick Start

1. Install

2. Configure Environment

3. Wrap Your MCP Server

How It Works

Claude Desktop Configuration

Tool-Level Permissions

Dashboard Configuration

API Configuration

Permission Logic

Monitoring MCP Calls

Dashboard

Webhooks

Supported MCP Servers

CLI Commands

Environment Variables

Troubleshooting

Example: Secure GitHub Agent