MCP Gateway & Registry - Frequently Asked Questions (FAQ)

MCP Gateway & Registry - Frequently Asked Questions (FAQ)

This FAQ addresses common questions from different user personas working with the MCP Gateway & Registry system. Questions are organized by user type and complexity level.

Table of Contents

• AI App Developer Questions
• Platform Level Questions
• General Questions

AI App Developer Questions

Questions from developers building AI applications that use the Registry and Gateway to discover and use MCP servers and tools.

Q1: How do I discover available MCP tools for my AI agent?

A: You can discover tools in several ways:

1. Dynamic Tool Discovery (Recommended): Use the intelligent_tool_finder tool with natural language queries:

   tools = await intelligent_tool_finder(
       natural_language_query="get current time in different timezones",
       session_cookie="your_session_cookie"
   )
   

2. Web Interface: Browse available tools at http://your-gateway-url:7860 after authentication.

3. Direct MCP Connection: Connect to the registry MCP server at /mcpgw/sse and use standard MCP tools/list calls.

Q2: What's the difference between user identity and agent identity authentication modes?

A: There are two authentication patterns:

• User Identity Mode: Your agent acts on behalf of a human user

  • Uses OAuth 2.0 PKCE flow with session cookies
  • Agent inherits user's permissions based on Cognito groups
  • Use --use-session-cookie flag when running agents
  • Best for: Interactive applications, user-driven tasks

• Agent Identity Mode: Your agent has its own identity

  • Uses Machine-to-Machine (M2M) JWT tokens
  • Agent has its own scopes assigned in Cognito
  • Default mode when running agents
  • Best for: Autonomous agents, scheduled tasks, background processing

See Authentication Documentation for detailed setup instructions.

Q3: How do I connect my agent to multiple MCP servers through the gateway?

A: The gateway provides a single endpoint with path-based routing:

# Connect to different servers via the gateway using SSE client
from mcp import ClientSession
from mcp.client.sse import sse_client

async def connect_to_server(server_url):
    async with sse_client(server_url) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            # Use the session for tool calls
            return session

# Example server URLs through the gateway
server_url = f"https://your-gateway.com/currenttime/sse"
time_session = await connect_to_server(server_url)

# Or use the registry's tool discovery
registry_url = f"https://your-gateway.com/mcpgw/sse"
registry_session = await connect_to_server(registry_url)

All requests go through the same gateway with authentication handled centrally.

Q4: What authentication headers do I need to include in my MCP requests?

A: For M2M Authentication (Agent Identity):

headers = {
    'Authorization': f'Bearer {jwt_token}',
    'X-User-Pool-Id': 'us-east-1_XXXXXXXXX',
    'X-Client-Id': 'your-client-id',
    'X-Region': 'us-east-1'
}

For Session Cookie Authentication (User Identity):

headers = {
    'Cookie': f'mcp_gateway_session={session_cookie}',
    'X-User-Pool-Id': 'us-east-1_XXXXXXXXX',
    'X-Client-Id': 'your-client-id',
    'X-Region': 'us-east-1'
}

Q5: How do I handle tool discovery when I don't know what tools are available?

A: Use the Dynamic Tool Discovery feature:

1. In your agent code:

   # Let your agent discover tools autonomously
   tools = await intelligent_tool_finder(
       natural_language_query="I need to get stock market data",
       session_cookie=session_cookie,
       top_n_tools=3
   )
   
   # Then invoke the discovered tool
   if tools:
       result = await invoke_mcp_tool(
           server_name=tools[0]["service_path"],
           tool_name=tools[0]["tool_name"],
           arguments={"symbol": "AAPL"},
           # ... auth parameters
       )
   

2. Configure your agent with tool discovery capabilities as shown in the Dynamic Tool Discovery guide.

Q6: What's the best way to handle authentication errors in my application?

A: Implement proper error handling for common authentication scenarios:

try:
    result = await mcp_client.call_tool(tool_name, arguments)
except AuthenticationError as e:
    if "token expired" in str(e):
        # Refresh JWT token or re-authenticate user
        await refresh_authentication()
        result = await mcp_client.call_tool(tool_name, arguments)
    elif "access denied" in str(e):
        # User lacks required scopes
        logger.error(f"Insufficient permissions for {tool_name}")
        return "Sorry, you don't have permission to use this tool."
    else:
        # Other auth errors
        logger.error(f"Authentication failed: {e}")
        return "Authentication failed. Please check your credentials."

