Mcpizer

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(Claude/VS Code)
    participant MCP as MCPizer
    participant API as Your APIs(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[FastAPIAuto-discovery]
        Spring[Spring BootAuto-discovery]
        gRPC[gRPC ServicesReflection/.proto]
        Custom[Custom APIsDirect 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

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

> Note: Make sure $GOPATH/bin is in your PATH. If not installed, install Go first.

Quick Start

Step 1: Configure Your APIs

Create a config file with your API endpoints:

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

MCPizer supports two transport modes:

📝 STDIO Mode (for clients that manage process lifecycle)

Used by clients that start MCPizer as a subprocess and communicate via standard input/output.

Example: Claude Desktop

Add to your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

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

The client will start MCPizer automatically when needed.

🌐 SSE Mode (Server-Sent Events over HTTP)

Used by clients that connect to a running MCPizer server via HTTP.

# Start MCPizer server (if your client doesn't start it automatically)
mcpizer

# Server runs at http://localhost:8080/sse

Configure your MCP client to connect to http://localhost:8080/sse

Note: Some clients may start the server automatically, while others require manual startup.

🧪 For Testing/Development

# Quick test - list available tools
mcpizer -transport=stdio http://your-api:8000"] 
    
    Try1["/openapi.jsonFastAPI default"]
    Try2["/docs/openapi.jsonFastAPI alt"]
    Try3["/swagger.jsonSwagger 2.0"]
    Try4["/v3/api-docsSpring Boot"]
    Try5["...more paths..."]
    
    Found["✓ Schema found!Parse and convert"]
    NotFound["✗ Not foundTry direct URL"]
    
    Start --> Try1
    Try1 -->|404| Try2
    Try2 -->|404| Try3
    Try3 -->|404| Try4
    Try4 -->|404| Try5
    
    Try1 -->|200| Found
    Try2 -->|200| Found
    Try3 -->|200| Found
    Try4 -->|200| Found
    
    Try5 -->|All fail| NotFound
    
    style Start fill:#e3f2fd
    style Found fill:#c8e6c9
    style NotFound fill:#ffcdd2

Supported frameworks:

• FastAPI: /openapi.json, /docs/openapi.json
• Spring Boot: /v3/api-docs, /swagger-ui/swagger.json
• Express/NestJS: /api-docs, /swagger.json
• Rails: /api/v1/swagger.json, /apidocs
• [See full list](internal/adapter/outbound/openapi/autodiscover.go)

gRPC Services

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

Option 1: gRPC Reflection (requires reflection enabled):

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

Option 2: .proto Files (NEW! - more secure, no reflection needed):

• Host your .proto files anywhere (GitHub, S3, CDN, etc.)
• GitHub URLs (github://) automatically use gh CLI authentication
• Specify the server endpoint separately
• Perfect for production where reflection is disabled
• Allows schema versioning and CI/CD validation

For alternative reflection implementations, see:

• connectrpc/grpcreflect-go Connect-Go's reflection implementation

Local Files

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

GitHub Integration (NEW!)

MCPizer can fetch schemas directly from GitHub repositories using the gh CLI tool - including both OpenAPI and .proto files:

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

Benefits:

• ✅ Works with private repositories (uses gh authentication)
• ✅ Specify branches/tags with @ref syntax
• ✅ No need to manage raw GitHub URLs or tokens
• ✅ Supports both OpenAPI and .proto files
• ✅ Config files can also be stored in GitHub

Requirements:

• Install GitHub CLI: brew install gh (macOS) or see docs
• Authenticate: gh auth login

Environment Variables

| Variable | Default | When to use | |----------|---------|-------------| | MCPIZER_CONFIG_FILE | ~/.mcpizer.yaml | Different config per environmentCan be github:// URL! | | MCPIZER_LOG_LEVEL | info | Set to debug for troubleshooting | | MCPIZER_LOG_FILE | /tmp/mcpizer.log | Change log location (STDIO mode) | | MCPIZER_LISTEN_ADDR | :8080 | Change port (SSE mode) | | MCPIZER_HTTP_CLIENT_TIMEOUT | 30s | Slow APIs need more time |

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 • Try direct schema URL• Check debug logs |
| "Connection refused" | • Wrong port?• Check if API is running• Firewall blocking? |
| "String should have at most 64 characters" | Update MCPizer - this is fixed in latest version |
| gRPC "connection refused" | • Enable reflection in your gRPC server• Check with `grpcurl`• Or use .proto file approach instead |
| "Schema not found at base URL" | • Specify exact schema path• Check if API exposes OpenAPI |
| ".proto file missing server" | • Add `server: grpc://host:port` to your config• Required for .proto files |

## Examples

### Complete Flow Example

Here's how MCPizer works with a FastAPI service:

```mermaid
flowchart LR
    subgraph "Your FastAPI App"
        API[FastAPI ServicePort 8000]
        Schema["/openapi.jsonAuto-generated"]
        API --> Schema
    end
    
    subgraph "MCPizer Config"
        Config["~/.mcpizer.yamlschema_sources:http://my-fastapi:8000"]
    end
    
    subgraph "MCPizer Process"
        Discover["(1) Discover schemaat /openapi.json"]
        Convert["(2) Convert endpointsto MCP tools"]
        Register["(3) Register toolswith MCP protocol"]
        
        Discover --> Convert
        Convert --> Register
    end
    
    subgraph "AI Assistant"
        List["List tools:• get_item• create_item• update_item"]
        Call["Call: get_item{item_id: 123}"]
        Result["Result:{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/](examples/) for more complete examples:

• [proto-config.yaml](examples/proto-config.yaml) - Using .proto files with multiple environments
• [fastapi/](examples/fastapi/) - FastAPI integration example
• [grpc-service/](examples/grpc-service/) - gRPC service with reflection

Contributing

Contributions welcome! Please:

1. Check existing issues first
2. Fork and create a feature branch
3. Add tests for new functionality
4. Submit a PR

License

MIT - see [LICENSE](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: i2y
• Source: i2y/mcpizer
• License: MIT

Install and usage instructions live in the source repository linked above.