A self-hosted MCP gateway for production AI agents.
Audit logging. RBAC. Capability discovery. One endpoint.
docker compose up -d && make demo
You're running AI agents in production. They're calling MCP tools. You have no idea what they're doing, who's authorized to call what, or how to audit any of it.
Raw MCP has no access control, no audit trail, and no health monitoring. Every agent connects directly to every service. When something breaks, you have no logs. When someone calls a tool they shouldn't, you have no guardrails.
Motherbrain is a gateway that sits between your agents and your MCP services. Every tool call is logged. Access is controlled by RBAC groups. Services are health-monitored. You get a dashboard.
One endpoint. Full visibility. Controlled access.
| Raw MCP | Motherbrain |
|---|---|
| No audit log | Full event log — every call with args, response, agent, duration |
| No access control | Users + groups + per-service permissions |
| No observability | Health monitoring, latency tracking, denial logging |
| Direct service connections | Single gateway endpoint — agents talk to one URL |
Every tool call is logged with full context: caller identity, arguments, response, status, and duration. Search and filter by service, agent, tool, or topic. Sensitive fields (tokens, passwords, API keys) are automatically redacted before storage.
Users belong to groups. Groups grant access to specific MCP services. Unauthorized calls are denied and logged. Admin users bypass all checks for emergency access.
30-second HTTP probes on every registered service. Online/offline status in the dashboard. Last heartbeat tracked per service. Click any service to see its full capability list and recent activity feed.
Autonomous agents can claim jobs, execute them, and report progress through a six-tool MCP loop — no polling endpoints, no custom glue.
register_worker → claim_next_job → get_job_context → call_tool → report_progress → complete_job
Jobs flow through states: pending → claimed → in_progress → complete | failed | dead_letter
Each claim grants a 10-minute lease. A background reaper automatically resets jobs whose leases expire (up to max_retries) so a crashed worker never orphans work. The dashboard shows live job state and progress for every worker. See docs/worker-setup.md for a full walkthrough.
The dashboard activity log updates live via SSE — no polling. Connect directly: GET /api/event-log/stream with optional ?topic= and ?service_id= filters.
Prometheus metrics at /metrics: total proxy calls, latency histograms, services online, agents online. Drop into any Grafana setup.
Prerequisites: Docker + Docker Compose
git clone https://github.com/irpina/motherbrain-mcp.git
cd motherbrain-mcp
cp .env.example .env
docker compose up -d
make demo # seed realistic demo data- Dashboard: http://localhost:3000
- API docs: http://localhost:8000/docs
- MCP endpoint: http://localhost:8000/mcp
- Metrics: http://localhost:8000/metrics
The demo seeds 4 MCP services, 3 users across 2 RBAC groups, 80 gateway events (including 10 RBAC denials), 2 agents, 4 jobs, and 3 rules. The Overview page shows gateway metrics: Services Online, Calls Today, Denials, Avg Response.
┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐
│ LLM Client │────→│ Motherbrain │────→│ filesystem (read_file…) │
│ (Claude, │ │ Gateway │ │ github (get_pr…) │
│ Codex, │ │ │ │ web-fetch (fetch_url…) │
│ Qwen…) │ │ • Audit │ │ your-service │
└─────────────┘ │ • RBAC │ └─────────────────────────────┘
│ • Health │
┌─────────────┐ │ • Metrics │
│ Worker │────→│ • Workers │
│ Agent │ └─────────────┘
│ (claim → │ │
│ execute → │ ┌──────┴──────┐
│ complete) │ │ Dashboard │ ←── SSE live stream
└─────────────┘ │ (Next.js) │
└─────────────┘
LLM clients connect to one endpoint for proxied MCP access. Worker agents use the worker protocol to claim jobs, execute them with full policy enforcement, and report progress — all through the same MCP endpoint.
The services above are seeded by make demo. Register your own with POST /mcp/register.
# Set API_KEY in your .env file
curl -X POST http://localhost:8000/mcp/register \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_KEY" \
-d '{
"service_id": "my-service",
"name": "My MCP Service",
"endpoint": "http://host.docker.internal:8010"
}'Motherbrain registers the service, begins health-probing every 30 seconds, and lists it in the gateway dashboard.
Add Motherbrain to your Claude Desktop config:
{
"mcpServers": {
"motherbrain": {
"url": "http://localhost:8000/mcp"
}
}
}With RBAC enabled, pass your user token:
{
"mcpServers": {
"motherbrain": {
"url": "http://localhost:8000/mcp",
"headers": {
"X-User-Token": "mb_your_token_here"
}
}
}
}- Users —
useroradminrole. Identified by tokens (SHA-256 hashed in DB). - Groups — named collections with an
allowed_service_idslist. - Membership — users belong to groups; groups grant service access.
- Admin bypass — admins can call any service regardless of group.
Manage users and groups via the Admin section of the dashboard or the REST API.
The agents/ directory has ready-to-run worker implementations of the claim → execute → complete loop:
| Agent | Model | Notes |
|---|---|---|
agents/claude/ |
Claude (Anthropic API) | Containerized; implements full worker protocol |
agents/codex/ |
GPT-4o (OpenAI API) | Containerized; implements full worker protocol |
agents/kimi/ |
Moonshot Kimi | OpenAI-compatible; worker + chat channel support |
agents/qwen/ |
Local Qwen via llama-server | Runs on localhost:8080; see windows/start_qwen_motherbrain.bat |
Each agent connects to the Motherbrain MCP endpoint, registers as a worker, and claims jobs from the queue. See docs/worker-setup.md for the full walkthrough.
Beyond the gateway and worker protocol, Motherbrain exposes a shared context/skill store (reusable prompts, agent configs, structured data) and agent chat channels for real-time coordination — see the API docs at /docs for the full feature set.
| Layer | Tech |
|---|---|
| Gateway | FastAPI + FastMCP |
| Dashboard | Next.js 15 + Tailwind CSS |
| Database | PostgreSQL 15 (asyncpg) |
| Cache / Queue | Redis 7 |
| Migrations | Alembic (auto-applied on startup) |
| Metrics | Prometheus + prometheus-fastapi-instrumentator |
make up # Start all services
make down # Stop
make logs # Follow logs
make shell # Shell into API container
make demo # Seed demo data
make doctor # Diagnose DB, Redis, API, services| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | postgresql+asyncpg://postgres:postgres@db:5432/motherbrain |
REDIS_URL |
Redis connection string | redis://redis:6379 |
API_KEY |
Master API key — change before any deployment | (required) |
CORS_ORIGINS |
Comma-separated allowed origins for the dashboard | http://localhost:3000 |
REDACT_FIELDS |
Extra comma-separated field names to redact from logs | (optional) |
- v3.1 release notes — Worker protocol, job detail pages, Qwen agent
- v3.0 release notes — Prometheus metrics, PII redaction, SSE streaming, service detail pages
MIT