CodeMie MCP Connect Service

 ██████╗ ██████╗ ██████╗ ███████╗███╗   ███╗██╗███████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝████╗ ████║██║██╔════╝
██║     ██║   ██║██║  ██║█████╗  ██╔████╔██║██║█████╗
██║     ██║   ██║██║  ██║██╔══╝  ██║╚██╔╝██║██║██╔══╝
╚██████╗╚██████╔╝██████╔╝███████╗██║ ╚═╝ ██║██║███████╗
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝     ╚═╝╚═╝╚══════╝

███╗   ███╗ ██████╗██████╗      ██████╗ ██████╗ ███╗   ██╗███╗   ██╗███████╗ ██████╗████████╗
████╗ ████║██╔════╝██╔══██╗    ██╔════╝██╔═══██╗████╗  ██║████╗  ██║██╔════╝██╔════╝╚══██╔══╝
██╔████╔██║██║     ██████╔╝    ██║     ██║   ██║██╔██╗ ██║██╔██╗ ██║█████╗  ██║        ██║
██║╚██╔╝██║██║     ██╔═══╝     ██║     ██║   ██║██║╚██╗██║██║╚██╗██║██╔══╝  ██║        ██║
██║ ╚═╝ ██║╚██████╗██║         ╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗   ██║
╚═╝     ╚═╝ ╚═════╝╚═╝          ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═══╝╚══════╝ ╚═════╝   ╚═╝

Platform for AI-Native Delivery, Modernization, and Business.

CodeMie is an open platform that lets teams build, orchestrate, and scale AI agents across the entire software lifecycle — from planning and coding to testing, deployment, and operations. It unites intelligent assistants, multi-agent workflows, deep integrations, and project knowledge in one system.

What you can do with CodeMie:

• 🚀 AI-Native SDLC & Delivery — Automate every phase of the software lifecycle: discovery, architecture, development, testing, and deployment with purpose-built AI agents.
• 🔄 AI Migration & Modernization — Migrate and modernize legacy systems and mainframes using AI-powered analysis, code exploration (AICE), and automated transformation workflows.
• 💼 AI for Business & Operations — Deploy AI agents across non-engineering functions such as finance, HR, sales, and support.

This repository — codemie-mcp-connect-service — is the MCP bridge component of the CodeMie platform. It provides HTTP/HTTPS-to-stdio protocol translation, enabling cloud-based CodeMie AI agents to communicate with locally running MCP servers over any transport (stdio, streamable-http, SSE). Deployed as a Docker container.

🌐 Website: codemie.ai 📖 Documentation: docs.codemie.ai 🖥️ CLI tool: codemie-code

A comprehensive containerized solution that bridges cloud-based AI services with local Model Context Protocol (MCP) servers.

Built with Python, FastAPI, and Docker 🐳

Description 🗒

CodeMie MCP Connect Service solves a critical challenge in the MCP ecosystem: enabling cloud-based AI platforms like CodeMie to seamlessly interact with local MCP servers that typically use stdio transport. By providing HTTP/HTTPS to stdio protocol translation with built-in tunneling support, developers can leverage the full power of local MCP tools in cloud environments without compromising security or requiring complex setup procedures.

Technology Stack 🛠

Core Runtime:

• Python 3.12+ with FastAPI 0.121.0+
• Uvicorn ASGI server
• Pydantic 2.12.0+ for validation
• MCP Python SDK v1.21.0+

Additional Runtimes:

• Node.js LTS (JavaScript/TypeScript MCP servers)
• OpenJDK 11, 17, 21 (Java-based MCP servers)
• Go 1.25.1 (Go-based MCP servers)
• Apache Maven 3.9.11

Development Tools:

• Testing: pytest + pytest-asyncio + pytest-cov
• Type Checking: mypy (strict mode)
• Code Quality: black (formatting), ruff (linting)
• Package Management: Poetry 2.1.3, uv (Python), npm (Node.js)

Features:

