MCP Server Overview

​

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external systems through a structured interface of tools, resources, and prompts. ProBeya ships a first-class MCP server so that Claude Desktop, Claude Code, VS Code extensions, and any MCP-compatible client can read and write your transformation data directly.

​

When to Use MCP vs REST

Rule of thumb: Use MCP when an AI model is in the loop. Use REST for system-to-system integrations.

​

Real Claude Conversation Example

Here is an actual conversation between a pharma quality manager and Claude Desktop connected to ProBeya via MCP:

User: What are the KPI alerts on our Brussels filling line board?

Claude: Let me check the KPI alerts for your Brussels board.

  [Calling tool: get_kpi_alerts with boardId: "clx9bd001"]

There are 2 KPI alerts on the Brussels Filling Line board:

1. **OEE** — 82.5% (AMBER)
   Threshold: Green ≥85%, Amber ≥75%, Red <75%
   Target: 90% by end of year
   → Below target but above amber. Line 2 downtime (seal replacement)
     is the primary driver.

2. **Right First Time** — 96.2% (AMBER)
   Threshold: Green ≥98%, Amber ≥95%, Red <90%
   → Labeling errors on secondary packaging. Not a product quality issue
     but affecting the metric.

Would you like me to create actions for these, or run a full
SQCDP review using the kpi_review prompt?

User: Create a critical action for the OEE issue and assign it to
Dr. Chen. Due next Friday.

Claude: [Calling tool: create_action with boardId: "clx9bd001",
  title: "Investigate Line 2 seal failures causing OEE drop to 82.5%",
  priority: "critical", category: "D", responsibleId: "clx9us003",
  dueDate: "2026-04-18"]

Done. Action created and assigned to Dr. Marie Chen:
- **Title:** Investigate Line 2 seal failures causing OEE drop to 82.5%
- **Priority:** Critical
- **Due:** April 18, 2026
- **Tier:** 1 (Team)

Dr. Chen has been notified. The action will appear on the Brussels
board's action list.

​

Transport Modes

The ProBeya MCP server supports two transport modes:

​

Authentication

All MCP connections authenticate via the PRPROBEYA_API_KEY environment variable.

# API key format
PRPROBEYA_API_KEY="probeya_sk_live_7f3a..."

The key is verified using the same authentication pipeline as the REST API: bcrypt verification, prefix lookup, expiry/revocation checks, and scope validation.

Generate an API key from Settings > API Keys in the ProBeya web app. Each key is scoped to a specific organization and user.

​

Scope Enforcement

API keys can be scoped to limit what the AI assistant can do. Scopes follow a action:resource pattern:

If an API key has no scopes (empty array), it has full access to all tools.

When a tool is called without the required scope, the server returns:

{
  "content": [{
    "type": "text",
    "text": "Error: Insufficient scope. Tool requires \"write:items\". Your API key has: [read:items]."
  }],
  "isError": true
}

​

MCP Key Restrictions

Beyond standard API key scopes, MCP-specific keys support additional restrictions:

These are configured when creating an MCP API key and enforced server-side before any tool execution.

​

Architecture

The MCP server is a thin adapter layer over the existing tRPC API. All business logic, input validation, audit trails, and multi-tenant isolation are handled by the tRPC layer.

AI Client (Claude Desktop / Code / VS Code)
    |
    | MCP Protocol (stdio or HTTP)
    |
ProBeya MCP Server v2.0.0 (apps/mcp/)
    |
    | appRouter.createCaller(ctx)
    |
tRPC Procedures (@probeya/api)
    |
    | Drizzle ORM + tenant isolation
    |
PostgreSQL (organizationId on every query)

Enforcement order for every tool call:

1. Check API key scope (read:items, write:kpis, etc.)
2. Check MCP key tool permission (allowedTools)
3. Check MCP key token budget (maxTokensPerMonth)
4. Execute handler via tRPC caller
5. Log to audit trail
6. Increment token counter

​

Server Capabilities

The ProBeya MCP server (v2.0.0) uses these MCP SDK features:

​

Quick Setup

• Claude Desktop
• Claude Code
• VS Code (Copilot)

{
  "mcpServers": {
    "probeya": {
      "command": "node",
      "args": ["/path/to/probeya/apps/mcp/dist/index.js"],
      "env": {
        "PRPROBEYA_API_KEY": "probeya_sk_live_7f3a...",
        "DATABASE_URL": "postgresql://user:pass@host:5432/probeya"
      }
    }
  }
}

​

What’s Next