Open Vyrab
Docs/Integrations & security
TECHNICAL REFERENCE

Integrations & security

Technical reference for administrators: AI configuration and MCP access.

Security boundary

This reference describes the source edition, not the security configuration of the public ERP deployment. Do not assume that an MCP endpoint is publicly available. The source implementation uses a shared service account and has no per-operator authentication or role filtering. Keep it private; production exposure requires an authenticated, authorized access layer. Read-only does not mean safe for public access.

Built-in assistant configuration

The built-in assistant requires OPENAI_API_KEY on the ERP server. Never put this key in the marketing website, browser code or a VITE_ variable. The built-in assistant checks operator permissions and requires confirmation for write actions. It is separate from MCP.

What it is and what it's for

A separate endpoint from the main API, /mcp, on the backend — this is a Streamable HTTP MCP server that gives external AI clients (primarily ChatGPT in developer/connector mode) read-only access to Vyrab data, without signing in as an operator and without applying RBAC roles/ permissions: the request to platform-core is made on behalf of the application's shared service API key, not a specific person. Its purpose is to let an external AI (for example, ChatGPT, which an employee uses outside Vyrab itself) quickly look up parts, production orders, and stock without entering the application.

Available tools

Tool What it does
search Full-text search over parts, production orders, and contracts (platform-core)
fetch Fetch a single object by an identifier of the form part:<uuid>, production_order:<uuid>, or contract:<uuid>, as returned by search
list_production_orders List of production orders, optionally filtered by status (draft/planning/in_production/done/canceled)
get_inventory Parts and current materialized warehouse stock by name/part number, including the balance net of the minimum reserve

All four tools are marked read-only (readOnlyHint, destructiveHint: false) at the MCP protocol level — ChatGPT sees them as safe to call without explicit human confirmation. Links in responses lead to the object's card in the Vyrab web interface (the address is assembled from MCP_UI_BASE_URL).

How to enable and test it

  1. The backend already publishes /mcp by default — there is nothing separate to enable, the MCP server comes up together with the ordinary API.
  2. Locally / for testing: npx @modelcontextprotocol/inspector, in Inspector choose the Streamable HTTP transport and point it at http://localhost:8000/mcp. The list of tools and their schemas can be invoked right in Inspector, without connecting ChatGPT.
  3. Connecting from ChatGPT — as a connector/developer mode pointed at the same URL (http(s)://<backend host>/mcp).

Configuration (environment variables)

Variable Purpose Default
MCP_UI_BASE_URL The public address of the Vyrab web interface that the links in search/fetch/list_production_orders/get_inventory responses point to. In a deployment, this should be the frontend's real address, not localhost http://localhost:5174
MCP_ALLOWED_HOSTS The list of hosts (with port) allowed to access /mcp — protection against DNS rebinding for the Streamable HTTP transport. In a deployment, add the MCP server's hostname, e.g. ["vyrab.example.com"] ["127.0.0.1:*", "localhost:*", "[::1]:*"]
MCP_ALLOWED_ORIGINS Allowed browser origins for the same transport, if needed ["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"]

Notes and limitations

  • /mcp is not protected by a login and does not filter data by roles — it is read-only, but full access to all the data visible to the service account, with no per-operator distinction. That is exactly why the current version is meant for local ChatGPT developer mode or access through a secured tunnel, not for publishing to the open internet.
  • Docker Compose deliberately publishes the backend only on 127.0.0.1:8000 (not on all interfaces) — this is the only real protection boundary for /mcp out of the box. Do not expose the port externally without OAuth 2.1 and a user permission check in front of /mcp.
  • MCP tools do not overlap with AI assistant tools: they are two independent sets (MCP is always read-only and unauthenticated for the operator, the assistant has RBAC and write capability via confirmation), even where they read the same data through shared query logic.
  • Getting started — roles and permissions (ai-chat.use, the per-tool boundary), the object inspector (where the links to objects from the assistant's replies lead).
  • Products & orders — Order fulfillment, Orders (the objects the assistant can create and most often references).
  • Warehouse & supply — Supply availability, Warehouse (the data source for the material-shortage and stock tools).
  • Cost & prices — Cost (the data source for get_part_cost).