WDG AI Dev Environment

Appearance

MCP (Model Context Protocol) Guide ​

Official documentation for managing MCP servers in the WDG AI Development Environment

Table of Contents ​

  1. Overview
  2. Architecture
  3. Platform Commands
  4. OAuth Authentication
  5. Project Commands
  6. Transport Types
  7. Tool Filtering
  8. Configuration Files
  9. Common Workflows
  10. Troubleshooting

Overview ​

The WDG AI Development Environment uses the Model Context Protocol (MCP) to connect AI assistants (Claude Code, Gemini CLI, Cursor) to external tools and services. The platform provides a two-tier architecture for managing MCP servers:

  • Platform Registry: Shared MCP servers available to all projects
  • Project Configuration: Per-project enablement and customization

Key Features ​

  • Native SSE Support: Direct Server-Sent Events connections without proxies
  • Tool Filtering: Reduce context window usage with mcp-filter
  • Multi-AI Support: Automatic registration with Claude Code, Gemini CLI, Cursor
  • Auto-Sync: Configuration files generated automatically
  • Isolation: Each project controls its own MCP access

Architecture ​

Two-Tier System ​

┌─────────────────────────────────────────┐
│     Platform Registry                    │
│  (mcp-server/registry.json)             │
│                                          │
│  • Stores all registered MCPs            │
│  • Defines transport types               │
│  • Shared across all projects           │
└─────────────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────┐
│   Project Configuration                  │
│  (projects/{project}/mcp-config.json)   │
│                                          │
│  • Enables specific MCPs                 │
│  • Configures tool filtering             │
│  • Project-specific settings             │
└─────────────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────┐
│   Generated Configs                      │
│  (repositories/{repo}/.{ai}/mcp.json)   │
│                                          │
│  • .claude/mcp.json (Claude Code)        │
│  • .gemini/mcp.json (Gemini CLI)         │
│  • .cursor/mcp.json (Cursor)             │
└─────────────────────────────────────────┘

Source Types ​

Projects can reference MCPs in two ways:

Platform Source ("source": "platform")

json
{
  "chrome-devtools": {
    "enabled": true,
    "source": "platform"
  }
}

References platform registry definition.

Direct Source ("source": "direct")

json
{
  "custom-mcp": {
    "enabled": true,
    "source": "direct",
    "transport": "stdio",
    "command": "node",
    "args": ["custom-server.js"]
  }
}

Project defines MCP directly without platform registry.

Platform Commands ​

Platform-level MCP management (available globally):

List Registered MCPs ​

bash
wdg mcp list

Shows all MCPs in the platform registry with their transport types and descriptions.

Add MCP to Platform ​

Adds an MCP server to the platform registry and automatically registers it with Claude Code and Gemini CLI.

STDIO Transport:

bash
wdg mcp add <name> <command> --transport=stdio [--args="arg1,arg2"]

Example:

bash
wdg mcp add github-mcp npx --transport=stdio --args="-y,@modelcontextprotocol/server-github"

SSE Transport:

bash
wdg mcp add <name> <url> --transport=sse [--oauth]

Examples:

bash
# Standard SSE MCP
wdg mcp add atlassian https://mcp.atlassian.com/v1/sse --transport=sse

# OAuth-enabled SSE MCP
wdg mcp add atlassian https://mcp.atlassian.com/v1/sse --transport=sse --oauth

What This Does:

  • Adds MCP to platform registry (mcp-server/registry.json)
  • Registers with Claude Code CLI (platform root)
  • Registers with Gemini CLI (platform root)
  • Makes MCP available for projects to enable

Inspect MCP Details ​

bash
wdg mcp inspect <name>

Shows full configuration including transport, command/URL, and available tools.

Test MCP Connection ​

bash
wdg mcp test <name>

Tests connectivity to an MCP server and validates its configuration.

Delete MCP from Platform ​

bash
wdg mcp delete <name>

Removes MCP from platform registry and cleans up platform root CLI registrations.

