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.

Method	Who creates the OAuth client	When	Best for	Status
Pre-registered public client id	An operator, once	Ahead of time	Enterprise registries; IdPs with DCR disabled	Supported
Dynamic Client Registration (DCR)	The IDE, automatically	At connect time	Public / multi-tenant registries	Supported
Client ID Metadata Documents (CIMD)	Nobody (id is a URL)	At connect time	Zero-touch without client sprawl	Coming soon

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.

Coding assistant	Keycloak	Amazon Cognito	Okta	Microsoft Entra ID
Claude Code	Client ID + DCR	Client ID (fixed port)	Client ID (fixed port)	Client ID (fixed port, per-server App ID URI)
Cursor	Client ID + DCR	Static token only	Static token only	Static token only
Codex	Client ID + DCR	Static token only	Static token only	Static token only
Other IDEs	DCR (if the IDE supports it)	Static token	Static token	Static token

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 works for Claude Code (issue #990). Entra binds the requested scope to the RFC 8707 resource and matches resource to a registered App ID URI exactly, and a spec client canonicalizes the bare origin with a trailing slash (which Entra App ID URIs cannot have). So on Entra each server advertises a per-server PRM whose resource is its exact connection URL, and the operator must register each server's connection URL as an App ID URI on the gateway app (with a user_impersonation scope exposed on it, granted to the IDE client). See the client-id method doc and Entra scope format. Only Claude Code can pin the callback port Entra's literal redirect match needs, so Cursor/Codex fall back to the static token on Entra as they do on Cognito/Okta.
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:

Enterprise Tool Catalog

Curated MCP servers approved by IT
Consistent across all developer environments
Centralized authentication and governance
Real-time health monitoring

AI Assistant in Action

Natural language tool discovery
Secure execution of enterprise tools
Complete audit trail for compliance
Seamless developer experience

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 in the mcp_scopes collection (DocumentDB / MongoDB)
# Scopes are seeded from the JSON scope seed files in scripts/, or managed via the scope management API

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

Credential Storage
- Store generated configurations in secure locations
- Use environment-specific credentials
- Regularly rotate authentication tokens
Access Control
- Follow principle of least privilege
- Regularly review user permissions
- Monitor tool usage for anomalies
Network Security
- Use HTTPS in production environments
- Restrict network access to authorized IP ranges
- Monitor for unauthorized access attempts

Development Workflow

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!"

Tool Discovery
- Use natural language queries: "find tools for database operations"
- Explore available tools through web interface
- Share useful tool combinations with team

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:

Gateway Authentication - The X-Authorization header for authenticating with the MCP Gateway
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:

Scheme	Description	Example Header
`none`	No backend authentication required	N/A
`bearer`	Bearer token authentication	`Authorization: Bearer <token>`
`api_key`	API key with custom header	`CONTEXT7_API_KEY: <key>` or `X-API-Key: <key>`

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

Gateway Authentication Header (X-Authorization):
- Authenticates the AI coding assistant with the MCP Gateway
- Automatically generated when you open the MCP Configuration modal
- Validates user identity and permissions
Backend Server Authentication Header (e.g., Authorization, CONTEXT7_API_KEY):
- Authenticates the MCP Gateway with the backend MCP server
- The credential is encrypted and stored in the registry during server registration
- Automatically decrypted and included in health checks and tool fetching
Automatic Configuration Generation:
- The Registry UI automatically detects the server's auth scheme
- Both headers are included in the generated configuration
- Works with all supported AI coding assistants (VS Code, Cursor, Cline, Roo Code, Claude Code)

UI Workflow

Open Server Card in the Registry dashboard
Click "Get MCP Config" button
Select Your IDE (VS Code, Cursor, Cline, Roo Code, or Claude Code)
Copy Configuration - The generated config includes both gateway and backend auth headers
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

Navigation Menu

Uh oh!

AI Coding Assistants Setup Guide

Overview

How coding assistants connect (three methods)

Compatibility matrix: coding assistant x identity provider

Prerequisites

Supported AI Development Tools

VS Code MCP Extension

Roo Code Plugin - Enterprise Showcase

Claude Code

Cursor

Cline (formerly Claude Dev)

Custom MCP Clients

Configuration Management

Automatic Token Refresh

Manual Configuration Updates

Environment-Specific Configurations

Troubleshooting

Authentication Issues

Configuration Issues

Best Practices

Security

Development Workflow

Enterprise Deployment Considerations

Scale Considerations

Compliance & Governance

Cost Optimization

Backend Server Authentication

Supported Authentication Schemes

Example Configurations

Example 1: API Key Authentication (Context7)

Example 2: Bearer Token Authentication (Cloudflare)

How It Works

UI Workflow

Registry-Only Mode

Support & Resources

Uh oh!

FilesExpand file tree

ai-coding-assistants-setup.md

Latest commit

History

ai-coding-assistants-setup.md

File metadata and controls

AI Coding Assistants Setup Guide

Overview

How coding assistants connect (three methods)

Compatibility matrix: coding assistant x identity provider

Prerequisites

Supported AI Development Tools

VS Code MCP Extension

Roo Code Plugin - Enterprise Showcase

Claude Code

Cursor

Cline (formerly Claude Dev)

Custom MCP Clients

Configuration Management

Automatic Token Refresh

Manual Configuration Updates

Environment-Specific Configurations

Troubleshooting

Authentication Issues

Configuration Issues

Best Practices

Security

Development Workflow

Enterprise Deployment Considerations

Scale Considerations

Compliance & Governance

Cost Optimization

Backend Server Authentication

Supported Authentication Schemes

Example Configurations

Example 1: API Key Authentication (Context7)

Example 2: Bearer Token Authentication (Cloudflare)

How It Works

UI Workflow

Registry-Only Mode

Support & Resources