• Cloud Integration: Enables cloud-based AI services to interact with local stdio-based MCP servers
• Protocol Translation: Converts HTTP/HTTPS requests to MCP (stdio, streamable-http, SSE) communication seamlessly
• Client Caching: Intelligent connection reuse with 5-minute TTL and ping validation
• Single-Usage Mode: Immediate resource cleanup for one-time operations
• Pre-installed MCP Servers: Comprehensive collection of popular MCP servers ready to use
• MCP Inspector: Built-in support for debugging and inspecting MCP servers
• Security: Token-based authentication and controlled access to local resources

Quick Start

Building the Docker Image

docker build --platform linux/amd64 -t codemie-mcp-connect-service .

Running the Container

Basic run:

docker run -d --restart unless-stopped --name codemie-mcp-connect-service \
  -e ACCESS_TOKEN= \
  -e PORT=3000 \
  -e LOG_LEVEL=info \
  -e LOG_FORMAT=json \
  -p 3000:3000 \
  codemie-mcp-connect-service:latest

With MCP Inspector (debugging):

docker run -d --restart unless-stopped --name codemie-mcp-connect-service \
  -e ACCESS_TOKEN= \
  -e PORT=3000 \
  -p 3000:3000 \
  -p 58080:58080 \
  -p 59000:59000 \
  codemie-mcp-connect-service:latest

Development

Local Development Setup

Prerequisites:

• Python 3.12+, pip, Poetry
• Virtual environment (MANDATORY)

Setup:

# ALWAYS activate virtual environment first
source .venv/bin/activate

# Install dependencies
poetry install

# Run development server
poetry run uvicorn mcp_connect.main:app --reload --port 3000

Testing 🧪

source .venv/bin/activate

poetry run pytest                    # Unit tests only
poetry run pytest -m integration     # Integration tests
poetry run pytest --cov=src          # With coverage

Code Quality 📝

Linting & Formatting:

poetry run ruff format               # Format code
poetry run ruff check                # Lint code
poetry run mypy src/                 # Type check
poetry run black src/ tests/         # Black formatting

Security Scanning:

make gitleaks                        # Scan for secrets and credentials

Pre-commit Quality Check (REQUIRED before commit/PR):

source .venv/bin/activate && \
poetry run ruff format && \
poetry run ruff check && \
poetry run mypy src/ && \
poetry run black --check src/ tests/ && \
poetry run pytest tests/ --cov=src --cov-report=term-missing && \
poetry run pytest tests/ -m integration --cov=src --cov-report=term-missing && \
make gitleaks

All checks MUST pass (exit code 0).

Client Caching and Single-Usage Mode

The service provides two operational modes for MCP client management:

Default Caching Mode

By default, the service caches MCP client connections for optimal performance:

• Automatic Reuse: Clients are cached and reused for subsequent requests with the same configuration
• Connection Validation: Cached clients are validated with ping requests before reuse
• TTL Management: Clients are automatically cleaned up after 5 minutes of inactivity (configurable via MCP_CONNECT_CLIENT_CACHE_TTL)
• Performance Benefits: Eliminates connection setup overhead for repeated requests

Single-Usage Mode

For scenarios requiring immediate resource cleanup or one-time operations, use the single_usage parameter:

{
  "serverPath": "npx",
  "method": "tools/list",
  "args": ["-y", "@upstash/context7-mcp"],
  "params": {},
  "single_usage": true,
  "user_context": {"user": {"id": "u-1", "email": "[email protected]"}}
}

user_context is optional and opaque: the service does not inspect or validate it, and forwards it to downstream MCP servers on tools/call requests as _meta["codemie.ai/user-context"]. Servers that do not read _meta ignore it.

When to use Single-Usage Mode:

• One-time operations: Bulk processing, data migrations, testing
• Resource-constrained environments: Immediate memory cleanup required
• Unique configurations: Avoid cache pollution from specialized setups
• Batch processing: When client reuse is not beneficial

Single-Usage Behavior:

1. No Caching: Client is created fresh for each request
2. Immediate Cleanup: Client and transport are closed immediately after request completion
3. Resource Management: Prevents memory buildup for infrequent operations
4. Higher Latency: Trade-off of connection setup time for immediate resource cleanup

Exposing Container to CodeMie Platform

To use your container with the CodeMie platform, it must be reachable from the CodeMie cloud service — deploy it behind your own ingress, load balancer, or tunnel of choice.