Q7: How do I test my agent's integration with the MCP Gateway locally?

A: Follow these steps:

1. Set up local environment:

   git clone https://github.com/agentic-community/mcp-gateway-registry.git
   cd mcp-gateway-registry
   cp .env.template .env
   # Configure your .env file
   ./build_and_run.sh
   

2. Test authentication:

   # For user identity mode
   cd agents/
   python cli_user_auth.py
   python agent.py --use-session-cookie --message "test message"
   
   # For agent identity mode
   python agent.py --message "test message"
   

3. Access the web interface at http://localhost:7860 to verify server registration and tool availability.

Platform Level Questions

Q8: What are the minimum system requirements for deploying the MCP Gateway & Registry?

A: Minimum Requirements:

• EC2 Instance: t3.large or larger (2 vCPU, 8GB RAM)
• Operating System: Ubuntu 20.04 LTS or newer
• Storage: 20GB+ available disk space
• Network: Ports 80, 443, 7860, 8080 accessible

Recommended for Production:

• EC2 Instance: t3.2xlarge (8 vCPU, 32GB RAM)
• Storage: 50GB+ SSD storage
• Load Balancer: Application Load Balancer for load distribution and redundancy
• SSL Certificate: Valid SSL certificate for HTTPS

Q9: How do I set up Amazon Cognito for authentication?

A: Follow the step-by-step Cognito Setup Guide:

1. Create User Pool with email/username sign-in
2. Configure App Client with proper callback URLs
3. Set up User Groups (e.g., mcp-registry-admin, mcp-registry-user)
4. Create Resource Server for M2M authentication with custom scopes
5. Configure Environment Variables in your .env file

Key environment variables needed:

COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
COGNITO_CLIENT_ID=your-client-id
COGNITO_CLIENT_SECRET=your-client-secret
AWS_REGION=us-east-1

Q10: What ports need to be open in my security group?

A: For HTTP Deployment:

• Port 80 (HTTP traffic)
• Port 7860 (Registry web interface)
• Port 8080 (Auth server)

For HTTPS Deployment:

• Port 443 (HTTPS traffic)
• Port 7860 (Registry web interface, if needed)
• Port 8080 (Auth server, if needed)

For Development/Testing:

• All above ports plus any custom MCP server ports (8000-8003 by default)

Q11: How do I deploy the solution using Docker Compose?

A: The deployment is automated with the provided script:

1. Clone and configure:

   git clone https://github.com/agentic-community/mcp-gateway-registry.git
   cd mcp-gateway-registry
   cp .env.template .env
   # Edit .env with your configuration
   

2. Create required directories:

   mkdir -p ${HOME}/mcp-gateway/{servers,auth_server,logs}
   cp -r registry/servers ${HOME}/mcp-gateway/
   cp auth_server/scopes.yml ${HOME}/mcp-gateway/auth_server/scopes.yml
   

3. Deploy:

   ./build_and_run.sh
   

The script handles Docker image building, service orchestration, and health checks.

Q12: How do I configure HTTPS with SSL certificates?

A: For production HTTPS deployment:

1. Prepare SSL certificates:

   # Create the ssl directory structure
   mkdir -p ${HOME}/mcp-gateway/ssl/certs
   mkdir -p ${HOME}/mcp-gateway/ssl/private
   
   # Copy your certificate files
   # Replace paths below with your actual certificate locations
   cp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem
   cp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem
   
   # Set proper permissions
   chmod 644 ${HOME}/mcp-gateway/ssl/certs/fullchain.pem
   chmod 600 ${HOME}/mcp-gateway/ssl/private/privkey.pem
   

2. Update security group to allow port 443

3. Deploy normally - the build_and_run.sh script automatically detects and configures SSL certificates:

   ./build_and_run.sh
   

   Note: If SSL certificates are not present at ${HOME}/mcp-gateway/ssl/certs/fullchain.pem and ${HOME}/mcp-gateway/ssl/private/privkey.pem, the MCP Gateway will automatically run in HTTP-only mode.

4. Access via HTTPS:

   • Main interface: https://your-domain.com
   • MCP servers: https://your-domain.com/server-name/sse

