Labsco
i2y logo

MCPizer

★ 1

from i2y

Enables AI assistants to call any REST API or gRPC service by automatically converting their schemas into MCP tools.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#devops#git#maps

MCPizer

MCPizer lets your AI assistant (Claude, VS Code, etc.) call any REST API or gRPC service by automatically converting their schemas into MCP (Model Context Protocol) tools.

Key Features:

  • 🚀 GitHub integration - fetch schemas directly with github:// URLs
  • 📄 .proto file support - use gRPC without reflection enabled
  • 🔐 Private repo support - automatic authentication via gh CLI
  • 🌐 Connect-RPC support - HTTP/JSON and gRPC modes
  • 🔧 Auto-discovery - finds OpenAPI/Swagger endpoints automatically

What is MCPizer?

MCPizer is a server that:

  • Auto-discovers API schemas from your services (OpenAPI/Swagger, gRPC reflection, .proto files)
  • Converts them into tools your AI can use
  • Handles all the API calls with proper types and error handling

Works with any framework that exposes OpenAPI schemas (FastAPI, Spring Boot, Express, etc.) or gRPC services (with reflection or .proto files). No code changes needed in your APIs - just point MCPizer at them!

How it Works

sequenceDiagram
    participant AI as AI Assistant<br/>(Claude/VS Code)
    participant MCP as MCPizer
    participant API as Your APIs<br/>(REST/gRPC)
    
    Note over AI,API: Initial Setup
    MCP->>API: Auto-discover schemas
    API-->>MCP: OpenAPI/gRPC reflection
    MCP->>MCP: Convert to MCP tools
    
    Note over AI,API: Runtime Usage
    AI->>MCP: List available tools
    MCP-->>AI: Tools from all APIs
    AI->>MCP: Call tool "create_user"
    MCP->>API: POST /users
    API-->>MCP: {"id": 123, "name": "Alice"}
    MCP-->>AI: Tool result

Architecture Overview

graph TB
    subgraph "AI Assistants"
        Claude[Claude Desktop]
        VSCode[VS Code Extensions]
        Other[Other MCP Clients]
    end
    
    subgraph "MCPizer"
        Transport{Transport Layer}
        Discovery[Schema Discovery]
        Converter[Tool Converter]
        Invoker[API Invoker]
        
        Transport -->|STDIO/SSE| Discovery
        Discovery --> Converter
        Converter --> Invoker
    end
    
    subgraph "Your APIs"
        FastAPI[FastAPI<br/>Auto-discovery]
        Spring[Spring Boot<br/>Auto-discovery]
        gRPC[gRPC Services<br/>Reflection/.proto]
        Custom[Custom APIs<br/>Direct schema URL]
    end
    
    Claude --> Transport
    VSCode --> Transport
    Other --> Transport
    
    Invoker --> FastAPI
    Invoker --> Spring
    Invoker --> gRPC
    Invoker --> Custom
    
    style MCPizer fill:#e1f5e1
    style Transport fill:#fff2cc
    style Discovery fill:#fff2cc
    style Converter fill:#fff2cc
    style Invoker fill:#fff2cc

Common Scenarios

"I want Claude to use my local FastAPI app"

# 1. Your FastAPI runs on port 8000
python -m uvicorn main:app

# 2. Install MCPizer
go install github.com/i2y/mcpizer/cmd/mcpizer@latest

# 3. Configure (~/.mcpizer.yaml)
echo "schema_sources:\n  - http://localhost:8000" > ~/.mcpizer.yaml

# 4. Add to Claude Desktop config and restart
# Now ask Claude: "What endpoints are available?"

"I want to test if MCPizer sees my API"

# Quick check - what tools are available?
mcpizer -transport=stdio << 'EOF'
{"jsonrpc":"2.0","method":"tools/list","id":1}
EOF

# Should list all your API endpoints as tools

"My API needs authentication"

# For APIs that require authentication headers
schema_sources:
  # Object format with headers (for fetching schemas)
  - url: https://api.example.com/openapi.json
    headers:
      Authorization: "Bearer YOUR_API_TOKEN"
      X-API-Key: "YOUR_API_KEY"
  
  # GitHub private repos (automatic auth via gh CLI)
  - github://myorg/private-apis/openapi.yaml     # No headers needed!
  - url: github://myorg/private-protos/api.proto  # gh handles auth
    server: grpc://api.example.com:50051
  
  # Simple format (no auth required)
  - https://public-api.example.com/swagger.json