1. Start the container and expose it publicly through your chosen ingress/tunnel
2. Configure CodeMie Assistants to use your MCP servers:
   • Navigate to your CodeMie AI Assistant configuration
   • Add a new MCP server connection or modify an existing one
   • Use your container’s public URL as MCP-Connect URL
   • Include your ACCESS_TOKEN in the MCP Server configuration

{
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"],
  "env": {
    "DEFAULT_MINIMUM_TOKENS": "10000"
  },
  "auth_token": ""
}

Optional: For single-usage mode (immediate cleanup after each request):

{
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"],
  "env": {
    "DEFAULT_MINIMUM_TOKENS": "10000"
  },
  "auth_token": "",
  "single_usage": true
}

4. Test the connection by listing available tools or calling a specific MCP server function

Container Security Model

The container implements a multi-layered security approach:

Protected System Scripts

Three critical scripts are installed in /usr/local/bin/ with root-only write permissions:

Security Characteristics:

• Ownership: root:root - only root user can modify or delete
• Permissions: 755 (rwxr-xr-x) - read and execute for all, write for root only
• Immutability: The codemie user (UID 1001) cannot modify or delete these scripts
• Availability: Scripts remain in PATH and executable from anywhere in the container

User Workspace

The codemie user operates with restricted privileges:

• Home Directory: /home/codemie/ - full read/write/execute permissions
• Working Directory: Full control over /home/codemie/ for project files and data
• System Scripts: Read and execute only - cannot modify system-critical scripts
• System Directories: Read and execute access to /usr/local/bin/, /usr/lib/jvm/, Maven, and MCP tools

This design ensures that:

1. System-critical functionality remains intact and tamper-proof
2. Users have a safe workspace (/home/codemie/) for all development activities
3. Accidental or malicious script modifications are prevented
4. Container behavior remains consistent and reliable across all sessions

MCP Inspector

The container includes built-in support for the MCP Inspector, a powerful tool for debugging and testing MCP servers.

Running MCP Inspector

1. Connect to the container via docker exec:

   docker exec -it codemie-mcp-connect-service /bin/bash
   

2. Run the MCP Inspector:

   HOST=0.0.0.0 CLIENT_PORT=58080 SERVER_PORT=59000 npx @modelcontextprotocol/inspector
   

3. Access the Inspector in your browser at http://localhost:58080

The MCP Inspector allows you to:

• Run MCP servers and check/validate their capabilities
• Test server methods and tool calls interactively
• Debug server responses and troubleshoot issues
• Explore server schemas and documentation

Python Virtual Environment Management

The container includes two specialized shell scripts installed system-wide in /usr/local/bin/ for managing Python virtual environments. These scripts are globally accessible from anywhere in the container and are designed to work seamlessly with MCP CLI servers like the CLI MCP Server.

Installation Location: /usr/local/bin/ (available in PATH) Execution Context: Runs as codemie user (UID 1001) No prefix required: Call scripts directly without ./ prefix

create_python_venv.sh

Creates and configures Python virtual environments using the fast uv package manager.

Usage:

create_python_venv.sh  [absolute_path_to_requirements_file]

Examples:

# Create a basic virtual environment
create_python_venv.sh /home/codemie/myproject

# Create virtual environment and install dependencies
create_python_venv.sh /home/codemie/myproject /home/codemie/myproject/requirements.txt

Features:

• Uses uv venv for fast virtual environment creation
• Automatically creates target directories if they don’t exist
• Validates absolute paths for security (prevents directory traversal)
• Optionally installs dependencies from requirements.txt
• Provides detailed status feedback and error handling
• Globally accessible from any directory in the container

run_in_python_venv.sh

Executes Python scripts and commands within existing virtual environments.

Usage:

run_in_python_venv.sh  [python_script_and_arguments...]

Examples:

# Run a Python script
run_in_python_venv.sh /home/codemie/myproject script.py arg1 arg2

# Execute Python code directly
run_in_python_venv.sh /home/codemie/myproject -c "print('Hello World')"

# Run Python modules
run_in_python_venv.sh /home/codemie/myproject -m pip list

# Install packages
run_in_python_venv.sh /home/codemie/myproject -m pip install requests

Features:

• Automatic virtual environment activation and validation
• Support for environment variable expansion in arguments
• Comprehensive error handling and validation
• Security-focused with absolute path requirements
• Compatible with any Python script or module execution
• Globally accessible from any directory in the container

Integration with MCP CLI Servers

These scripts are particularly useful when combined with MCP CLI servers, enabling AI assistants to:

1. Create isolated Python environments for different projects or experiments
2. Install specific package versions without conflicts
3. Execute Python code safely within controlled environments
4. Manage multiple Python projects with different dependency requirements

Example MCP CLI Server Configuration:

{
  "command": "uvx",
  "args": ["cli-mcp-server"],
  "env": {
    "TIMEOUT": "3000",
    "ALLOWED_DIR": "/home/codemie",
    "ALLOWED_FLAGS": "all",
    "COMMAND_TIMEOUT": "3000",
    "ALLOWED_COMMANDS": "all",
    "MAX_COMMAND_LENGTH": "70000",
    "ALLOW_SHELL_OPERATORS": "true"
  },
  "auth_token": ""
}

Complete Workflow Example:

From anywhere inside the container, execute:

# Set project directory (recommended: /home/codemie for write permissions)
PROJECT=/home/codemie/my-python-project

# Step 1: Create virtual environment
create_python_venv.sh ${PROJECT}

# Step 2: Install dependencies (if requirements.txt exists)
create_python_venv.sh ${PROJECT} ${PROJECT}/requirements.txt

# Step 3: Run your application
run_in_python_venv.sh ${PROJECT} app.py --port 8000

# Step 4: Run tests
run_in_python_venv.sh ${PROJECT} -m pytest tests/

# Step 5: Install additional packages as needed
run_in_python_venv.sh ${PROJECT} -m pip install requests pandas numpy

Key Benefits:

• Global Accessibility: Scripts work from any directory in the container
• No Navigation Required: No need to cd to script location
• Secure by Design: Absolute path validation prevents directory traversal attacks
• User Context: Runs as codemie user with appropriate permissions
• Fast Performance: Uses uv package manager for rapid environment creation

This integration allows AI assistants to dynamically create Python environments, install packages, and execute Python applications with full isolation and security controls.

Available Technologies and MCP Servers

Runtime Environments

Development Tools

Media and System Tools

Pre-installed MCP Servers

Core MCP Servers (from modelcontextprotocol/servers)

The container includes all servers from the official MCP servers repository:

• Filesystem - File system operations and management
• Git - Git repository operations and version control
• GitHub - GitHub API integration and repository management
• Google Drive - Google Drive file operations
• Slack - Slack workspace integration
• PostgreSQL - PostgreSQL database operations
• MySQL - MySQL database operations
• SQLite - SQLite database operations
• Fetch - HTTP request and web scraping capabilities
• Puppeteer - Web automation and scraping
• Brave Search - Web search capabilities
• Everything - Windows file search (Everything search engine)
• Memory - Persistent memory and context management

Archived MCP Servers (from modelcontextprotocol/servers-archived)

Additional servers from the archived repository for extended functionality.

Third-party MCP Servers

Environment Configuration 🔧

The container supports the following environment variables:

Volume Mounts

The Docker container supports volume mounting for persistent storage and file system access:

• SQLite databases: Mount for persistent database storage
• Custom configurations: Mount configuration files as needed
• Project files: Mount your project directories for development

Contributing

We welcome contributions! Please read our Contributing Guide for commit conventions, branch workflow, dev setup, and code standards. All participants are expected to follow the Code of Conduct.

License Compliance

Check licenses of production dependencies:

poetry run pip-licenses --packages $(poetry show --only main | awk '{print $1}' | tr '\n' ' ')

This checks licenses only for production packages (excludes dev dependencies like pytest, etc.).

Documentation 📚

• CLAUDE.md - Comprehensive development guide for AI agents and developers
• API Documentation - FastAPI application structure and modules
• MCP Python SDK - Official MCP SDK documentation

Ready to bridge the gap between local MCP capabilities and cloud-based AI platforms.