MCP Setup Skill

Overview

This skill handles Model Context Protocol (MCP) server configuration, troubleshooting, and integration for StepCountLeague v3. Use this when:

• Setting up new MCP servers
• Debugging MCP connection issues
• Managing authentication for MCP services
• Updating MCP configurations

Key Files

Configured MCP Servers

Active Servers (5 total)

1. Supabase MCP - Database access

   • Type: HTTP Remote
   • Auth: Project reference in URL
   • Config: .mcp.json, .vscode/mcp.json

2. PostHog MCP - Analytics querying

   • Type: HTTP with Bearer token
   • Auth: POSTHOG_MCP_TOKEN environment variable
   • Config: .mcp.json, .vscode/mcp.json

3. Google Tag Manager MCP - GTM management

   • Type: stdio via mcp-remote
   • Auth: Google OAuth (browser popup)
   • Config: .mcp.json, .vscode/mcp.json

4. Google Analytics 4 MCP - GA4 reporting

   • Type: stdio via mcp-remote
   • Auth: Google OAuth (browser popup)
   • Config: .mcp.json, .vscode/mcp.json

5. Playwright MCP - Browser automation

   • Type: stdio via npx
   • Auth: None (local tool)
   • Config: .mcp.json, .vscode/mcp.json

Critical Rules

[!WARNING] Always follow these rules when working with MCP servers:

1. Never Hardcode Tokens

❌ WRONG:

{
  "posthog": {
    "headers": {
      "Authorization": "Bearer phx_hardcoded_token_here"
    }
  }
}

✅ CORRECT:

{
  "posthog": {
    "headers": {
      "Authorization": "Bearer ${POSTHOG_MCP_TOKEN}"
    }
  }
}

2. Keep Both Config Files in Sync

When adding/updating MCP servers:

1. Update .mcp.json (Claude Code)
2. Update .vscode/mcp.json (VS Code MCP extension)
3. Keep server names and configurations consistent

3. Document New Servers

When adding a new MCP server:

1. Add configuration to .mcp.json
2. Add environment variables to .env.local (if needed)
3. Document in .agent/MCP.md
4. Test with /mcp command in Claude Code

4. Use Environment Variables

All sensitive tokens must be in .env.local:

# ❌ Never in .mcp.json
# ✅ Always in .env.local
POSTHOG_MCP_TOKEN=phx_xxx...
SUPABASE_MCP_ACCESS_TOKEN=sbp_xxx...

Common Tasks

Adding a New MCP Server

Step 1: Choose the server type

HTTP Server with Bearer Token:

{
  "server-name": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${SERVER_TOKEN}"
    },
    "description": "Brief description of what this server does"
  }
}

stdio Server via npx:

{
  "server-name": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "package-name@version"],
    "description": "Brief description of what this server does"
  }
}

Step 2: Add to .mcp.json

Edit: D:\Vasso\coding projects\SCL v3 AG\scl-v3\.mcp.json

Step 3: Add environment variables (if needed)

Edit: D:\Vasso\coding projects\SCL v3 AG\scl-v3\.env.local

# New MCP Server
# Get from: [URL to token generation]
# Description of what the token is for
SERVER_TOKEN=xxx...

Step 4: Document the server

Edit: D:\Vasso\coding projects\SCL v3 AG\scl-v3\.agent\MCP.md

Add a new section describing:

• Purpose and capabilities
• Authentication method
• Environment variables used
• Official documentation links

Step 5: Test the connection

In Claude Code CLI:

/mcp
# Verify the server appears in the list with status

Troubleshooting MCP Connection Issues

Issue: Server Not Listed in /mcp

Diagnostic Steps:

1. Check .mcp.json syntax:

   bashCopy

   # Validate JSON syntax
   node -e "JSON.parse(require('fs').readFileSync('.mcp.json', 'utf8'))"
   

2. Verify environment variables:

   bashCopy

   # Check if token is set (Windows)
   echo %POSTHOG_MCP_TOKEN%
   

3. Restart Claude Code CLI completely

4. Check for typos in server name

Fix:

• Ensure .mcp.json is valid JSON
• Verify environment variable names match exactly (case-sensitive)
• Check for trailing commas in JSON

Issue: Authentication Failed (HTTP Servers)

Diagnostic Steps:

1. Verify environment variable is set and loaded
2. Check token format (e.g., PostHog uses phx_ not phc_)
3. Test token manually with curl:
   bashCopy

   curl -H "Authorization: Bearer $POSTHOG_MCP_TOKEN" https://mcp.posthog.com/mcp
   

Fix:

• Generate new token from service provider
• Update .env.local with correct token
• Restart Claude Code to reload environment variables

Issue: OAuth Popup Blocked (GTM/GA4)

Diagnostic Steps:

1. Check browser popup blocker settings
2. Verify default browser is set correctly
3. Check if OAuth redirect URL is allowed

Fix:

• Disable popup blocker for localhost/Claude Code
• Use a different browser as default temporarily
• Clear browser cache and try again

