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

.mcp.json

.vscode/mcp.json

.env.local

.agent/MCP.md

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:

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

2. Verify environment variables:

   # 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:

   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:

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

2. Test manual execution:

   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

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