MCP AI Bridge

MCP AI Bridge

A secure Model Context Protocol (MCP) server that bridges Claude Code with OpenAI and Google Gemini APIs.

Features

• OpenAI Integration: Access GPT-4o, GPT-4o Mini, GPT-4 Turbo, GPT-4, and reasoning models (o1, o1-mini, o1-pro, o3-mini)
• Gemini Integration: Access Gemini 1.5 Pro, Gemini 1.5 Flash, and vision models with latest capabilities
• Security Features:
  • Enhanced Input Validation: Multi-layer validation with sanitization
  • Content Filtering: Blocks explicit, harmful, and illegal content
  • Prompt Injection Detection: Identifies and blocks manipulation attempts
  • Rate Limiting: Prevents API abuse with configurable limits
  • Secure Error Handling: No sensitive information exposure
  • API Key Validation: Format validation for API keys
  • Configurable Security Levels: Basic, Moderate, and Strict modes
• Robust Error Handling: Specific error types with detailed messages
• Structured Logging: Winston-based logging with configurable levels
• Flexible Configuration: Control temperature and model selection for each request

Installation

1. Clone or copy the mcp-ai-bridge directory to your preferred location
2. Install dependencies:

3. Configure your API keys using ONE of these methods:Option A: Use global .env file in your home directory (Recommended)
   • Create or edit ~/.env file
   • Add your API keys:
     OPENAI_API_KEY=your_openai_api_key_here GOOGLE_AI_API_KEY=your_google_ai_api_key_here

   Option B: Use local .env file

   • Create a .env file in the mcp-ai-bridge directory:
     cp .env.example .env
   • Add your API keys to this local .env file

   Option C: Use environment variables in Claude Code config

   • Configure directly in the Claude Code settings (see Configuration section)

The server will check for environment variables in this order:

1. ~/.env (your home directory)
2. ./.env (local to mcp-ai-bridge directory)
3. System environment variables
4. Optional Configuration Variables:
   # Logging level (error, warn, info, debug) LOG_LEVEL=info # Server identification MCP_SERVER_NAME=AI Bridge MCP_SERVER_VERSION=1.0.0 # Security Configuration SECURITY_LEVEL=moderate # disabled, basic, moderate, strict # Content Filtering (granular controls) BLOCK_EXPLICIT_CONTENT=true # Master content filter toggle BLOCK_VIOLENCE=true # Block violent content BLOCK_ILLEGAL_ACTIVITIES=true # Block illegal activity requests BLOCK_ADULT_CONTENT=true # Block adult/sexual content # Injection Detection (granular controls) DETECT_PROMPT_INJECTION=true # Master injection detection toggle DETECT_SYSTEM_PROMPTS=true # Detect system role injections DETECT_INSTRUCTION_OVERRIDE=true # Detect "ignore instructions" attempts # Input Sanitization (granular controls) SANITIZE_INPUT=true # Master sanitization toggle REMOVE_SCRIPTS=true # Remove script tags and JS LIMIT_REPEATED_CHARS=true # Limit DoS via repeated characters # Performance & Flexibility ENABLE_PATTERN_CACHING=true # Cache compiled patterns for speed MAX_PROMPT_LENGTH_FOR_DEEP_SCAN=1000 # Skip deep scanning for long prompts ALLOW_EDUCATIONAL_CONTENT=false # Whitelist educational content WHITELIST_PATTERNS= # Comma-separated regex patterns to allow

Configuration in Claude Code

Method 1: Using Claude Code CLI (Recommended)

Use the interactive MCP setup wizard:

Or add the server configuration directly:

Method 2: Manual Configuration

Add the following to your Claude Code MCP settings. The configuration file location depends on your environment:

• Claude Code CLI: Uses settings.json in the configuration directory (typically ~/.claude/ or $CLAUDE_CONFIG_DIR)
• Claude Desktop: Uses ~/.claude/claude_desktop_config.json

For Claude Desktop compatibility:

Alternatively, if you have the .env file configured, you can omit the env section:

Method 3: Import from Claude Desktop

If you already have this configured in Claude Desktop, you can import the configuration:

Available Tools

1. ask_openai

Query OpenAI models with full validation and security features.

Parameters:

• prompt (required): The question or prompt to send (max 10,000 characters)
• model (optional): Choose from 'gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-4', 'o1', 'o1-mini', 'o1-pro', 'o3-mini', 'chatgpt-4o-latest', and other available models (default: 'gpt-4o-mini')
• temperature (optional): Control randomness (0-2, default: 0.7)

Security Features:

• Input validation for prompt length and type
• Temperature range validation
• Model validation
• Rate limiting (100 requests per minute by default)

2. ask_gemini

Query Google Gemini models with full validation and security features.

Parameters:

• prompt (required): The question or prompt to send (max 10,000 characters)
• model (optional): Choose from 'gemini-1.5-pro-latest', 'gemini-1.5-pro-002', 'gemini-1.5-pro', 'gemini-1.5-flash-latest', 'gemini-1.5-flash', 'gemini-1.5-flash-002', 'gemini-1.5-flash-8b', 'gemini-1.0-pro-vision-latest', 'gemini-pro-vision' (default: 'gemini-1.5-flash-latest')
• temperature (optional): Control randomness (0-1, default: 0.7)

Security Features:

• Input validation for prompt length and type
• Temperature range validation
• Model validation
• Rate limiting (100 requests per minute by default)

3. server_info

Get comprehensive server status and configuration information.

Returns:

• Server name and version
• Available models for each service
• Security settings (rate limits, validation status)
• Configuration status for each API

Usage Examples

In Claude Code, you can use these tools like:

Debugging MCP Server

If you encounter issues with the MCP server, you can use Claude Code's debugging features:

Testing

The project includes comprehensive unit tests and security tests. To run tests:

Test Coverage

• Unit tests for all server functionality
• Security tests for input validation and rate limiting
• Integration tests for API interactions
• Error handling tests
• Mock-based testing to avoid real API calls

Troubleshooting

Common Issues

1. "API key not configured" error: Make sure you've added the correct API keys to your .env file or Claude Code config
2. "Invalid OpenAI API key format" error: OpenAI keys must start with 'sk-'
3. "Rate limit exceeded" error: Wait for the rate limit window to reset (default: 1 minute)
4. "Prompt too long" error: Keep prompts under 10,000 characters
5. Module not found errors: Run npm install in the mcp-ai-bridge directory
6. Permission errors: Ensure the index.js file has execute permissions
7. Logging issues: Set LOG_LEVEL environment variable (error, warn, info, debug)

Claude Code Specific Troubleshooting

8. MCP server not loading:
   • Use claude --mcp-debug to see detailed error messages
   • Check server configuration with /mcp slash command
   • Verify the server path is correct and accessible
   • Ensure Node.js is installed and in your PATH
9. Configuration issues:
   • Use claude mcp add for interactive setup
   • Check CLAUDE_CONFIG_DIR environment variable if using custom config location
   • For timeouts, configure MCP_TIMEOUT and MCP_TOOL_TIMEOUT environment variables
10. Server startup failures:
    • Check if the server process can start independently: node /path/to/mcp-ai-bridge/src/index.js
    • Verify all dependencies are installed
    • Check file permissions on the server directory

Security Features

Enhanced Security Protection

• Multi-Layer Input Validation: Type, length, and content validation
• Content Filtering: Blocks explicit, violent, illegal, and harmful content
• Prompt Injection Detection: Identifies and prevents manipulation attempts including:
  • Instruction override attempts ("ignore previous instructions")
  • System role injection ("system: act as...")
  • Template injection ({{system}}, <|system|>, [INST])
  • Suspicious pattern detection
• Input Sanitization: Removes control characters, scripts, and malicious patterns
• Rate Limiting: 100 requests per minute by default to prevent API abuse
• API Key Validation: Format validation for API keys before use
• Secure Error Handling: No stack traces or sensitive information in error messages
• Structured Logging: All operations are logged with appropriate levels

Security Levels

• Basic: Minimal filtering, allows most content
• Moderate (Default): Balanced protection with reasonable restrictions
• Strict: Maximum protection, blocks borderline content

Granular Security Configuration

Security Levels:

• disabled - No security checks (maximum performance)
• basic - Essential protection only (good performance)
• moderate - Balanced protection (default, good balance)
• strict - Maximum protection (may impact performance)

Individual Feature Controls:

Performance Considerations:

• Pattern caching reduces regex compilation overhead
• Long prompts (>1000 chars) get lighter scanning in basic mode
• Early termination stops checking after finding issues
• Granular controls let you disable unneeded checks

Best Practices

• Never commit your .env file to version control
• Keep your API keys secure and rotate them regularly
• Consider setting usage limits on your API accounts
• Monitor logs for unusual activity
• Use the rate limiting feature to control costs
• Validate the server configuration using the server_info tool

Rate Limiting

The server implements sliding window rate limiting:

• Default: 100 requests per minute
• Configurable via environment variables
• Per-session tracking
• Graceful error messages with reset time information