Note: These headers are used when fetching the schema files. Headers required for actual API calls should be defined in the OpenAPI spec itself.

"I'm getting 'no tools available'"

# 1. Check if your API is running
curl http://localhost:8000/openapi.json  # Should return JSON

# 2. Run with debug logging
MCPIZER_LOG_LEVEL=debug mcpizer -transport=stdio

# 3. Check the log file
tail -f /tmp/mcpizer.log

"I want to use my company's gRPC services"

Option 1: If reflection is enabled

# Simple - just point to the service
schema_sources:
  - grpc://my-service:50051

Option 2: Using .proto files (recommended)

# More secure - no reflection needed in production
schema_sources:
  # From GitHub (private repos supported)
  - url: github://mycompany/protos/user-service.proto@v1.0.0
    server: grpc://user-service.prod:443
  
  # From any HTTPS URL
  - url: https://cdn.mycompany.com/schemas/order-service.proto
    server: grpc://order-service.prod:443

"I want to run MCPizer as a service"

Option 1: Direct binary execution

# Run in background with specific config
mcpizer -config /etc/mcpizer/production.yaml &

# Or use systemd (create /etc/systemd/system/mcpizer.service)
[Unit]
Description=MCPizer MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mcpizer
Environment="MCPIZER_CONFIG_FILE=/etc/mcpizer/production.yaml"
Restart=always
User=mcpizer

[Install]
WantedBy=multi-user.target

Examples

Complete Flow Example

Here's how MCPizer works with a FastAPI service:

flowchart LR
    subgraph "Your FastAPI App"
        API[FastAPI Service<br/>Port 8000]
        Schema["/openapi.json<br/>Auto-generated"]
        API --> Schema
    end
    
    subgraph "MCPizer Config"
        Config["~/.mcpizer.yaml<br/>schema_sources:<br/>http://my-fastapi:8000"]
    end
    
    subgraph "MCPizer Process"
        Discover["(1) Discover schema<br/>at /openapi.json"]
        Convert["(2) Convert endpoints<br/>to MCP tools"]
        Register["(3) Register tools<br/>with MCP protocol"]
        
        Discover --> Convert
        Convert --> Register
    end
    
    subgraph "AI Assistant"
        List["List tools:<br/>• get_item<br/>• create_item<br/>• update_item"]
        Call["Call: get_item<br/>{item_id: 123}"]
        Result["Result:<br/>{id: 123, name: 'Test'}"]
        
        List --> Call
        Call --> Result
    end
    
    Config --> Discover
    Schema --> Discover
    Register --> List
    Call -->|HTTP GET /items/123| API
    API -->|JSON Response| Result
    
    style API fill:#e8f4fd
    style Config fill:#fff4e6
    style Register fill:#e8f5e9
    style Result fill:#f3e5f5

FastAPI Example

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

# MCPizer auto-discovers at http://localhost:8000/openapi.json

gRPC Example

Option 1: Using Reflection

// Enable reflection for MCPizer
import "google.golang.org/grpc/reflection"

func main() {
    s := grpc.NewServer()
    pb.RegisterYourServiceServer(s, &server{})
    reflection.Register(s)  // This line enables MCPizer support
    s.Serve(lis)
}

Option 2: Using .proto Files (Recommended for Production)

# config.yaml
schema_sources:
  # Your .proto file in version control
  - url: github://myorg/protos/user-service.proto@v1.0.0
    server: grpc://user-service.prod.example.com:443
  
  # Multiple environments, same schema
  - url: github://myorg/protos/user-service.proto@v1.0.0
    server: grpc://user-service.staging.example.com:443

Benefits:

  • ✅ No reflection needed in production
  • ✅ Version-controlled schemas
  • ✅ CI/CD can validate schemas
  • ✅ Same .proto for multiple environments

Development

# Run tests
go test ./...

# Run integration tests (requires internet connection)
go test -tags=integration ./...

# Build locally
go build -o mcpizer ./cmd/mcpizer

# Run with example services (includes Petstore, gRPC test service, Jaeger)
docker compose up

# Run individual examples
cd examples/fastapi && pip install -r requirements.txt && python main.py

See examples/ for more complete examples: