AI Coding Assistants Setup Guide¶

Complete guide for integrating the MCP Gateway & Registry with popular AI development tools.

Overview¶

The MCP Gateway automatically generates configuration files for various AI coding assistants, enabling seamless access to enterprise-curated MCP servers with proper authentication and governance.

How coding assistants connect (three methods)¶

A coding assistant connecting to a gateway-protected MCP server needs an OAuth client_id to start the login flow. There are three ways to provide it. They are not ranked alternatives - each fits a different scale and IdP posture. Pick based on your deployment.

Short version:

• Pre-registered public client id - an operator registers one public PKCE client and the registry advertises its id (IDE_OAUTH_CLIENT_ID, or per-server oauth_client_id). Simple, no client sprawl, full per-user audit. The right default for an enterprise registry, and the only option when the IdP has anonymous DCR disabled.
• DCR - the IDE self-registers a client on the fly. Zero-touch and scalable, but needs DCR enabled and creates client sprawl in the IdP.
• CIMD - the client_id is an https URL to a metadata document; nothing is registered. Zero-touch with no sprawl, but newest and least supported. Not yet implemented here.

In all three, the user logs in as themselves in the browser and the IDE receives a per-user token; the client id only identifies the application, not the user. Actual access is derived from the token's groups claim, not from the requested OAuth scopes.

Compatibility matrix: coding assistant x identity provider¶

Which connection method works for each coding assistant against each IdP. CIMD (Client ID Metadata Documents) is not yet implemented; it is on the roadmap - so it is omitted from the cells below. Each cell lists the methods that work today.

Legend: Client ID = pre-registered public client (IDE_OAUTH_CLIENT_ID). DCR = Dynamic Client Registration. A "fixed port" note means the IdP requires IDE_OAUTH_CALLBACK_PORT and only Claude Code can honor it.

Notes:

