MCP Ai Bridge

🚀 MCP AI Bridge

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

🚀 Quick Start

The MCP AI Bridge is a secure server that connects Claude Code with OpenAI and Google Gemini APIs. Follow the steps below to get started.

✨ Features

• OpenAI Integration: Access a variety of OpenAI models, including 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 the 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:

cd mcp-ai-bridge
npm install

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
   

📚 Documentation

Configuration in Claude Code

Method 1: Using Claude Code CLI (Recommended)

Use the interactive MCP setup wizard:

claude mcp add

Or add the server configuration directly:

claude mcp add-json ai-bridge '{"command": "node", "args": ["/path/to/mcp-ai-bridge/src/index.js"]}'

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:

{
  "mcpServers": {
    "ai-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-ai-bridge/src/index.js"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "GOOGLE_AI_API_KEY": "your_google_ai_api_key"
      }
    }
  }
}

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

{
  "mcpServers": {
    "ai-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-ai-bridge/src/index.js"]
    }
  }
}

Method 3: Import from Claude Desktop

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

claude mcp add-from-claude-desktop

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:

mcp__ai-bridge__ask_openai
  prompt: "Explain the concept of recursion in programming"
  model: "gpt-4o"
  temperature: 0.5

mcp__ai-bridge__ask_gemini
  prompt: "What are the key differences between Python and JavaScript?"
  model: "gemini-1.5-flash-latest"

mcp__ai-bridge__server_info

Debugging MCP Server

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

# Enable MCP debug mode for detailed error information
claude --mcp-debug

# Check MCP server status and tools
claude
# Then use the /mcp slash command to view server details

🔧 Technical Details

Testing

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

# Run all tests (including security tests)
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

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:

# Master toggles
SECURITY_LEVEL=moderate
BLOCK_EXPLICIT_CONTENT=true
DETECT_PROMPT_INJECTION=true
SANITIZE_INPUT=true

# Granular content filtering
BLOCK_VIOLENCE=true                  # "how to kill", violence
BLOCK_ILLEGAL_ACTIVITIES=true       # "how to hack", illegal acts
BLOCK_ADULT_CONTENT=true            # Sexual/adult content

# Granular injection detection
DETECT_SYSTEM_PROMPTS=true           # "system: act as admin"
DETECT_INSTRUCTION_OVERRIDE=true     # "ignore previous instructions"

# Granular sanitization
REMOVE_SCRIPTS=true                  # Remove <script> tags
LIMIT_REPEATED_CHARS=true           # Prevent character flooding

# Performance optimization
ENABLE_PATTERN_CACHING=true         # Cache patterns for speed
MAX_PROMPT_LENGTH_FOR_DEEP_SCAN=1000 # Skip intensive checks on long prompts

# Flexibility options
ALLOW_EDUCATIONAL_CONTENT=true      # Whitelist "research about", "explain"
WHITELIST_PATTERNS="educational,academic" # Custom regex patterns

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.