MCP Server Setup Guide

Deze inhoud is nog niet vertaald.

The MCP (Model Context Protocol) server enables Claude Desktop to interact with your Eryxon Flow deployment using natural language. This guide covers local development and trusted self-hosted deployment.

Overview

What is the MCP Server?

Provides 50 AI tools across 9 modules for manufacturing operations
Enables natural language interaction with jobs, parts, operations, quality, and analytics
Optional component - your application works perfectly without it
Designed for developers and power users who want AI assistant integration

Architecture:

Claude Desktop (User)
  ↓ MCP Protocol (stdio/SSE)
MCP Server (Local or Docker host)
  ↓ Direct Supabase service-role client
Eryxon Flow Database
  ↓ Optional TENANT_ID enforcement
Your Data

Deployment Modes

Local Stdio

Best for: Claude Desktop, Cursor, and local development.

Requirements:

Node.js 20+
Direct access to Supabase database
Service role key

Setup:

Build the server:

cd mcp-server
npm install
npm run build

Configure environment:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="eyJhbGc..."  # Service role key
export TENANT_ID="optional-tenant-id"      # recommended when sharing one DB

Start the server:

npm start

Configure Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "eryxon-flow": {
      "command": "node",
      "args": ["/absolute/path/to/eryxon-flow/mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key"
      }
    }
  }
}

Restart Claude Desktop

You should see “Eryxon Flow MCP Server” with the available tools listed.

Docker HTTP

Best for: trusted internal deployments and MCP clients that support Streamable HTTP.

cd mcp-server
docker build -t eryxon-mcp .
docker run -p 3001:3001 \
  -e SUPABASE_URL="https://your-project.supabase.co" \
  -e SUPABASE_SERVICE_KEY="your-service-role-key" \
  -e MCP_BEARER="change-this-long-random-token" \
  -e MCP_ALLOWED_HOSTS="localhost,your-mcp-domain.com" \
  eryxon-mcp

Connection Mode

The v0.5.x maintenance line supports direct Supabase access only.

Environment Variables	Mode	Use Case
`SUPABASE_URL` + `SUPABASE_SERVICE_KEY`	Direct Mode	Self-hosted, local, trusted internal deployment

If you expose HTTP transport, set MCP_HOST=0.0.0.0, MCP_BIND_PUBLIC=true, a strong MCP_BEARER, and MCP_ALLOWED_HOSTS to the hostnames allowed to reach the server. The default bind address is 127.0.0.1; MCP_ALLOWED_HOSTS defaults to localhost,127.0.0.1,[::1].

Available Tools

The MCP server provides 50 tools across 9 modules:

1. Jobs (7 tools)

fetch_jobs - Query jobs with filters and pagination
create_job - Create new manufacturing jobs
update_job - Update job properties
start_job - Start job execution
stop_job - Pause/stop job
complete_job - Mark job as completed
resume_job - Resume paused job

2. Parts (2 tools)

fetch_parts - Query parts with relationships
update_part - Update part properties

3. Operations (5 tools)

fetch_operations - Query operations with filters
start_operation - Begin operation execution
pause_operation - Pause operation
complete_operation - Complete operation
update_operation - Update operation details

4. Tasks (2 tools)

fetch_tasks - Query tasks
update_task - Update task status

5. Issues (8 tools)

fetch_issues - Query quality issues
create_ncr - Create Non-Conformance Reports
fetch_ncrs - Query NCRs
update_issue - Update issue status
get_issue_analytics - Issue trend analysis
get_issue_trends - Historical issue patterns
get_root_cause_analysis - Root cause insights
suggest_quality_improvements - AI-powered recommendations

6. Substeps (5 tools)

fetch_substeps - Query operation substeps
add_substep - Add substep to operation
complete_substep - Mark substep complete
update_substep - Update substep
delete_substep - Remove substep

7. Dashboard (3 tools)

get_dashboard_stats - Real-time production metrics
get_qrm_data - Quick Response Manufacturing capacity
get_production_metrics - Historical production data

8. Scrap (7 tools)

fetch_scrap_reasons - Query scrap categories
report_scrap - Record scrap events
get_scrap_analytics - Scrap analysis
get_scrap_trends - Scrap patterns over time
get_yield_metrics - Production yield rates
get_scrap_pareto - Pareto analysis of scrap causes
get_quality_score - Overall quality metrics

9. Agent Batch (11 tools)

Optimized batch operations for AI agents:

batch_update_parts - Bulk part updates
batch_reschedule_operations - Bulk rescheduling
prioritize_job - Set job priority
fetch_parts_by_customer - Customer-scoped queries
batch_complete_operations - Bulk completion
get_job_overview - Comprehensive job summary
check_resource_availability - Resource planning
assign_resource_to_operations - Resource allocation
get_cell_capacity - Cell utilization
get_parts_due_soon - Due date alerts
suggest_reschedule - AI-powered rescheduling

Testing Your Setup

1. Verify Server is Running

Local mode:

npm start
# Should output:
# Eryxon Flow MCP Server
# Loaded 50 tools from 9 modules
# Eryxon Flow MCP Server running on stdio

HTTP mode:

curl http://localhost:3001/health
# Should return: {"status":"ok","version":"2.4.0","mode":"direct","tools":50,"transport":"streamable-http"}

2. Test in Claude Desktop

Ask Claude:

"Show me all jobs currently in progress"

Claude should use the fetch_jobs tool with status: "in_progress".

3. Verify Tool Access

Ask Claude:

"What tools do you have available from Eryxon Flow?"

Claude should list all 50 tools.

Troubleshooting

”MCP server not found”

Issue: Claude Desktop can’t find the server

Solutions:

Verify absolute paths in config (no ~ or relative paths)
Ensure npm run build completed successfully
Check dist/index.js exists
Restart Claude Desktop after config changes

”Permission denied” or “EACCES”

Issue: Node can’t execute the script

Solution:

chmod +x mcp-server/dist/index.js

“Supabase connection failed”

Issue: Can’t connect to database

Solutions:

Verify SUPABASE_URL is correct
Check SUPABASE_SERVICE_KEY is valid
Test connection manually:

curl https://your-project.supabase.co/rest/v1/jobs \
  -H "apikey: YOUR_ANON_KEY_HERE" \
  -H "Authorization: Bearer YOUR_SERVICE_KEY_HERE"

“No tools available”

Issue: Tools not loading

Solutions:

Check server logs for errors
Verify build output: ls -la mcp-server/dist/tools/
Ensure all dependencies installed: npm ci

”Rate limited”

Issue: Too many requests

Solution:

Reduce request frequency
Use pagination limits on broad fetches

Security Best Practices

For Self-Hosted (Direct Mode)

Never commit service keys to version control
Use environment variables for all secrets
Restrict service key to specific IP ranges if possible
Enable RLS policies on all tables
Monitor usage via Supabase dashboard

Updating the MCP Server

Local Mode

cd mcp-server
git pull origin main
npm ci
npm run build
# Restart Claude Desktop

Performance Optimization

Caching

Add Redis caching for frequently accessed data:

UPSTASH_REDIS_REST_URL="https://your-redis.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your-token"

Default TTL: 5 minutes for fetch operations

Query Optimization

The server includes:

Pagination - All fetch operations support limit and offset
Soft-delete filtering - Automatically excludes deleted records
Timeout protection - 30-second query timeout (configurable)