MCPilot - MCP Gateway

A powerful, FastAPI-based gateway for the Model Context Protocol (MCP), designed to unify and scale your AI toolchain.

✅ Current Status

MCPilot is now fully functional with the following working features:

✅ Working Features

FastAPI Gateway Server - Running on http://localhost:8000/docs
Admin Dashboard - Beautiful web UI at http://localhost:8000
REST API Endpoints - Full CRUD operations via /api/v1/*
API Wrapper System - Convert REST APIs to MCP tools (tested with JSONPlaceholder)
Configuration Management - Environment-based settings
Transport Framework - Ready for HTTP, WebSocket, SSE, stdio
Modular Architecture - Clean separation of concerns
Interactive Documentation - OpenAPI/Swagger UI at /docs

🔄 In Progress

MCP Server Federation - Basic framework ready, needs MCP client integration fixes
WebSocket Real-time Communication - Framework ready
Admin UI Management - Backend ready, frontend interactions needed

🧪 Tested Examples

The API wrapper successfully converts REST APIs to MCP tools:

# Example: JSONPlaceholder API → MCP Tool
result = await gateway.call_tool(
    "api:jsonplaceholder:get_user",
    {"user_id": "1"}
)
# Returns: Full user data from REST API

Federation of multiple MCP servers into one unified endpoint
REST API and function wrapping as virtual MCP-compliant tools
Multiple transport support: HTTP/JSON-RPC, WebSocket, SSE, and stdio
Centralized tools, prompts, and resources with full JSON-Schema validation
Admin UI with built-in auth, observability, and transport layers

📁 Project Structure

src/mcpilot/
├── main.py           # FastAPI application entry point
├── config.py         # Configuration management
├── gateway.py        # Core MCP federation logic
├── api.py           # REST API endpoints
├── admin.py         # Admin management endpoints
├── transports.py    # Transport layer implementations
├── api_wrapper.py   # REST API to MCP tool wrapper
├── middleware.py    # Request/response middleware
└── server.py        # Original MCP server implementation

🛠️ Installation

Prerequisites

Python 3.10 or higher
uv package manager (recommended) or pip

Install Dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

🚀 Quick Start

1. Start the Gateway Server

# Run the FastAPI server
uv run python -m mcpilot.main

# Or using uvicorn directly
uvicorn mcpilot.main:app --reload --host 0.0.0.0 --port 8000

2. Access the Admin UI

Open your browser to http://localhost:8000 to access the admin dashboard.

3. API Documentation

OpenAPI/Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

🔧 Configuration

MCPilot can be configured via environment variables or a .env file:

# Server Configuration
MCPILOT_HOST=0.0.0.0
MCPILOT_PORT=8000
MCPILOT_DEBUG=false

# CORS Settings
MCPILOT_CORS_ORIGINS=["*"]

# Logging
MCPILOT_LOG_LEVEL=INFO

Adding MCP Servers

Configure MCP servers via the admin API or by setting up the configuration:

from mcpilot.config import MCPServerConfig

server_config = MCPServerConfig(
    name="my-server",
    type="stdio",
    command="python",
    args=["-m", "my_mcp_server"],
    enabled=True
)

Adding API Wrappers

Convert REST APIs to MCP tools:

from mcpilot.config import APIWrapperConfig

api_config = APIWrapperConfig(
    name="my-api",
    base_url="https://api.example.com",
    auth_type="bearer",
    auth_config={"token": "your-token"},
    endpoints=[
        {
            "name": "get_user",
            "method": "GET",
            "path": "/users/{user_id}",
            "description": "Get user information",
            "path_params": [
                {"name": "user_id", "type": "string", "required": True}
            ]
        }
    ]
)

📖 API Endpoints

Core MCP Operations

GET /api/v1/tools - List all available tools
POST /api/v1/tools/call - Call a tool
GET /api/v1/prompts - List all available prompts
POST /api/v1/prompts/get - Get a prompt
GET /api/v1/resources - List all available resources
POST /api/v1/resources/read - Read a resource

Admin Operations

GET /admin/servers - List MCP servers
POST /admin/servers - Add new MCP server
PUT /admin/servers/{name} - Update MCP server
DELETE /admin/servers/{name} - Remove MCP server
GET /admin/api-wrappers - List API wrappers
POST /admin/api-wrappers - Add new API wrapper

Health & Monitoring

GET /health - Health check endpoint
GET /api/v1/status - Gateway and server status
GET /admin/metrics - System metrics

🔌 WebSocket Support

Connect to the WebSocket endpoint for real-time MCP communication:

const ws = new WebSocket('ws://localhost:8000/api/v1/ws');

// Send MCP JSON-RPC message
ws.send(JSON.stringify({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
}));

🧪 Development

Running in Development Mode

# Install development dependencies
uv sync --dev

# Run with auto-reload
uvicorn mcpilot.main:app --reload --host 0.0.0.0 --port 8000

Testing

# Run tests (when implemented)
uv run pytest

# Type checking
uv run mypy src/mcpilot

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Original MCP Server Components

MCPilot also includes the original MCP server functionality for development and testing:

Resources

The server implements a simple note storage system with:

Custom note:// URI scheme for accessing individual notes
Each note resource has a name, description and text/plain mimetype

Prompts

The server provides a single prompt:

summarize-notes: Creates summaries of all stored notes
- Optional "style" argument to control detail level (brief/detailed)
- Generates prompt combining all current notes with style preference

Tools

The server implements one tool:

add-note: Adds a new note to the server
- Takes "name" and "content" as required string arguments
- Updates server state and notifies clients of resource changes

Configuration

[TODO: Add configuration details specific to your implementation]

Quickstart

Install

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

``` "mcpServers": { "MCPilot": { "command": "uv", "args": [ "--directory", "C:\Users\ary7s\OneDrive\Desktop\MCPilot", "run", "MCPilot" ] } } ```

Published Servers Configuration

``` "mcpServers": { "MCPilot": { "command": "uvx", "args": [ "MCPilot" ] } } ```

Development

Building and Publishing

To prepare the package for distribution:

Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory C:\Users\ary7s\OneDrive\Desktop\MCPilot run mcpilot

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.