What This Does:

  • Removes from platform registry (mcp-server/registry.json)
  • Removes from Claude Code CLI (platform root)
  • Removes from Gemini CLI (platform root, both .mcp.json and .gemini/settings.json)
  • Shows informative message that projects remain unaffected

Important: Platform and project MCPs are completely independent. Deleting from platform only affects the platform root's own configurations. Projects that have enabled this MCP will continue using it with their own configurations.

OAuth Authentication ​

Some MCP servers (like Atlassian) require OAuth 2.1 authentication to access protected resources. The WDG AI Development Environment provides built-in OAuth support with secure token storage and automatic token injection.

Overview ​

The platform implements OAuth 2.1 with PKCE (Proof Key for Code Exchange) for secure authentication:

  • Browser-based authentication flow - Opens default browser for login
  • Encrypted token storage - Tokens stored securely in ~/.wdg/mcp-oauth-tokens.json
  • Automatic token refresh - Handles token expiration transparently
  • Project sync integration - Tokens automatically injected into project configs
  • Tool filtering compatible - Works with mcp-filter for OAuth-enabled MCPs

Authentication Commands ​

List OAuth-Enabled MCPs ​

bash
wdg mcp auth

Shows all MCPs in platform registry that support OAuth authentication.

Authenticate with MCP Server ​

bash
wdg mcp auth <server-name>

Performs OAuth 2.1 authentication flow:

  1. Opens browser to server's login page
  2. User authenticates and grants permissions
  3. Platform receives authorization code
  4. Exchanges code for access and refresh tokens
  5. Stores tokens securely with encryption

Example:

bash
wdg mcp auth atlassian

Expected flow:

🔐 Starting OAuth authentication for atlassian...

Opening browser for authentication...
Waiting for authorization callback...

✅ Authentication successful!
Access token stored securely.

You can now use this MCP in your projects:
  wdg <project> mcp add atlassian
  wdg <project> mcp sync

Check Authentication Status ​

bash
wdg mcp auth:status [server-name]

Shows authentication status for OAuth-enabled MCPs:

bash
# Check all OAuth MCPs
wdg mcp auth:status

# Check specific MCP
wdg mcp auth:status atlassian

Example output:

OAuth Authentication Status
===========================

atlassian:
  ✅ Authenticated
  Expires: 2025-10-24 14:30:00 (23h 59m remaining)
  Scopes: read:jira-work, read:confluence-content.all

github-enterprise:
  ❌ Not authenticated
  Run: wdg mcp auth github-enterprise

Revoke Authentication ​

bash
wdg mcp auth:revoke <server-name>

Removes stored credentials for an MCP:

bash
wdg mcp auth:revoke atlassian

Note: This only deletes local tokens. To fully revoke access, visit the service's authorized apps page.

OAuth Configuration ​

MCP servers requiring OAuth must have oauth metadata in the platform registry:

Platform Registry (mcp-server/registry.json):

json
{
  "mcpServers": {
    "atlassian": {
      "transport": "sse",
      "url": "https://mcp.atlassian.com/v1/sse",
      "description": "Atlassian Cloud (Jira, Confluence)",
      "oauth": {
        "enabled": true,
        "scopes": [
          "read:jira-work",
          "read:jira-user",
          "read:confluence-space.summary",
          "read:confluence-content.all"
        ],
        "audiences": [
          "api.atlassian.com"
        ]
      }
    }
  }
}

OAuth fields:

  • enabled - Set to true to enable OAuth for this MCP
  • scopes - List of OAuth scopes to request
  • audiences - Optional audience claims for token validation

OAuth Discovery ​

The platform automatically discovers OAuth configuration from MCP servers using:

  1. WWW-Authenticate header - Checks server response for OAuth metadata
  2. MCP resource endpoint - Queries server for OAuth configuration
  3. Well-known endpoint - Falls back to .well-known/oauth-authorization-server

If OAuth config is found but not in registry, you'll be prompted to update registry.json.

Token Storage Security ​

OAuth tokens are stored with multiple security layers:

Location: ~/.wdg/mcp-oauth-tokens.json