Issue: npx Command Fails (Playwright)

Diagnostic Steps:

1. Verify npx is in PATH:

   bashCopy

   where npx
   # Should return: C:\Program Files\nodejs\npx.cmd
   

2. Test manual execution:

   bashCopy

   npx -y @executeautomation/playwright-mcp-server
   

3. Check internet connection (first run downloads package)

Fix:

• Reinstall Node.js if npx not found
• Clear npx cache: npx clear-npx-cache
• Check Windows Firewall settings

Updating MCP Server Configurations

Scenario: Update PostHog MCP endpoint or token

Step 1: Update .mcp.json:

{
  "posthog": {
    "type": "http",
    "url": "https://new-endpoint.posthog.com/mcp",
    "headers": {
      "Authorization": "Bearer ${POSTHOG_MCP_TOKEN}"
    }
  }
}

Step 2: Update .vscode/mcp.json to match (if needed)

Step 3: Update environment variable:

# .env.local
POSTHOG_MCP_TOKEN=phx_new_token_here

Step 4: Restart Claude Code CLI

Step 5: Verify with /mcp

Rotating MCP Tokens

Best Practice: Rotate tokens every 90 days

Step 1: Generate new token from service provider:

• PostHog: https://app.posthog.com/settings/user-api-keys
• Supabase: https://supabase.com/dashboard/account/tokens

Step 2: Update .env.local:

# Old token (keep temporarily for rollback)
# POSTHOG_MCP_TOKEN=phx_old_token

# New token
POSTHOG_MCP_TOKEN=phx_new_token

Step 3: Test connection

Step 4: Delete old token from provider once confirmed working

Step 5: Remove old token comment from .env.local

Verification Checklist

After any MCP configuration changes:

• .mcp.json is valid JSON
• Environment variables set in .env.local
• Both .mcp.json and .vscode/mcp.json updated (if applicable)
• Documentation updated in .agent/MCP.md
• Claude Code CLI restarted
• /mcp command shows server with ✅ status
• Server tools loadable via ToolSearch
• Test query/command executed successfully

Environment Variable Reference

Current MCP-related environment variables:

# Supabase MCP (optional - project_ref provides read-only)
SUPABASE_MCP_ACCESS_TOKEN=sbp_xxx...

# PostHog MCP (required for MCP server)
# NOTE: Different from app token (phc_ prefix)
POSTHOG_MCP_TOKEN=phx_xxx...

# No environment variables needed for:
# - Google Tag Manager MCP (OAuth)
# - Google Analytics 4 MCP (OAuth)
# - Playwright MCP (local tool)

Server Configuration Template

Use this template when adding new MCP servers:

{
  "mcpServers": {
    "existing-servers": "...",

    "new-server-name": {
      "type": "http|stdio",
      "url": "https://api.example.com/mcp",
      "command": "npx",
      "args": ["-y", "package-name"],
      "headers": {
        "Authorization": "Bearer ${ENV_VAR_NAME}"
      },
      "env": {
        "CUSTOM_ENV": "${CUSTOM_ENV_VAR}"
      },
      "description": "Clear description of server purpose"
    }
  }
}

Choose type:

• http - For HTTP/HTTPS MCP servers
• stdio - For command-line MCP servers (npx, python, etc.)

HTTP servers need:

• url - The MCP endpoint URL
• headers (optional) - Authentication headers
• description - Brief purpose description

stdio servers need:

• command - The executable (e.g., "npx", "python")
• args - Command arguments
• env (optional) - Environment variables for the command
• description - Brief purpose description

Windows-Specific Notes

Path Handling

• Use forward slashes: / not \
• Environment variables: ${VAR_NAME}
• User profile: ${USERPROFILE} or %USERPROFILE%

Command Execution

• npx commands run via Git Bash (if available)
• Claude Code handles Windows/Unix path translation
• No need for cmd /c prefix

OAuth Flows

• Default browser must be set in Windows
• OAuth redirects to localhost
• Check Windows Firewall for localhost blocking

Debugging

# Check environment variable (PowerShell)
$env:POSTHOG_MCP_TOKEN

# Check environment variable (Git Bash)
echo $POSTHOG_MCP_TOKEN

# List environment variables
env | grep MCP

Related Skills

• supabase-patterns - Using Supabase MCP for database operations
• analytics-tracking - Integrating PostHog/GA4 MCP for analytics queries
• testing-patterns - Using Playwright MCP for E2E testing

References

Documentation:

• .agent/MCP.md - Comprehensive MCP documentation
• CLAUDE.md - Project context including MCP servers

External Resources:

• MCP Specification
• Claude Code MCP Docs
• MCP Registry

Configured Servers:

• Supabase MCP
• PostHog MCP
• Stape GTM MCP
• Stape GA4 MCP
• Playwright MCP

Version: 1.0 Last Updated: 2026-01-24 Compatibility: Claude Code Project: StepCountLeague v3