shopdb-flask/.claude/archived/MCP-SETUP-GUIDE.md

MCP Servers Setup Guide

Complete guide to set up Gortex, MySQL, Browser, and GitHub MCP servers for ShopDB.

Quick Summary

What you need to do:

1. Install npm packages
2. Set environment variable for GitHub
3. Restart Claude Code to load MCP servers

---

Step 1: Install MCP Server Packages

Run these commands:

# MySQL MCP server (with write support)
npm install -g @benborla29/mcp-server-mysql

# Browser automation MCP server
npm install -g @agent-infra/mcp-server-browser

---

Step 2: Fix GitHub MCP Authentication

The GitHub MCP error "Authorization header is badly formatted" means your GitHub token isn't set.

Create GitHub Personal Access Token

1. Go to: https://github.com/settings/tokens/new
2. Name: Claude Code MCP
3. Select scopes:
   • repo (Full control of private repositories)
   • read:org (Read org and team membership)
4. Click "Generate token"
5. Copy the token (starts with ghp_...)

Set Environment Variable

Option A: Set for current session (temporary)

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"

Option B: Set permanently (recommended) Add to your shell profile (~/.bashrc or ~/.bash_profile):

echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"' >> ~/.bashrc
source ~/.bashrc

Option C: Windows Environment Variables (GUI)

1. Search "Environment Variables" in Windows
2. Click "Environment Variables..."
3. Under "User variables", click "New"
4. Variable name: GITHUB_PERSONAL_ACCESS_TOKEN
5. Variable value: ghp_YOUR_TOKEN_HERE
6. Click OK, restart Claude Code

---

Step 3: MCP Configuration

The configuration file is already created at: .claude/mcp-servers.json

It contains:

• Gortex - Code intelligence (already running)
• MySQL - Database queries
• Browser - Frontend testing

Current Configuration:

{
  "mcpServers": {
    "gortex": {
      "command": "C:\\Users\\270015376\\Documents\\gortex.exe",
      "args": ["mcp"],
      "cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
    },
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql",
        "mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask"
      ]
    },
    "browser": {
      "command": "npx",
      "args": [
        "-y",
        "@agent-infra/mcp-server-browser"
      ]
    }
  }
}

---

Step 4: Verify Setup

After installing packages and setting GitHub token:

1. Restart Claude Code completely (close and reopen)

2. Check MCP servers are loaded:

   • You should see available tools from each server
   • No authentication errors in console

3. Test each server:

Gortex test:

ToolSearch("gortex explore")

MySQL test:

# Once MCP is loaded, you can query:
SELECT COUNT(*) FROM notifications WHERE alertfleet = true;

Browser test:

# Once MCP is loaded:
Navigate to http://localhost:5000/shopdb

GitHub test:

# Once MCP is loaded:
List my repositories

---

Step 5: Using the MCP Servers

Gortex (Code Intelligence)

Use for: Finding code, understanding relationships, editing symbols

Examples:

• "Use Gortex to explore fleet alert architecture"
• "Show me what calls get_fleet_alerts"
• "Edit the _alert_targets_endpoint function"

MySQL (Database)

Use for: Querying data, verifying schema, testing SQL

Examples:

• "Query all active fleet alerts from database"
• "Show me the notifications table schema"
• "How many operator reports exist?"

Browser (Frontend Testing)

Use for: Testing Vue app, screenshots, UI verification

Examples:

• "Navigate to /shopdb/notifications and screenshot"
• "Test the fleet alert form"
• "Verify the notification list loads"

GitHub (Collaboration)

Use for: PRs, issues, CI status

Examples:

• "Create PR for fleet alert work"
• "Check CI status on wj branch"
• "List open issues"

---

Troubleshooting

GitHub still shows auth error

• Verify token is correct (starts with ghp_)
• Check token has repo and read:org scopes
• Restart Claude Code after setting environment variable
• Try setting token in Windows Environment Variables GUI

MySQL connection fails

• Verify Docker containers are running: docker ps
• Check MySQL is accessible: mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask
• Verify port 3306 is not blocked

Browser MCP doesn't work

• Install Chrome/Chromium if not present
• Check browser package installed: npm list -g @agent-infra/mcp-server-browser

Gortex MCP not connecting

• Check daemon is running: /c/Users/270015376/Documents/gortex.exe status
• Verify path in mcp-servers.json is correct
• Try starting daemon manually: /c/Users/270015376/Documents/gortex.exe daemon start

MCP servers not loading at all

• Check .claude/mcp-servers.json file exists in project
• Verify JSON syntax is valid
• Restart Claude Code completely
• Check Claude Code console for errors

---

What Each Server Gives You

Server	Tools	Token Savings
Gortex	48 tools (explore, edit_symbol, find_files, etc.)	30-50K per session
MySQL	Query, schema inspection, data verification	5-10K per session
Browser	Navigate, click, screenshot, test	Catch bugs early
GitHub	PR, issues, CI status	5-10K per session

Total expected savings: 50-70K tokens per session (vs current ~120K usage)

---

Next Steps

1. Run the npm install commands above
2. Create GitHub token and set environment variable
3. Restart Claude Code
4. Try the test commands to verify each server works

Once all four are connected, you'll have complete code + data + frontend + collaboration coverage!