• Keycloak is the most flexible: it accepts a wildcard loopback redirect (http://localhost/*), so no fixed port is needed, and it supports anonymous DCR. Both methods work for all assistants.
• Cognito / Okta match the redirect URI literally (including the port), so the Client ID method requires a fixed callback port (IDE_OAUTH_CALLBACK_PORT). Only Claude Code can pin the port (--callback-port), so it is the only assistant that completes the Client ID login flow there today. Codex has no port-pinning flag and Cursor's JSON config has no port field, so they use a random port that fails the literal redirect match - they fall back to the static gateway token.
• The Connect dialog only presents the DCR-style (token-less) config when the provider is Keycloak (the dialog treats auth_provider == "keycloak" as "DCR available"; see the DCR method doc). So for Cognito/Okta, non-Claude-Code assistants get the static-token config, not DCR, even though those IdPs technically support DCR.
• Entra IDE login is blocked pending resource-qualified PRM scopes (issue #990), regardless of assistant.
• Validated this release: Keycloak (Client ID + DCR), Cognito (Client ID with Claude Code, on ECS), Okta (Client ID with Claude Code). See the client-id method doc for per-IdP setup.

Prerequisites¶

• MCP Gateway & Registry deployed and running
• Authentication credentials generated via ./credentials-provider/generate_creds.sh
• Access to the AI coding assistant of your choice

Supported AI Development Tools¶

VS Code MCP Extension¶

Microsoft's popular editor with native MCP support.

Setup:

# Copy generated configuration
cp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json

# Alternative: Merge with existing settings
cat .oauth-tokens/vscode-mcp.json >> ~/.vscode/settings.json

Configuration Format:

{
  "mcp": {
    "servers": {
      "mcpgw": {
        "url": "https://your-gateway.com/mcpgw/mcp",
        "headers": {
          "Authorization": "Bearer eyJ...",
          "X-User-Pool-Id": "us-east-1_vm1115QSU",
          "X-Client-Id": "5v2rav1v93...",
          "X-Region": "us-east-1"
        },
        "transport": "streamable-http"
      }
    }
  }
}

Roo Code Plugin - Enterprise Showcase¶

Roo Code demonstrates the power of enterprise governance for AI development tools.

Setup:

# Copy Roo Code configuration
cp .oauth-tokens/mcp.json ~/.vscode/mcp_settings.json

Alternative Setup Options:

# Option 1: Direct copy (recommended)
cp .oauth-tokens/mcp.json ~/.vscode/mcp_settings.json

# Option 2: Create symbolic link for automatic updates
ln -sf "$(pwd)/.oauth-tokens/mcp.json" ~/.vscode/mcp_settings.json

Enterprise Use Case:

Key Enterprise Benefits:

Centralized Control - IT teams manage approved MCP servers across all development environments - Consistent tool availability regardless of developer setup - Rapid deployment of new tools to entire organization

Secure Authentication
- All tool access routes through enterprise identity systems (Amazon Cognito) - No individual API key management required - Automatic token refresh and rotation via Token Refresh Service

Usage Analytics & Compliance - Track which developers use which tools and when - Generate compliance reports for audit requirements - Monitor tool adoption and usage patterns across teams

Developer Productivity - Zero configuration required for approved tools - Instant access to new enterprise tools as they're approved - Same experience across VS Code, Cursor, Claude Code, and other assistants

Claude Code¶

Anthropic's coding assistant with standardized MCP configurations.

Setup:

# Claude Code uses similar JSON format
cp .oauth-tokens/vscode-mcp.json ~/.claude-code/mcp-config.json

Features: - Natural language interaction with MCP tools - Context-aware tool suggestions - Integrated code generation and tool execution

Cursor¶

AI-first code editor with advanced MCP integration.

Setup:

# Cursor configuration (similar to VS Code)
cp .oauth-tokens/vscode-mcp.json ~/.cursor/mcp-settings.json

Advanced Features: - Multi-file context for tool operations - Predictive tool suggestions based on code context - Integrated diff view for tool-generated changes

OAuth login button (no embedded token): see How coding assistants connect below, in particular the pre-registered public client id method.

Cline (formerly Claude Dev)¶

Autonomous coding agent compatible with VS Code.

Setup:

# Cline uses VS Code-style configuration
cp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json

Autonomous Capabilities: - Goal-directed tool usage - Multi-step task execution - Error handling and retry logic

Custom MCP Clients¶

For custom applications or other MCP clients:

Use Raw Authentication:

# Access authentication details directly
cat .oauth-tokens/ingress.json

Example Integration:

import json
import mcp
from mcp.client.sse import sse_client

# Load authentication from generated file
with open('.oauth-tokens/ingress.json') as f:
    auth = json.load(f)

headers = {
    'Authorization': f'Bearer {auth["access_token"]}',
    'X-User-Pool-Id': auth['user_pool_id'],
    'X-Client-Id': auth['client_id'],
    'X-Region': auth['region']
}

# Connect to MCP server
async with sse_client('https://gateway.com/mcpgw/sse', headers=headers) as (read, write):
    async with mcp.ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

Configuration Management¶

Automatic Token Refresh¶

The MCP Gateway includes an Automated Token Refresh Service that provides continuous token management:

# Start the token refresh service (runs in background)
./start_token_refresher.sh

# Service automatically:
# - Monitors token expiration (1-hour buffer by default)
# - Refreshes tokens before they expire
# - Updates all MCP client configurations
# - Generates fresh configs for all AI assistants

Key Benefits: - Zero Downtime: Tokens refresh automatically before expiration - Continuous Operation: AI assistants never lose access due to expired tokens - Multiple Client Support: Updates configurations for VS Code, Roo Code, Claude Code, etc. - Background Operation: Runs as a service with comprehensive logging

Manual Configuration Updates¶

If you need to manually regenerate configurations:

# Regenerate all configurations
./credentials-provider/generate_creds.sh

# Copy updated configurations to AI assistants
./scripts/update-ai-assistants.sh  # Custom script you can create

For AI assistants using symbolic links (recommended setup), configuration updates are automatic since they point to the live .oauth-tokens/ files.

Environment-Specific Configurations¶

Development Environment:

# Generate development configurations
ENVIRONMENT=dev ./credentials-provider/generate_creds.sh
cp .oauth-tokens/dev-* ~/.vscode/

Production Environment:

# Generate production configurations  
ENVIRONMENT=prod ./credentials-provider/generate_creds.sh
cp .oauth-tokens/prod-* ~/.vscode/

Troubleshooting¶

Authentication Issues¶

Token Expired:

If using Token Refresh Service (recommended):

# Check if token refresh service is running
ps aux | grep token_refresher

# Restart token refresh service if needed
./start_token_refresher.sh

# Check service logs
tail -f token_refresher.log

Manual token refresh:

# Regenerate credentials
./credentials-provider/generate_creds.sh
# Update AI assistant configurations

Permission Denied:

# Check user permissions in Cognito
aws cognito-idp admin-list-groups-for-user \
  --user-pool-id YOUR_POOL_ID \
  --username YOUR_USERNAME

# Verify scope configuration
cat auth_server/scopes.yml

Configuration Issues¶

Tools Not Appearing:

# Verify MCP server health
curl -H "Authorization: Bearer TOKEN" \
  https://your-gateway.com/server-name/sse

# Check AI assistant logs
tail -f ~/.vscode/logs/mcp.log

Connection Failures:

# Test gateway connectivity
./tests/mcp_cmds.sh ping

# Verify SSL certificates (if using HTTPS)
openssl s_client -connect your-gateway.com:443

Best Practices¶

Security¶

1. Credential Storage
2. Store generated configurations in secure locations
3. Use environment-specific credentials

4. Regularly rotate authentication tokens

5. Access Control

6. Follow principle of least privilege
7. Regularly review user permissions

8. Monitor tool usage for anomalies

9. Network Security

10. Use HTTPS in production environments
11. Restrict network access to authorized IP ranges
12. Monitor for unauthorized access attempts

Development Workflow¶

1. Team Onboarding

   # Create onboarding script
   #!/bin/bash
   ./credentials-provider/generate_creds.sh
   cp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json
   echo "MCP Gateway configured successfully!"
   

2. Tool Discovery

3. Use natural language queries: "find tools for database operations"
4. Explore available tools through web interface

5. Share useful tool combinations with team

6. Automation

   # Automate configuration updates
   crontab -e
   # Add: 0 9 * * * /path/to/update-mcp-config.sh
   

Enterprise Deployment Considerations¶

Scale Considerations¶

• Large Teams (100+ developers): Consider load balancing and caching
• Global Teams: Deploy regional gateways for reduced latency
• High Security: Use private networking and enhanced monitoring

Compliance & Governance¶

• Audit Requirements: Enable comprehensive logging
• Data Residency: Deploy in compliant regions
• Access Reviews: Implement periodic permission audits

Cost Optimization¶

• Resource Management: Monitor gateway resource usage
• Tool Usage: Analyze tool usage patterns for optimization
• License Management: Track per-developer tool usage

Backend Server Authentication¶

When MCP servers require their own authentication (API keys, bearer tokens, etc.), the MCP Gateway Registry provides automatic configuration generation that includes both:

1. Gateway Authentication - The X-Authorization header for authenticating with the MCP Gateway
2. Backend Server Authentication - The server's own auth header (Authorization, custom API key headers, etc.)

Supported Authentication Schemes¶

The registry supports three backend authentication schemes:

Example Configurations¶

Example 1: API Key Authentication (Context7)¶

Server Details: - Display Name: Context7 - Auth Scheme: api_key - Auth Header: CONTEXT7_API_KEY - Credential: API key provided during registration

Generated MCP Configuration (VS Code):

{
  "servers": {
    "context7": {
      "type": "http",
      "url": "https://mcpgateway.ddns.net/context7/mcp",
      "headers": {
        "X-Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "CONTEXT7_API_KEY": "[YOUR_API_KEY]"
      }
    }
  }
}

Generated MCP Configuration (Roo Code/Cline):

{
  "mcpServers": {
    "context7": {
      "type": "streamable-http",
      "url": "https://mcpgateway.ddns.net/context7/mcp",
      "disabled": false,
      "headers": {
        "X-Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "CONTEXT7_API_KEY": "[YOUR_API_KEY]"
      }
    }
  }
}

Example 2: Bearer Token Authentication (Cloudflare)¶

Server Details: - Display Name: Cloudflare API - Auth Scheme: bearer - Auth Header: Authorization - Credential: Bearer token provided during registration

Generated MCP Configuration (VS Code):

{
  "servers": {
    "cloudflare-api": {
      "type": "http",
      "url": "https://mcpgateway.ddns.net/cloudflare-api/mcp",
      "headers": {
        "X-Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "Authorization": "Bearer [YOUR_SERVER_AUTH_TOKEN]"
      }
    }
  }
}

How It Works¶

1. Gateway Authentication Header (X-Authorization):
2. Authenticates the AI coding assistant with the MCP Gateway
3. Automatically generated when you open the MCP Configuration modal

4. Validates user identity and permissions

5. Backend Server Authentication Header (e.g., Authorization, CONTEXT7_API_KEY):

6. Authenticates the MCP Gateway with the backend MCP server
7. The credential is encrypted and stored in the registry during server registration

8. Automatically decrypted and included in health checks and tool fetching

9. Automatic Configuration Generation:

10. The Registry UI automatically detects the server's auth scheme
11. Both headers are included in the generated configuration
12. Works with all supported AI coding assistants (VS Code, Cursor, Cline, Roo Code, Claude Code)

UI Workflow¶

1. Open Server Card in the Registry dashboard
2. Click "Get MCP Config" button
3. Select Your IDE (VS Code, Cursor, Cline, Roo Code, or Claude Code)
4. Copy Configuration - The generated config includes both gateway and backend auth headers
5. Paste into your IDE's MCP settings file

Screenshot Example:

Registry-Only Mode¶

In registry-only deployment mode (catalog mode), only the backend server authentication is included:

{
  "mcpServers": {
    "context7": {
      "type": "streamable-http",
      "url": "https://context7-direct-endpoint.com/mcp",
      "disabled": false,
      "headers": {
        "CONTEXT7_API_KEY": "[YOUR_API_KEY]"
      }
    }
  }
}

See Registry Deployment Modes for more details on deployment configurations.

Support & Resources¶

• Configuration Reference - Complete configuration options
• Authentication Guide - Identity provider setup and server credential management
• Server Registration - How to register servers with auth credentials
• Troubleshooting Guide - Common issues and solutions
• API Reference - Programmatic management
• GitHub Discussions - Community support