> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloomtechnologies.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Integration

> Secure any MCP server with tool-level permissions

## 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

<Info>
  **Package**: [bloom-mcp on NPM](https://www.npmjs.com/package/bloom-mcp)
</Info>

## Quick Start

### 1. Install

```bash theme={null}
npm install -g bloom-mcp
```

### 2. Configure Environment

```bash theme={null}
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

```bash theme={null}
# 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`:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "events": ["mcp_tool_blocked", "mcp_tool_allowed"]
}
```

**Webhook Payload:**

```json theme={null}
{
  "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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Tool calls being blocked unexpectedly">
    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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Example: Secure GitHub Agent

Complete setup for a GitHub-enabled Claude agent:

```bash theme={null}
# 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.