Q13: How do I add new MCP servers to the registry?

A: You can add servers through the web interface:

1. Access the registry at http://your-gateway:7860
2. Login with your Cognito credentials or admin credentials
3. Click "Register Server" button
4. Fill in server details:
   • Server Name: Display name
   • Path: URL path (e.g., /my-service)
   • Proxy Pass URL: Internal server URL (e.g., http://localhost:8001)
   • Description: Optional description
   • Tags: Optional categorization tags

The registry will automatically:

• Update the Nginx configuration
• Perform health checks
• Discover available tools
• Update the FAISS index for tool discovery

Q14: How do I monitor the health of MCP servers?

A: The registry provides built-in health monitoring:

1. Web Interface: View server status at http://your-gateway:7860

   • Green: Healthy servers
   • Red: Servers with issues
   • Gray: Disabled servers

2. Manual Health Checks: Click the refresh icon (🔄) on any server card

3. Logs: Monitor service logs:

   # View all service logs
   docker-compose logs -f
   
   # View specific service logs
   docker-compose logs -f registry
   docker-compose logs -f auth-server
   

4. API Endpoint: Programmatic health checks via /health endpoints

Q15: What should I do if authentication is not working?

A: Follow this troubleshooting checklist:

1. Verify Cognito Configuration:

   • Check User Pool ID format: us-east-1_XXXXXXXXX
   • Verify Client ID and Secret are correct
   • Ensure callback URLs match exactly

2. Check Environment Variables:

   # Verify .env file has all required variables
   cat .env | grep -E "(COGNITO|AWS_REGION|SECRET_KEY)"
   

3. Test Authentication Flows:

   # Test user authentication
   cd agents/
   python cli_user_auth.py
   
   # Test M2M authentication
   python -c "from auth_server.cognito_utils import generate_token; print('M2M test passed')"
   

4. Review Logs:

   docker-compose logs -f auth-server | grep -i error
   

5. Common Issues:

   • Callback URL mismatch: Add all required URLs to Cognito app client
   • Secret key mismatch: Ensure same SECRET_KEY in registry and agent configs
   • Scope issues: Verify group mappings in scopes.yml

Advanced Platform Engineer Questions

Q16: What is the architectural pattern used by the MCP Gateway, and what are its trade-offs?

A: The MCP Gateway uses a Reverse Proxy Pattern with Path-Based Routing:

Architecture:

• Nginx as the reverse proxy layer
• Path-based routing (/server-name/* → backend server)
• Centralized authentication via dedicated auth server
• Service discovery through registry MCP server

Q17: How does the fine-grained access control system work, and how can it be extended?

A: The FGAC system uses a Scope-Based Authorization Model:

Core Components:

1. Scope Configuration (scopes.yml): Defines permissions
2. Group Mappings: Maps IdP groups to scopes
3. Validation Engine: Enforces access decisions

Authorization Flow:

graph LR
    A[Request] --> B[Extract Credentials]
    B --> C[Validate with IdP]
    C --> D[Map to Scopes]
    D --> E[Check Server Access]
    E --> F[Check Method Access]
    F --> G[Check Tool Access]
    G --> H[Grant/Deny]

Extension Points:

1. Custom Scope Types:

   # Add new scope categories
   Custom-Scopes:
     data-scientist-tools:
       - server: analytics
         methods: [tools/call]
         tools: [ml_model, data_analysis]
   

2. Dynamic Scope Resolution:

   # Implement custom scope resolver
   def resolve_dynamic_scopes(user_context, request_context):
       # Custom logic based on time, location, etc.
       return computed_scopes
   

3. Attribute-Based Access Control (ABAC):

   # Extend validation with attributes
   def validate_with_attributes(user_attrs, resource_attrs, env_attrs):
       # Policy evaluation engine
       return access_decision
   

Q18: What are the performance characteristics and bottlenecks of the current implementation?

A: Performance Profile:

Throughput:

• Nginx Proxy: Metrics TBD and would be updated soon
• Auth Validation: Metrics TBD and would be updated soon
• Tool Discovery: Metrics TBD and would be updated soon

Latency Breakdown:

• Proxy Overhead: Metrics TBD and would be updated soon
• Auth Validation: Metrics TBD and would be updated soon
• MCP Server Call: Variable (depends on tool complexity)
• Tool Discovery: Metrics TBD and would be updated soon

Bottlenecks:

1. Authentication Server:

   • Issue: IdP validation latency
   • Mitigation: JWT token caching, connection pooling
   • Scaling: Multiple auth server instances

2. FAISS Index Operations:

   • Issue: Memory usage and search latency
   • Mitigation: Index optimization, model selection
   • Scaling: Distributed search, GPU acceleration

3. Nginx Configuration Updates:

   • Issue: Config reload during server registration
   • Mitigation: Graceful reloads, configuration templating
   • Scaling: Dynamic upstream configuration

Optimization Opportunities:

# 1. Implement connection pooling
async def create_connection_pool():
    return aiohttp.TCPConnector(limit=100, limit_per_host=30)

# 2. Add response caching
@lru_cache(maxsize=1000)
def cache_tool_metadata(server_name: str):
    return expensive_tool_discovery()

# 3. Implement circuit breakers
@circuit_breaker(failure_threshold=5, timeout=30)
async def call_mcp_server(server_url: str):
    return await make_request(server_url)

Q19: How can the system be extended to support federated registries?

A: Federated Registry Architecture (Roadmap item #37):

General Questions

Q20: What is the Model Context Protocol (MCP) and why do I need a gateway?

A: Model Context Protocol (MCP) is an open standard that allows AI models to connect with external systems, tools, and data sources.

Why You Need a Gateway:

• Service Discovery: Find approved MCP servers in your organization
• Centralized Access Control: Secure, governed access to tools
• Dynamic Tool Discovery: Agents can find new tools autonomously
• Simplified Client Configuration: Single endpoint for multiple servers
• Enterprise Security: Authentication, authorization, and audit logging

Without Gateway: Each agent connects directly to individual MCP servers With Gateway: All agents connect through a single, secure, managed endpoint

Q21: What's the difference between the Registry and the Gateway?

A: They are complementary components:

Registry:

• Purpose: Service discovery and management
• Features: Web UI, server registration, health monitoring, tool catalog
• Users: Platform administrators, developers
• Access: Web browser at :7860

Gateway:

• Purpose: Secure proxy for MCP protocol traffic
• Features: Authentication, authorization, request routing
• Users: AI agents, MCP clients
• Access: MCP protocol at /server-name/sse

Together: Registry manages what's available, Gateway controls access to it.

Q22: Can I use this with non-AWS identity providers?

A: Currently, the system is designed for Amazon Cognito, but the architecture supports other OAuth2/OIDC providers.

Supported Patterns:

• OAuth 2.0 Authorization Code flow (PKCE)
• OAuth 2.0 Client Credentials flow (M2M)
• JWT token validation
• Group-based authorization

To Add New IdP:

1. Implement IdP-specific authentication in auth_server/
2. Update token validation logic
3. Map IdP groups/roles to MCP scopes
4. Update environment configuration

Potential IdPs: Azure AD, Okta, Auth0, Keycloak, Google Identity

Q23: How do I contribute to the project or report issues?

A: Contributing:

1. GitHub Repository: agentic-community/mcp-gateway-registry
2. Issues: Report bugs or request features via GitHub Issues
3. Pull Requests: Submit code contributions following the project guidelines
4. Documentation: Help improve documentation and examples

Getting Help:

• GitHub Issues: For bugs and feature requests
• Discussions: For questions and community support
• Documentation: Check existing docs first

Development Setup:

git clone https://github.com/agentic-community/mcp-gateway-registry.git
cd mcp-gateway-registry
# Follow development setup in README.md

Q24: What's on the roadmap for future development?

A: Major Features (from GitHub Issues):

• Multi-Level Registry Support: Federated registries with cross-IdP authentication
• Usage Metrics and Analytics: Comprehensive usage tracking and analytics
• Tool Popularity Scoring: Rating system for tools and servers

Authentication & Identity Enhancements:

• Additional IdP integrations
• Enhanced RBAC capabilities

See the full roadmap in the README for complete details.

Need More Help?

• Documentation: Check the docs/ folder for detailed guides
• Examples: See agents/ for working code examples
• Issues: Report problems on GitHub Issues
• Community: Join discussions and get support from the community

This FAQ is maintained by the MCP Agentic community. Last updated: June 16, 2025