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

---

1. Federation of multiple MCP servers into one unified endpoint
2. REST API and function wrapping as virtual MCP-compliant tools
3. Multiple transport support: HTTP/JSON-RPC, WebSocket, SSE, and stdio
4. Centralized tools, prompts, and resources with full JSON-Schema validation
5. 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

<details> <summary>Development/Unpublished Servers Configuration</summary>

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

</details>

<details> <summary>Published Servers Configuration</summary>

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

</details>

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

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

3. 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.