MCP Server Setup Guide

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:

1. Build the server:

cd mcp-server
npm install
npm run build

2. 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

3. Start the server:

npm start

4. 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"
      }
    }
  }
}

5. 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:

1. Verify absolute paths in config (no ~ or relative paths)
2. Ensure npm run build completed successfully
3. Check dist/index.js exists
4. 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:

1. Verify SUPABASE_URL is correct
2. Check SUPABASE_SERVICE_KEY is valid
3. 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:

1. Check server logs for errors
2. Verify build output: ls -la mcp-server/dist/tools/
3. 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)

1. Never commit service keys to version control
2. Use environment variables for all secrets
3. Restrict service key to specific IP ranges if possible
4. Enable RLS policies on all tables
5. 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)