Security features:

  • File permissions: 0o600 (owner read/write only)
  • Fernet encryption: Symmetric encryption with PBKDF2 key derivation
  • Machine-specific keys: Derived from hostname + username
  • Expiration tracking: 5-minute buffer before expiration

Format (encrypted):

json
{
  "atlassian": {
    "encrypted_credentials": "gAAAAA...",
    "updated_at": "2025-10-23T14:00:00Z"
  }
}

Tokens cannot be copied between machines due to machine-specific encryption keys.

OAuth with Tool Filtering ​

OAuth tokens are dynamically injected at runtime using a wrapper script that handles token retrieval and auto-refresh:

Without OAuth (public MCP):

json
{
  "mcp-name-filtered": {
    "command": "uvx",
    "args": [
      "mcp-filter",
      "run",
      "-t", "http",
      "--http-url", "https://mcp.example.com/sse",
      "-a", "tool1",
      "-a", "tool2"
    ]
  }
}

With OAuth (authenticated MCP) - Dynamic Token Injection:

json
{
  "atlassian-filtered": {
    "command": "bash",
    "args": [
      "${WDG_HOME}/mcp-server/mcp_oauth_wrapper.sh",
      "atlassian",
      "-t", "http",
      "--http-url", "https://mcp.atlassian.com/v1/sse",
      "-a", "jira_search_issues",
      "-a", "confluence_get_page"
    ]
  }
}

How Dynamic Token Injection Works:

  1. Wrapper Script (mcp_oauth_wrapper.sh) runs on each MCP call
  2. Token Lookup - Retrieves current valid token from encrypted storage (~/.wdg/mcp-oauth-tokens.json)
  3. Auto-Refresh - If token is expired, automatically refreshes using refresh token
  4. Environment Variable - Sets MF_HTTP_HEADERS="Authorization=Bearer <token>"
  5. mcp-filter Launch - Executes mcp-filter with the fresh token

Benefits:

  • ✅ Tokens are always fresh (retrieved on each call)
  • ✅ Auto-refresh when expired (~1 hour typical)
  • ✅ No tokens stored in config files
  • ✅ No tokens in process list (uses environment variables)
  • ✅ Works indefinitely without manual intervention
  • ✅ Secure: Tokens encrypted at rest, never logged

Security Notes:

  • Tokens stored in ~/.wdg/mcp-oauth-tokens.json with 600 permissions
  • Machine-specific encryption (cannot copy between machines)
  • Wrapper script never logs or exposes tokens
  • mcp-filter receives tokens via secure environment variables only

OAuth Workflow Example ​

Complete workflow for using OAuth-enabled Atlassian MCP:

bash
# 1. Check if Atlassian MCP is registered
wdg mcp list | grep atlassian

# 2. Authenticate with Atlassian
wdg mcp auth atlassian
# Browser opens → Login → Grant permissions → Success

# 3. Verify authentication
wdg mcp auth:status atlassian
# ✅ Authenticated (scopes, expiration shown)

# 4. Add to project
wdg demo mcp add atlassian

# 5. Optional: Filter tools
wdg demo mcp filter atlassian
# Select: jira_search_issues, confluence_get_page, jira_get_issue

# 6. Sync project configs (includes OAuth token)
wdg demo mcp sync

# 7. Verify in AI tool
claude mcp list
# Should show: atlassian-filtered ✓ Connected (3 tools)

# 8. Use in Claude Code
# Tools are now available with full authentication

Troubleshooting OAuth ​

Authentication fails ​

Check OAuth is enabled in registry:

bash
jq '.mcpServers.atlassian.oauth.enabled' mcp-server/registry.json
# Should return: true

Check port 7777 is available:

bash
lsof -i :7777
# Should return nothing (port free)

Check browser opens:

bash
wdg mcp auth atlassian
# If browser doesn't open, manually visit the URL shown

Token not found after authentication ​

Verify token storage:

bash
ls -la ~/.wdg/mcp-oauth-tokens.json
# Should show: -rw------- (permissions 600)

wdg mcp auth:status atlassian
# Should show: ✅ Authenticated

Check token expiration:

