MCP Agent Broker

The Model Context Protocol (MCP) Agent Broker is a centralized service designed to orchestrate and manage autonomous coding agents.

It acts as a middleware that securely maps AI Agents (Principals) to tasks, enforcing distributed locks (Fencing Tokens) so multiple agents don't step on each other's toes when working on the same repository.

Features

• MCP Server Integration: Natively implements the MCP SDK via Server-Sent Events (SSE).
• Secure Authentication: Validates API keys against securely hashed database records.
• Distributed Locking: Safely hand off tasks between implementer agents and reviewer agents using fencing tokens.
• Transactional Outbox: Guaranteed delivery of domain events without dual-write issues.
• Event Relay: Real-time event broadcasting over Redis Pub/Sub.

Getting Started

1. Start the Infrastructure

The broker requires PostgreSQL and Redis. We provide a docker-compose.yml to spin up everything (including the broker itself) instantly.

docker compose up -d

Note: If you are doing local development, you can run docker compose up -d postgres redis and then run the app locally using npm run dev.

2. Generate an API Key

To connect to the broker, your Agent must have an API Key. We provide a seed script to generate your first Workspace, Principal, and API Key.

npx tsx seed_api_key.ts

Take note of the API Key (e.g. test-api-key-123) output by the terminal.

3. Connect your Agents

Point your MCP-compatible client to the broker's endpoint and pass your API key as a Bearer token.

Programmatic Example (TypeScript):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(new URL("http://localhost:3000/mcp/sse"), {
  eventSourceInit: {
    headers: { Authorization: "Bearer test-api-key-123" }
  } as any,
  requestInit: {
    headers: { Authorization: "Bearer test-api-key-123" }
  }
});

const client = new Client({ name: "my-agent", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);

// Register your agent!
await client.request({
  method: "tools/call",
  params: {
    name: "register_agent",
    arguments: { 
      workspaceId: "00000000-0000-0000-0000-000000000000", 
      name: "My Implementer Agent", 
      version: "1.0", 
      capabilities: ["execute"] 
    }
  }
}, CallToolResultSchema);

4. Listen to Real-Time Events

Any downstream CI dashboard or review agent can connect to the Redis server and subscribe to workspace:{workspace_id}:events to see real-time updates as tasks are created and leases are acquired!

Future Improvements for Contributors

• Implement standard OAuth2 / OIDC for user-facing dashboards.
• Extend the Review Module to enforce reviewer sign-offs before pushing to main branches.
• Implement the Fencing Token check in a Git Hook or CI/CD layer.