MCP Agent Bridge Protocol

Purpose: Define how Paperclip agents access Busflow systems via MCP (Model Context Protocol) servers. Related: ADR-020, agentic-led-company-spec.md

Overview

Paperclip runs as a standalone governance platform with its own Postgres. It does not share a database with Busflow. All data access flows through MCP servers — lightweight protocol adapters that expose Busflow resources as agent-consumable tools.

┌─── Paperclip ───────────────────────┐       ┌─── Busflow ─────────────┐
│                                     │       │                         │
│  Commerce Team (PM · Eng · QA)      │       │  Hasura (GraphQL)       │
│    → mcp-server-hasura (commerce) ──│───────│──► Commerce data        │
│    → mcp-server-busflow-api ────────│───────│──► Commerce actions     │
│    → mcp-server-github ─────────────│───────│──► Code repos           │
│                                     │       │                         │
│  Backoffice Team (PM · Eng · QA)    │       │  n8n (Automations)      │
│    → mcp-server-hasura (backoffice) │───────│──► Backoffice data      │
│    → mcp-server-busflow-api ────────│───────│──► Backoffice actions   │
│    → mcp-server-github ─────────────│───────│──► Code repos           │
│                                     │       │                         │
│  Operations Team (PM · Eng · QA)    │       │                         │
│    → mcp-server-hasura (operations) │───────│──► Operations data      │
│    → mcp-server-busflow-api ────────│───────│──► Operations actions   │
│    → mcp-server-github ─────────────│───────│──► Code repos           │
│                                     │       │                         │
│  Comms Team (PM · Eng · QA)         │       │                         │
│    → mcp-server-hasura (comms) ─────│───────│──► Messaging data       │
│    → mcp-server-busflow-api ────────│───────│──► Comms actions        │
│    → mcp-server-github ─────────────│───────│──► Code repos           │
│                                     │       │                         │
│  Cross-Cutting: PM · Co-Founder     │       │                         │
│    → mcp-server-analytics ──────────│───────│──► Usage metrics        │
│    → mcp-server-hasura (read-only) ─│───────│──► Aggregated views     │
│                                     │       │                         │
└─────────────────────────────────────┘       └─────────────────────────┘

MCP Server Inventory

MCP Server	Purpose	Data Source	Estimated Effort
`mcp-server-hasura`	Read product data: tours, bookings, customers, vehicles, crew	Busflow Hasura (GraphQL)	~1 day (community server exists)
`mcp-server-busflow-api`	Execute NestJS Hasura Actions: manage bookings, trigger workflows, update operator config	Busflow NestJS API (REST)	~2 days
`mcp-server-n8n`	Trigger n8n automations from agent workflows	n8n webhook API	~1 day
`mcp-server-github`	Read/write code, PRs, issues, CI status	GitHub API	~0 (community server exists)
`mcp-server-analytics`	Read anonymized usage metrics, churn signals, feature adoption	Analytics store (TBD)	~1 day

TIP

Community MCP servers exist for GitHub and generic GraphQL endpoints. Prefer community servers where available; only build custom servers for Busflow-specific APIs.

Bounded Context Enforcement via MCP

The spec (§3.2) defines a strict access control matrix. MCP tool assignment enforces this — agents see only the MCP servers assigned in their Paperclip config.

Domain Teams

Each domain team receives MCP servers scoped to its bounded context. The mcp-server-hasura instance exposes only the Hasura views and permissions relevant to that domain.

Domain Team	MCP Servers Assigned	Monorepo Scope	Cannot Access
Commerce	`hasura` (commerce views), `busflow-api` (commerce actions), `github`	`apps/booking-widget`, `apps/passenger`, `packages/commerce/*`	Other domains' data, analytics, marketing
Backoffice	`hasura` (backoffice views), `busflow-api` (backoffice actions), `github`	`apps/workspace`, `packages/backoffice/*`	Other domains' data, analytics, marketing
Operations	`hasura` (operations views), `busflow-api` (operations actions), `github`	`apps/driver`, `packages/operations/*`	Other domains' data, analytics, marketing
Communications	`hasura` (comms views), `busflow-api` (comms actions), `github`	`packages/comms/*`, Real-time Inbox modules	Other domains' data, analytics, marketing

Cross-Cutting Roles

Role	MCP Servers Assigned	Cannot Access
Product Manager	`hasura` (read-only aggregated views), `analytics`	Source code, marketing internals
Domain Expert	None (uses own knowledge base)	All Busflow systems
Co-Founder (Strategy)	`analytics`	Raw code, raw customer data

IMPORTANT

MCP servers should expose scoped views, not raw database access. The mcp-server-hasura instance for each domain team should expose only the tables/views belonging to that domain's schema. The Product Manager's instance should expose pre-authorized GraphQL queries (anonymized booking counts, feature usage metrics) instead of full table access.

Authentication & Security

Concern	Approach
MCP ↔ Busflow auth	MCP servers authenticate to Busflow APIs using service account tokens (stored as Docker secrets)
Agent ↔ MCP auth	Paperclip manages agent-to-MCP authentication via its adapter config
Data isolation	Each MCP server exposes only the endpoints/queries its target agent needs. No blanket database access
PII protection	`mcp-server-hasura` must NOT expose passenger PII to non-Engineering agents. Use Hasura view-based permissions to expose anonymized aggregates
Audit trail	Paperclip's audit trail logs MCP tool calls. Additionally, Busflow NestJS logs inbound API calls from MCP servers

Deployment

Paperclip and its MCP servers run as standalone services in the Docker Swarm stack:

yaml

# docker-compose.paperclip.yml (simplified)
services:
  paperclip:
    image: busflow/paperclip-fork:latest  # or official image
    ports:
      - "3100:3100"
    environment:
      - DATABASE_URL=postgresql://paperclip:***@paperclip-db:5432/paperclip
    volumes:
      - paperclip-data:/data

  paperclip-db:
    image: postgres:16
    volumes:
      - paperclip-pgdata:/var/lib/postgresql/data

  mcp-server-hasura:
    image: busflow/mcp-server-hasura:latest
    environment:
      - HASURA_GRAPHQL_ENDPOINT=http://hasura:8080/v1/graphql
      - HASURA_ADMIN_SECRET=***

NOTE

The exact deployment configuration will evolve. This serves as the initial architectural direction. Traefik routing, secrets management, and monitoring integration follow the patterns established in infrastructure.md.

Evolution Triggers

If any of the following occur, re-evaluate the MCP bridge approach per ADR-020:

Latency: MCP round-trip adds unacceptable delay to agent workflows → consider shared DB access
Data scope: Agents need real-time subscriptions to Busflow data → consider Hasura subscriptions (requires shared DB or webhook forwarding)
Complexity: >5 custom MCP servers → consider consolidating into a single Busflow gateway MCP server

Busflow Docs

MCP Agent Bridge Protocol ​

Overview ​

MCP Server Inventory ​

Bounded Context Enforcement via MCP ​

Domain Teams ​

Cross-Cutting Roles ​

Authentication & Security ​

Deployment ​

Evolution Triggers ​