bash
wdg mcp auth:status atlassian
# If expired, re-authenticate:
wdg mcp auth atlassian

MCP not connecting after sync ​

Verify wrapper script in generated config:

bash
# Check if wrapper script is used:
cat projects/demo/repositories/demo/.mcp.json | jq '.mcpServers."atlassian-filtered"'
# Should show: {
#   "command": "bash",
#   "args": ["/path/to/mcp_oauth_wrapper.sh", "atlassian", "-t", "http", ...]
# }

Test wrapper script directly:

bash
# Test token retrieval:
python3 mcp-server/get_token.py atlassian
# Should output a valid token (if authenticated)

# Test wrapper execution:
bash mcp-server/mcp_oauth_wrapper.sh atlassian --help
# Should show mcp-filter help (if token valid)

Common Issues:

  1. "No valid OAuth token found" - Run wdg mcp auth atlassian to authenticate

  2. Token expired - The wrapper auto-refreshes tokens, but if refresh fails:

    • Re-authenticate: wdg mcp auth atlassian
    • Check token status: wdg mcp auth:status atlassian

  3. Wrapper script not executable:

    bash
    chmod +x mcp-server/mcp_oauth_wrapper.sh

  4. Old static token config - Regenerate configs:

    bash
    wdg <project> mcp sync

Check MCP server logs:

bash
# For SSE MCPs, check network connectivity:
curl -v https://mcp.atlassian.com/v1/sse

Re-sync project:

bash
wdg demo mcp sync
# This regenerates configs with latest tokens

Token refresh fails ​

Re-authenticate:

bash
wdg mcp auth:revoke atlassian
wdg mcp auth atlassian
wdg demo mcp sync

Security Best Practices ​

  1. Never commit tokens - .wdg/ directory is git-ignored
  2. Use minimal scopes - Only request permissions needed
  3. Revoke unused access - Delete tokens for unused MCPs
  4. Monitor expiration - Use auth:status to check token health
  5. Separate machines - Tokens can't be shared (machine-specific encryption)

Project Commands ​

Project-specific MCP management:

List Project MCPs ​

bash
wdg <project> mcp list

Shows MCPs enabled for the project with their status.

Add MCP to Project ​

bash
wdg <project> mcp add <name>

Enables a platform-registered MCP for the project and auto-syncs configs.

Example:

bash
wdg demo mcp add chrome-devtools

Remove MCP from Project ​

bash
wdg <project> mcp remove <name>

Disables MCP for the project and removes from configs.

View Available Tools ​

bash
wdg <project> mcp tools <name>

Lists all tools provided by the MCP (connects to server).

Filter MCP Tools ​

bash
wdg <project> mcp filter <name>

Interactive fzf menu to select which tools to allow (reduces context window).

Sync Configuration ​

bash
wdg <project> mcp sync

Regenerates all AI tool configuration files. Automatically runs after add and filter.

Transport Types ​

STDIO (Standard Input/Output) ​

Process-based communication where the AI tool spawns the MCP server as a subprocess.

Platform Registry:

json
{
  "chrome-devtools": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest"]
  }
}

Generated Config:

json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Best for: NPM packages, local scripts, single-instance servers

SSE (Server-Sent Events) ​

HTTP-based communication where the AI tool connects to a running server.

Platform Registry:

json
{
  "wdg-local": {
    "transport": "sse",
    "url": "http://localhost:8765/sse"
  }
}

Generated Config:

json
{
  "mcpServers": {
    "wdg-local": {
      "url": "http://localhost:8765/sse"
    }
  }
}

Best for: Always-running services, remote servers, multiple AI tools sharing one server

Tool Filtering ​

Reduce context window usage by limiting which tools are exposed to the AI.

Why Filter? ​

Large MCPs like chrome-devtools provide 27+ tools. If you only need 6 for your project, filtering reduces:

  • Context window usage by ~78%
  • Tool confusion for the AI
  • Prompt complexity

How It Works ​

Uses the open-source mcp-filter tool to wrap MCPs and expose only selected tools.

Without Filtering:

json
{
  "chrome-devtools": {
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest"]
  }
}

