FBIS MCP Server
Relevant source files
The following files were used as context for generating this wiki page:
The FBIS MCP Server is a Python-based Model Context Protocol (MCP) implementation designed for the HERMES autonomous agent system. Built using the FastMCP framework, it serves as the intelligence bridge between AI agents and the FusionOps backend infrastructure, specifically focusing on "Ban Intelligence" and automated risk analysis for advertising accounts. Sources: HERMES_FBIS_AUDIT.txt:10-14, CLAUDE.md:61-63
The server provides a set of specialized tools that allow agents to query account data, analyze proxy health, track pixel events, and perform risk scoring. It operates on port 8765 by default and integrates directly with the FusionOps API Worker and D1 databases to facilitate automated decision-making, such as pausing high-risk accounts or reducing budgets based on predictive analytics. Sources: HERMES_FBIS_AUDIT.txt:11-25, CLAUDE.md:65-66
Architecture and Integration
The FBIS MCP Server acts as a middle tier between the HERMES Agent System (which includes agents like ARGUS and VERDICT) and the core FusionOps databases. It exposes high-level Python functions as MCP tools, which are then consumed by AI models to perform complex analysis pipelines. Sources: HERMES_FBIS_AUDIT.txt:30-45, CLAUDE.md:61-64
Data Flow Overview
The server interacts with the FusionOps API Worker using a Bearer token for authentication. The API Worker, in turn, manages connections to multiple Cloudflare D1 database instances. Sources: HERMES_FBIS_AUDIT.txt:100-110
The diagram above illustrates the request path from an autonomous agent through the MCP server to the underlying data persistence layer. Sources: HERMES_FBIS_AUDIT.txt:30-45, HERMES_FBIS_AUDIT.txt:100-115
Key Components and Modules
The server is organized into modular tool files located in apps/fbis-mcp-server/tools/. Each module encapsulates a specific domain of the FBIS (Ban Intelligence) system. Sources: HERMES_FBIS_AUDIT.txt:18-25
Tool Module Summary
| Module | Purpose | Key Functionality |
|---|---|---|
accounts.py | Account Queries | Fetches metadata for Google Ads/Advertising accounts. |
risk.py | Risk Scoring | Writes and retrieves risk scores; evaluates auto-pause rules. |
cloudflare.py | Infrastructure | Manages Cloudflare DNS, zones, and Pages deployments. |
pixel.py | Event Tracking | Queries first-party pixel event data for traffic analysis. |
proxy.py | Proxy Intel | Analyzes the health and risk of proxy pools. |
_client.py | API Client | Centralized HTTPX client for FusionOps API communication. |
Sources: HERMES_FBIS_AUDIT.txt:18-25, apps/fbis-mcp-server/server.py:10-20
Risk Scoring System
The most critical function of the server is handled in risk.py. It implements a weighted risk aggregation system used by the VERDICT agent to determine account health. Sources: HERMES_FBIS_AUDIT.txt:75-85, apps/fbis-mcp-server/tools/risk.py
Risk Scoring Logic
The system calculates a verdict_score (0-100) where higher values indicate higher risk (an inverted scale compared to safety scores). Sources: HERMES_FBIS_AUDIT.txt:75-80
The scoring system maps numerical values to actionable statuses, allowing agents to trigger automated responses. Sources: HERMES_FBIS_AUDIT.txt:81-88
Automated Decision Rules
The server evaluates specific rules when a risk score is processed:
- Critical Risk (≥80): Triggers an automatic PAUSE command.
- High Risk (≥60): Triggers a 50% budget reduction.
- Anomalies: Generates alerts for overspending (≥110% budget) or conversion drops (≥30%).
Sources: HERMES_FBIS_AUDIT.txt:90-95, apps/fbis-mcp-server/tools/risk.py:50-75
Tool Implementation Examples
The server uses the @mcp.tool() decorator to expose Python functions. Below are implementation details for core tools. Sources: apps/fbis-mcp-server/server.py:25-35
Account Management
The query_accounts tool allows agents to retrieve active account lists and their current status.
# From apps/fbis-mcp-server/tools/accounts.py
@mcp.tool()
async def query_accounts(status: str = "active"):
"""Fetch ad accounts filtered by status."""
return await client.get(f"/api/accounts?status={status}")
Sources: apps/fbis-mcp-server/tools/accounts.py:5-15
Cloudflare Integration
The manage_cloudflare tool (implemented in tools/cloudflare.py) provides agents with the ability to verify DNS settings or trigger Pages deployments for landing pages. Sources: apps/fbis-mcp-server/tools/cloudflare.py:10-40
Configuration and Environment
The server requires several environment variables for operation, primarily for authenticating with the FusionOps API and optional notification services. Sources: HERMES_FBIS_AUDIT.txt:27-32
| Variable | Description | Default |
|---|---|---|
FUSIONOPS_API_URL | Base URL of the Cloudflare API Worker. | N/A |
FUSIONOPS_API_KEY | Bearer token for authentication. | N/A |
MCP_PORT | The port the MCP server listens on. | 8765 |
TELEGRAM_BOT_TOKEN | Token for sending alerts to team chat. | Optional |
TELEGRAM_CHAT_ID | ID for the target Telegram group. | Optional |
Sources: HERMES_FBIS_AUDIT.txt:27-32, CLAUDE.md:65-66
Summary
The FBIS MCP Server is a specialized interface that empowers the HERMES agent team to maintain the health of the advertising ecosystem. By modularizing account, risk, and infrastructure operations into MCP tools, the system enables complex nightly analysis pipelines (orchestrated via /fbis-run) that can predict bans, aggregate risk, and perform autonomous mitigations without manual intervention. Sources: HERMES_FBIS_AUDIT.txt:50-60, HERMES_FBIS_AUDIT.txt:130-140