MCPizer

What is MCPizer?

How it Works

Architecture Overview

Installation

# Install MCPizer
go install github.com/i2y/mcpizer/cmd/mcpizer@latest
# Verify installation
mcpizer --help

Usage Examples

# Use default config file (configs/mcpizer.yaml)
mcpizer
# Specify config file via command line (highest priority)
mcpizer -config=/path/to/config.yaml
# Use GitHub-hosted config
mcpizer -config=github://myorg/configs/mcpizer-prod.yaml
# Or via environment variable
export MCPIZER_CONFIG_FILE=/path/to/config.yaml
mcpizer
# STDIO mode with custom config
mcpizer -transport=stdio -config=./my-config.yaml

Quick Start

Step 1: Configure Your APIs

schema_sources:
 # Production APIs with HTTPS
 - https://api.mycompany.com # Auto-discovers OpenAPI
 - https://api.example.com/openapi.json # Direct schema URL
 
 # GitHub-hosted schemas (NEW: use github:// URLs)
 - github://myorg/api-specs/main/user-api.yaml # Uses gh CLI auth
 - github://OAI/OpenAPI-Specification/examples/v3.0/petstore.yaml@master
 - https://raw.githubusercontent.com/myorg/api-specs/main/user-api.yaml # Direct URL also works
 
 # Internal services (FastAPI, Spring Boot, etc.)
 - http://my-fastapi-app:8000 # Auto-discovers at /openapi.json, /docs
 - http://spring-service:8080 # Auto-discovers at /v3/api-docs
 
 # gRPC services (must have reflection enabled)
 - grpc://my-grpc-service:50051
 
 # gRPC with .proto files (NEW! - no reflection needed)
 - url: https://raw.githubusercontent.com/myorg/protos/main/service.proto
 server: grpc://production.example.com:50051
 
 # Or use github:// for private repos (uses gh CLI)
 - url: github://myorg/protos/service.proto@main
 server: grpc://production.example.com:50051
 
 # Connect-RPC services (NEW!)
 # If the service supports gRPC reflection:
 - grpc://connect.example.com:50051
 
 # Connect-RPC with HTTP/JSON mode:
 - url: github://connectrpc/examples/eliza/eliza.proto
 server: https://demo.connectrpc.com
 type: connect
 mode: http # Use HTTP/JSON for easier debugging
 
 # Local development
 - http://localhost:3000
 - grpc://localhost:50052
 
 # Public test APIs
 - https://petstore3.swagger.io/api/v3/openapi.json
 - grpc://grpcb.in:9000

Step 2: Choose Your Transport Mode

📝 STDIO Mode (for clients that manage process lifecycle)

{
 "mcpServers": {
 "mcpizer": {
 "command": "mcpizer",
 "args": ["-transport=stdio", "-config=/path/to/your/config.yaml"]
 }
 }
}

🌐 SSE Mode (Server-Sent Events over HTTP)

# Start MCPizer server (if your client doesn't start it automatically)
mcpizer
# Server runs at http://localhost:8080/sse

🧪 For Testing/Development

# Quick test - list available tools
mcpizer -transport=stdio << 'EOF'
{"jsonrpc":"2.0","method":"tools/list","id":1}
EOF
# Interactive mode
mcpizer -transport=stdio

Usage Guide

When to Use What

Configuration

Supported API Types

schema_sources:
 # Auto-discovery from base URL
 - https://api.production.com # Tries /openapi.json, /swagger.json, etc.
 - http://internal-api:8000 # For internal services
 
 # Direct schema URLs
 - https://api.example.com/v3/openapi.yaml
 - https://raw.githubusercontent.com/company/api-specs/main/openapi.json

schema_sources:
 # Connect-RPC with gRPC reflection (if supported)
 - grpc://connect.example.com:50051
 
 # Connect-RPC with HTTP/JSON mode
 - url: github://connectrpc/examples/eliza/eliza.proto
 server: https://demo.connectrpc.com
 type: connect
 mode: http # HTTP/JSON mode (default)
 
 # Connect-RPC with gRPC mode
 - url: https://raw.githubusercontent.com/myorg/protos/service.proto
 server: grpc://connect.example.com:50051
 type: connect
 mode: grpc # Use gRPC transport

Separate Schema Files and API Servers

schema_sources:
 # Schema file points to production API
 - https://docs.company.com/api/v1/openapi.yaml
 
 # Local schema file for external API
 - ./schemas/third-party-api.yaml

servers:
 - url: https://api.production.com
 description: Production server
 - url: https://api.staging.com
 description: Staging server

openapi: 3.0.0
info:
 title: Internal API
 version: 1.0.0
servers:
 - url: https://internal-api.company.com
paths:
 /users:
 get:
 summary: List users
 responses:
 '200':
 description: Success
 content:
 application/json:
 schema:
 type: array
 items:
 type: object
 properties:
 id: {type: integer}
 name: {type: string}

Auto-Discovery Process

schema_sources:
 # Using gRPC reflection (requires reflection enabled on server)
 - grpc://your-grpc-host:50051 # Your service
 - grpc://grpcb.in:9000 # Public test service
 
 # Using .proto files (NEW! - no reflection needed)
 - url: https://raw.githubusercontent.com/grpc/grpc-go/master/examples/helloworld/helloworld/helloworld.proto
 server: grpc://production.example.com:50051
 
 # Private GitHub .proto files (uses gh CLI authentication)
 - url: github://myorg/protos/user-service.proto
 server: grpc://user-service:50051
 
 # With specific branch/tag
 - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@v1.65.0
 server: grpc://production.example.com:50051

// In your gRPC server
import "google.golang.org/grpc/reflection"
reflection.Register(grpcServer)

schema_sources:
 - ./api-spec.json
 - /path/to/openapi.yaml

GitHub Integration (NEW!)

schema_sources:
 # OpenAPI schemas from GitHub
 - github://owner/repo/path/to/openapi.yaml
 - github://microsoft/api-guidelines/graph/openapi.yaml@v1.0
 
 # .proto files from GitHub (NEW!)
 - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@master
 server: grpc://production.example.com:50051
 
 # Private repositories (uses gh CLI authentication)
 - github://myorg/private-apis/user-api.yaml
 - url: github://myorg/private-protos/service.proto@v2.0
 server: grpc://internal-service:50051
 
 # Load MCPizer config itself from GitHub!
 # Set MCPIZER_CONFIG_FILE=github://myorg/configs/mcpizer.yaml

Environment Variables

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

"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"

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

# 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"

# 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

Troubleshooting

Debug Commands

# See what's happening
MCPIZER_LOG_LEVEL=debug mcpizer -transport=stdio
# Watch logs (STDIO mode)
tail -f /tmp/mcpizer.log
# Test your API is accessible
curl http://your-api-host:8000/openapi.json
# Test gRPC reflection
grpcurl -plaintext your-grpc-host:50051 list

Common Issues

Examples

Complete Flow Example

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

// 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)
}

# 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

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

Contributing

License