Result: 27 tools available

With Filtering:

json
{
  "chrome-devtools-filtered": {
    "command": "uvx",
    "args": [
      "mcp-filter",
      "run",
      "-t",
      "stdio",
      "--stdio-command",
      "npx",
      "--stdio-arg",
      "-y",
      "--stdio-arg",
      "chrome-devtools-mcp@latest",
      "-a",
      "navigate_page",
      "-a",
      "take_screenshot",
      "-a",
      "list_pages",
      "-a",
      "new_page",
      "-a",
      "click",
      "-a",
      "fill"
    ]
  }
}

Result: 6 tools available (78% reduction)

Filter Workflow ​

  1. View available tools:

    bash
    wdg demo mcp tools chrome-devtools

  2. Configure filtering:

    bash
    wdg demo mcp filter chrome-devtools

    Interactive menu appears - use TAB to select, ENTER to confirm.

  3. Auto-sync: Configuration files automatically updated with filtered version.

  4. Verify:

    bash
    claude mcp list  # or gemini mcp list

Per-Project Filtering ​

Different projects can filter the same MCP differently:

bash
# Project 1: Browser testing (6 tools)
wdg testing-project mcp filter chrome-devtools
# Select: navigate, screenshot, click, fill, list_pages, new_page

# Project 2: Performance analysis (8 tools)
wdg perf-project mcp filter chrome-devtools
# Select: navigate, performance_*, network_*, screenshot

Configuration Files ​

Platform Registry ​

Location: mcp-server/registry.json

Format:

json
{
  "mcpServers": {
    "mcp-name": {
      "transport": "stdio|sse",
      "command": "...",        // For STDIO
      "args": [...],           // For STDIO
      "url": "...",            // For SSE
      "description": "...",
      "installedAt": "2025-10-23T14:00:00Z"
    }
  }
}

Who manages: Platform administrators via wdg mcp commands

Project Configuration ​

Location: projects/{project}/mcp-config.json

Format:

json
{
  "mcpServers": {
    "mcp-name": {
      "enabled": true,
      "source": "platform|direct",
      "allowedTools": [        // Optional: for filtering
        "tool1",
        "tool2"
      ],
      "transport": "...",      // Only for source=direct
      "command": "...",        // Only for source=direct
      "args": [...],           // Only for source=direct
      "url": "..."             // Only for source=direct
    }
  }
}

Who manages: Developers via wdg {project} mcp commands

