Copy page

Developer Guide

MCP Gateway

The mcp module exposes Primebrick's domain operations to AI clients over the Model Context Protocol. It has two distinct surfaces:

Surface	Consumer	Purpose
POST /mcp	External AI clients (Claude, ChatGPT, Cursor, VS Code)	Full MCP server — JSON-RPC 2.0, OAuth 2.1 Bearer auth
GET /api/v1/system/mcp/tools + POST /api/v1/system/mcp/call	The Primebrick Frontend	Lightweight tool catalog + single-call execution for the in-app assistant

Both surfaces expose the same tool catalog — one registry in modules/mcp/tools/ — so an operation exists identically for external agents and for the internal chat loop.

The tool catalog

Eleven generic tools work across every registered entity — they dispatch through entity-registry/dispatch, so a newly installed module's entities become tool-addressable with zero tool-code changes:

list_entities, get_entity_meta, list_records, get_record, create_record, update_record, delete_record, restore_record, get_audit, bulk_delete_records, list_services.

Each tool declaration carries a read_only flag — the caller uses it to decide whether a call needs user confirmation.

The caller-driven loop (internal assistant)

The AI microservice is inference-only — it never calls application tools. The Frontend owns the agentic loop:

1. GET /api/v1/system/mcp/tools → OpenAI-style tool definitions (+ read_only).
2. FE passes tools[] to POST /api/v1/ai/chat.
3. LLM requests a tool → AI emits client-tool-call and stops.
4. FE executes POST /api/v1/system/mcp/call — read-only tools immediately, write tools behind a user confirmation.
5. FE resubmits /api/v1/ai/chat with history + tool_results — repeat until finish (FE bounds the loop at 8 steps).

mcp-call.service executes each call inside the same entity service machinery the HTTP routes use — permissions, validation and audit are identical to a UI action.

OAuth 2.1 for external MCP clients

/mcp implements the 2025-06-18 MCP authorization profile:

• RFC 9728 — protected-resource metadata (/.well-known/oauth-protected-resource)
• RFC 8414 — authorization-server metadata (/.well-known/oauth-authorization-server)
• RFC 7591 — dynamic client registration (/mcp/oauth/register)
• Authorization Code flow at /mcp/oauth/authorize → Bearer tokens verified by token-verifier per request

Registered OAuth clients are persisted in oauth/client-registry-dal.

Discovery

tools/openapi-discovery lets MCP clients introspect available API surfaces, so an agent can learn the platform without a hardcoded map.