MCP Bridge

The Zihin MCP Bridge connects your ERP database to AI agents via the Model Context Protocol. It turns YAML manifests into MCP tools, resources, and prompts — no code required.

Overview

Feature	Details
Delivery	Docker image
Transport	HTTP Streamable (SSE)
Configuration	YAML manifests per business domain
Database	PostgreSQL 14+

ERP (Protheus, SAP, Oracle, ...)
    ↓ replica / sync
PostgreSQL (client database)
    ↓ semantic views + functions (contract)
zihin-mcp-bridge (YAML manifest)
    ↓ MCP Protocol
AI Agent

The bridge is ERP-agnostic. It expects semantic views and functions with standardized column names (English, snake_case). The client's DBA is responsible for translating their ERP data into the contract.

---

How It Works

Each business domain is defined as a YAML manifest that declares:

• Tools — queries the agent can execute (with parameters, filters, and descriptions)
• Resources — context data the agent can read (customer summaries, bank accounts, calendars)
• Prompts — structured workflows that guide the agent through multi-step analyses

The bridge loads the manifest at startup, validates it against a Zod schema, and exposes everything as MCP endpoints. The agent discovers tools automatically via the MCP Server protocol.

Manifest Example

A minimal tool definition in the manifest:

tools:
  - name: cash_position
    description: "Current cash position across all bank accounts"
    engine: view_query
    view: vw_cash_position
    filters:
      - name: branch_code
        column: branch_code
        type: string
        required: false
        description: "Filter by branch code"
    result:
      format: table
      max_rows: 100

This generates an MCP tool that the agent can call with optional filters. The bridge translates it into a SELECT * FROM vw_cash_position WHERE branch_code = $1 query at runtime.

Engine Types

The manifest supports five query engines:

Engine	Pattern	Use Case
view_query	SELECT * FROM view WHERE filters	Simple filtered queries (exact match, ILIKE)
raw_query	Parameterized SQL from YAML	Date ranges, complex WHERE clauses
function_call	SELECT * FROM fn($1, $2)	PostgreSQL functions with business logic
fts_query	Full-text search with ranking	Semantic product/entity search
materialized_view	Stats + sample queries	Resource context for the agent

---

Data Contract

The bridge defines a semantic contract for each domain. The contract specifies:

• View and function names (vw_cash_position, fn_cash_forecast)
• Column names and types (customer_code, due_date, open_amount)
• Expected behaviors (what each tool returns, what each alert detects)

The DBA reads the contract and creates the corresponding views in the client's database, mapping from their ERP tables to the semantic names. This way, the same manifest works across different ERPs.

Available Domains

Finance / Cash Flow

Cash flow management for financial executives. Includes cash position, receivables and payables schedules, aging analysis, working capital metrics, cash flow forecasting, scenario analysis, and proactive alerts.

Category	Count	Examples
Operational tools	7	Cash position, receivables schedule, bank transactions
Analytical tools	9	Aging analysis, customer/supplier performance, cash flow statement
Predictive functions	6	Cash forecast, liquidity gap detection, what-if scenarios
Reactive alerts	8	Delinquency spike, concentration risk, budget variance
Context resources	8	Bank accounts, business calendar, treasury parameters
Guided prompts	5	Daily treasury report, client analysis, alert check

The contract expects 24 views (vw_*), 14 functions (fn_*), and 2 reference tables (ref_branches, ref_treasury_parameters).

Procurement / Supply Chain

Procurement and supply chain management. Includes product catalog with full-text search, supplier evaluation, ABC/XYZ classification, reorder point calculation, price anomaly detection, and demand forecasting.

Category	Count	Examples
Search tools	1	Full-text product search with ranking
Pipeline tools	4	Purchase pipeline, critical stock, pending approvals
Analytical functions	9	ABC/XYZ, supplier scorecard, HHI concentration
Materialized views	4	Monthly spend, supplier metrics, demand history
Context resources	7	Product catalog, supplier directory, cost centers
Guided prompts	5	Supply chain analysis, supplier evaluation, stock optimization

---

Supported ERPs

The bridge itself is ERP-agnostic. Migration scripts (accelerators) are available for:

ERP	Status
Protheus (TOTVS)	Production
SAP	Planned
Oracle EBS	Planned

For ERPs without a migration script, the DBA creates the views manually following the contract documentation.

---

Deployment

Step 1 — Prepare the Database

Run the migration script for your ERP and domain, then:

1. Populate ref_branches with your branch/company mapping
2. Calibrate ref_treasury_parameters with the treasury team (alert thresholds)
3. Validate: SELECT COUNT(*) FROM vw_receivables_schedule;

Step 2 — Configure Environment

Create a .env file with database credentials:

DB_HOST=database-host
DB_PORT=5432
DB_USER=bridge_user
DB_PASSWORD=your-password
DB_NAME=database-name
PORT=3000
ENABLED_DOMAINS=all

The database user needs SELECT on all contract views and functions.

Step 3 — Start the Bridge

docker compose up -d

Step 4 — Verify

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "tools": 49,
  "resources": 15,
  "prompts": 10
}

Step 5 — Connect to an Agent

Register the bridge as an MCP server on your agent via the MCP Server API:

curl -X POST https://llm.zihin.ai/api/mcp-servers \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_UUID",
    "name": "ERP Bridge",
    "endpoint": "http://bridge-host:3000/mcp",
    "transport": "http"
  }'

The agent automatically discovers all tools, resources, and prompts from the bridge. See Agent Tools — MCP for details on how agents use MCP tools.

---

Multi-Tenant Architecture

Each client gets:

• Their own Docker container — running the same image
• Their own manifest(s) — volume-mounted, domain-specific
• Their own database — with views created from the contract

The bridge image contains no client data, manifests, or credentials. Everything is injected at runtime via volume mounts and environment variables.

Client A: Docker + manifest(finance)     + .env → PostgreSQL A
Client B: Docker + manifest(procurement) + .env → PostgreSQL B
Client C: Docker + manifest(both)        + .env → PostgreSQL C

---

Adding a New Domain

1. Define the contract: what views, functions, and columns the domain needs
2. Create the manifest YAML with tools, resources, and prompts
3. Write the migration script for the target ERP
4. Place the manifest in the bridge configuration and restart