Default Configuration: When creating a new project with wdg create, the following default MCPs are automatically configured:

  • wdg-local: Direct SSE connection to platform MCP server (http://localhost:8765/sse)
  • chrome-devtools: Platform-sourced browser automation tool

To skip default MCP configuration, use --skip-default-mcps flag:

bash
wdg create my-project --init-wikit --skip-default-mcps

Generated AI Configs ​

Locations:

  • projects/{project}/repositories/{repo}/.claude/mcp.json
  • projects/{project}/repositories/{repo}/.gemini/mcp.json
  • projects/{project}/repositories/{repo}/.cursor/mcp.json

Format: Standard MCP configuration for each AI tool

Who manages: Automatically generated by wdg {project} mcp sync

DO NOT EDIT MANUALLY - Changes will be overwritten on next sync

Common Workflows ​

Workflow 1: Add New Platform MCP ​

bash
# 1. Register at platform level
wdg mcp add github-mcp npx @github/mcp-server

# 2. Verify registration
wdg mcp list

# 3. Add to a project
wdg demo mcp add github-mcp

# 4. Configuration automatically synced
# AI tools now have access to GitHub MCP in demo project

Workflow 2: Filter MCP Tools ​

bash
# 1. View all available tools
wdg demo mcp tools chrome-devtools

# 2. Configure filtering (interactive menu)
wdg demo mcp filter chrome-devtools

# 3. Select tools with TAB, confirm with ENTER

# 4. Verification
claude mcp list
# Should show: chrome-devtools-filtered ✓ Connected (X tools)

Workflow 3: Project-Specific MCP ​

bash
# Create project-specific MCP (not in platform registry)
# Edit: projects/demo/mcp-config.json

{
  "mcpServers": {
    "custom-api": {
      "enabled": true,
      "source": "direct",
      "transport": "sse",
      "url": "http://localhost:9000/mcp"
    }
  }
}

# Sync to generate configs
wdg demo mcp sync

# MCP now available to demo project only

Workflow 4: Share MCP Across Projects ​

bash
# 1. Add to platform once
wdg mcp add shared-tools npx shared-mcp-server

# 2. Enable for multiple projects
wdg project-a mcp add shared-tools
wdg project-b mcp add shared-tools
wdg project-c mcp add shared-tools

# Each project can filter differently
wdg project-a mcp filter shared-tools  # Select 5 tools
wdg project-b mcp filter shared-tools  # Select 10 tools
wdg project-c mcp filter shared-tools  # No filtering (all tools)

Workflow 5: Update MCP Version ​

bash
# Platform MCPs update automatically (npx always uses @latest)
# To force update, delete and re-add:

wdg mcp delete chrome-devtools
wdg mcp add chrome-devtools npx chrome-devtools-mcp@latest

# Re-sync all projects using this MCP
wdg project-a mcp sync
wdg project-b mcp sync

Workflow 6: OAuth-Enabled MCP (Atlassian) ​

bash
# Complete workflow for OAuth-authenticated MCPs

# 1. Verify Atlassian MCP is registered
wdg mcp list
# Should show: atlassian (SSE) - Atlassian Cloud (Jira, Confluence)

# 2. Authenticate with Atlassian
wdg mcp auth atlassian
# Browser opens automatically
# → Login to Atlassian account
# → Grant requested permissions
# → Success message displayed

# 3. Check authentication status
wdg mcp auth:status atlassian
# ✅ Authenticated
# Expires: 2025-10-24 14:30:00 (23h 59m remaining)
# Scopes: read:jira-work, read:confluence-content.all

# 4. Add Atlassian to your project
wdg demo mcp add atlassian

# 5. View available Atlassian tools
wdg demo mcp tools atlassian
# Shows: jira_search_issues, jira_get_issue, confluence_get_page, etc.

# 6. Filter to only needed tools
wdg demo mcp filter atlassian
# Select with TAB:
#   - jira_search_issues
#   - jira_get_issue
#   - confluence_get_page
#   - confluence_search
# Press ENTER to confirm

# 7. Sync generates configs with OAuth token
wdg demo mcp sync
# Configurations updated:
#   - .claude/mcp.json (with Authorization header)
#   - .gemini/mcp.json (with Authorization header)

# 8. Verify connection in Claude Code
claude mcp list
# Should show: atlassian-filtered ✓ Connected (4 tools)

# 9. Test in Claude Code
# Ask: "Search Jira for issues assigned to me"
# Claude will use jira_search_issues tool with authentication

# 10. Monitor token expiration (tokens valid ~24 hours)
wdg mcp auth:status atlassian
# If expired, re-authenticate:
wdg mcp auth atlassian
wdg demo mcp sync  # Updates configs with new token

Troubleshooting ​

MCP Not Connecting ​

Check connection status:

bash
claude mcp list  # or: gemini mcp list

Common issues:

  1. Service not running (SSE)

    bash
    # For wdg-local:
docker compose ps mcp-server
docker compose up -d mcp-server

  2. Wrong transport type

    bash
    # Check registry:
wdg mcp inspect <name>

# Verify generated config matches
cat projects/{project}/repositories/{repo}/.claude/mcp.json

  3. Config not synced

    bash
    # Regenerate configs:
wdg {project} mcp sync

Tool Filtering Not Working ​

Verify filter configuration:

bash
# Check project config has allowedTools:
cat projects/{project}/mcp-config.json

# Should show:
{
  "mcp-name": {
    "enabled": true,
    "source": "platform",
    "allowedTools": ["tool1", "tool2"]
  }
}

Verify mcp-filter in generated config:

bash
# Check for mcp-filter wrapper:
cat projects/{project}/repositories/{repo}/.claude/mcp.json

# Should show command: "uvx" with args including "mcp-filter"

Re-apply filter:

bash
wdg {project} mcp filter <name>
wdg {project} mcp sync

MCP Shows Wrong Tools ​

Clear and re-register:

bash
# For Claude Code:
claude mcp delete <name>
wdg {project} mcp sync  # Re-registers automatically

# For Gemini:
gemini mcp remove <name>
wdg {project} mcp sync

Configuration Conflicts ​

If manually edited configs cause issues:

bash
# Delete project config and start over:
rm projects/{project}/mcp-config.json

# Re-add MCPs:
wdg {project} mcp add <name>
wdg {project} mcp sync

Permission Issues ​

Cannot connect to MCP:

bash
# Check MCP server logs:
docker compose logs mcp-server

# For STDIO MCPs, check command is executable:
which npx
npx chrome-devtools-mcp@latest --help

Best Practices ​

Platform vs Project MCPs ​

✅ Platform Registry:

  • Common tools used across projects (chrome-devtools, atlassian)
  • Stable, well-maintained MCPs
  • MCPs requiring version consistency

✅ Project Direct:

  • Project-specific APIs
  • Experimental MCPs
  • Custom internal tools

Tool Filtering Strategy ​

  1. Start without filtering - Understand what's available
  2. Monitor usage - See which tools AI actually uses
  3. Filter conservatively - Keep tools you might need
  4. Iterate - Adjust based on actual needs

Multi-AI Tool Support ​

The platform automatically registers MCPs with:

  • Claude Code - via claude mcp add
  • Gemini CLI - via gemini mcp add
  • Cursor - via .cursor/mcp.json file

All three get the same MCP configuration for consistency.

Version Management ​

  • Use @latest for NPM packages (auto-updates)
  • Pin versions for stability: npx package@1.2.3
  • Test updates in one project before platform-wide deployment

Additional Resources ​

  • MCP Specification - Official protocol docs
  • mcp-filter - Tool filtering utility
  • Claude Code Docs - Claude Code MCP setup
  • Platform Docs:
    • CLAUDE.md - Platform AI context
    • docs/MCP_SEARCH_PATTERNS.md - Using MCP search tools
    • cli/wdg --help - CLI reference

Summary ​

The WDG AI Development Environment provides a robust MCP management system:

  • Two-tier architecture separates platform registry from project usage
  • Native SSE support eliminates proxy complexity
  • Tool filtering optimizes context window usage
  • Multi-AI support works with Claude Code, Gemini CLI, Cursor
  • Automatic sync keeps configs up-to-date

Use wdg mcp commands for platform management and wdg {project} mcp commands for project-specific configuration.

PageSpeed Insights API Setup ​

The wordpress-site-auditor agent uses the PSI API as its primary lab-measurement layer in Phase 3 (Performance). PSI runs Lighthouse on Google's infrastructure with consistent throttling (4G mobile emulation, slow 4G network), returns CrUX field data in the same response, and ships first-class opportunities + savings estimates that become content in the audit's Recommendations section.

To enable it:

  1. Open the Google Cloud Console.
  2. Create or select a project (one project per WDG environment is fine -- there's no per-client requirement).
  3. Enable PageSpeed Insights API under "APIs & Services -> Library."
  4. Create an API key under "APIs & Services -> Credentials."
  5. Add the key to your .env file: PSI_API_KEY=AIza...
  6. Optional but recommended: restrict the key to "API restrictions: PageSpeed Insights API" to prevent it from being used for other Google APIs by accident.

The same Google Cloud project will host the Chrome UX Report API (already used by the agent for CrUX queries via chrome-devtools-mcp's embedded public key) and, in the future, the Google Analytics Data API (when an auto-pull-top-pages skill ships). One project, one key for public APIs.

If the key is missing, the auditor falls back to Chrome DevTools for lab measurement and notes the fallback in the report's methodology section.

Free quota: 25,000 requests/day per API key -- well above any audit-run requirement (a 10-page audit uses ~10 requests).

Released under the MIT License.

Copyright © 2024 WDG