Gin-MCP: Zero-Config Gin to MCP Bridge

Enable MCP features for any Gin API with a line of code. Gin-MCP is an opinionated, zero-configuration library that automatically exposes your existing Gin endpoints as Model Context Protocol (MCP) tools, making them instantly usable by MCP-compatible clients like Cursor, Claude Desktop, Continue, Zed, and other MCP-enabled tools. Our philosophy is simple: minimal setup, maximum productivity. Just plug Gin-MCP into your Gin application, and it handles the rest.

Why Gin-MCP?

• Effortless Integration: Connect your Gin API to MCP clients without writing tedious boilerplate code.
• Zero Configuration (by default): Get started instantly. Gin-MCP automatically discovers routes and infers schemas.
• Developer Productivity: Spend less time configuring tools and more time building features.
• Flexibility: While zero-config is the default, customize schemas and endpoint exposure when needed.
• Existing API: Works with your existing Gin API - no need to change any code.

Demo

Features

• Automatic Discovery: Intelligently finds all registered Gin routes.
• Schema Inference: Automatically generates MCP tool schemas from route parameters and request/response types (where possible).
• Direct Gin Integration: Mounts the MCP server directly onto your existing gin.Engine.
• Parameter Preservation: Accurately reflects your Gin route parameters (path, query) in the generated MCP tools.
• Dynamic BaseURL Resolution: Support for proxy environments (Quicknode, RAGFlow) with per-user/deployment endpoints.
• Customizable Schemas: Manually register schemas for specific routes using RegisterSchema for fine-grained control.
• Selective Exposure: Filter which endpoints are exposed using operation IDs or tags.
• Flexible Deployment: Mount the MCP server within the same Gin app or deploy it separately.
• Modern MCP Transport: Streamable HTTP (default) with protocol version negotiation (2026-07-28 through 2025-03-26), up-front server/discover, and a legacy HTTP+SSE opt-out.
• Authorization Header Forwarding: Automatically forward the client's Authorization header to every internal tool-execution call, enabling MCP access to JWT-protected APIs.

Installation

go get github.com/ckanthony/gin-mcp

Basic Usage: Instant MCP Server

Get your MCP server running in minutes with minimal code:

package main

import (
	"net/http"

	server "github.com/ckanthony/gin-mcp/"
	"github.com/gin-gonic/gin"
)

func main() {
	// 1. Create your Gin engine
	r := gin.Default()

	// 2. Define your API routes (Gin-MCP will discover these)
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "pong"})
	})

	r.GET("/users/:id", func(c *gin.Context) {
		// Example handler...
		userID := c.Param("id")
		c.JSON(http.StatusOK, gin.H{"user_id": userID, "status": "fetched"})
	})

	// 3. Create and configure the MCP server
	//    Provide essential details for the MCP client.
	mcp := server.New(r, &server.Config{
		Name:        "My Simple API",
		Description: "An example API automatically exposed via MCP.",
		// BaseURL is crucial! It tells MCP clients where to send requests.
		BaseURL: "http://localhost:8080",
	})

	// 4. Mount the MCP server endpoint
	mcp.Mount("/mcp") // MCP clients will connect here

	// 5. Run your Gin server
	r.Run(":8080") // Gin server runs as usual
}

That's it! Your MCP tools are now available at http://localhost:8080/mcp. Gin-MCP automatically created tools for /ping and /users/:id.

Note on BaseURL: Always provide an explicit BaseURL. This tells the MCP server the correct address to forward API requests to when a tool is executed by the client. Without it, automatic detection might fail, especially in environments with proxies or different internal/external URLs.

Advanced Usage

While Gin-MCP strives for zero configuration, you can customize its behavior.

Annotating Handlers with Comments

Gin-MCP automatically extracts metadata from handler function comments to generate rich tool descriptions. Use these annotations to make your MCP tools more discoverable and easier to use:

// listProducts retrieves a paginated list of products
// @summary List all products
// @description Returns a paginated list of products with optional filtering by price, tags, and availability
// @param page Page number for pagination (default: 1)
// @param limit Number of items per page (default: 10, max: 100)
// @param minPrice Minimum price filter
// @param tag Filter products by tag
// @tags public catalog
func listProducts(c *gin.Context) {
    // Handler implementation...
}

Supported Annotations:

• @summary - Brief one-line description that becomes the tool's primary description
• @description - Additional detailed explanation appended to the summary
• @param <name> <text> - Attaches descriptive text to specific input parameters in the generated schema
• @tags - Space or comma-separated tags used for filtering tools (see "Filtering Exposed Endpoints" below)
• @operationId <id> - Custom operation ID for the tool (overrides the default METHOD_path naming scheme). Must be unique across all routes; duplicates will be skipped (first declaration wins) with a warning logged.

All annotations are optional, but using them makes your API tools much more user-friendly in MCP clients like Claude Desktop and Cursor.

Custom Operation IDs:

By default, Gin-MCP generates operation IDs using the format METHOD_path (e.g., GET_users_id). For routes with very long paths, you can use @operationId to specify a shorter, more manageable name:

// getUserProfile retrieves a user's profile with extended metadata
// @summary Get user profile
// @operationId getUserProfile
// @param id User identifier
func getUserProfile(c *gin.Context) {
    // Instead of the default "GET_api_v2_users_userId_profile_extended"
    // this tool will be named "getUserProfile"
}

Important: Operation IDs must be unique. If two handlers use the same @operationId, the duplicate will be skipped entirely (first declaration wins), and a warning will always be logged. This ensures consistency between the tool list and operations map.

Fine-Grained Schema Control with RegisterSchema

Sometimes, automatic schema inference isn't enough. RegisterSchema allows you to explicitly define schemas for query parameters or request bodies for specific routes. This is useful when:

• You use complex structs for query parameters (ShouldBindQuery).
• You want to define distinct schemas for request bodies (e.g., for POST/PUT).
• Automatic inference doesn't capture specific constraints (enums, descriptions, etc.) that you want exposed in the MCP tool definition.

package main

import (
	// ... other imports
	"github.com/ckanthony/gin-mcp/pkg/server"
	"github.com/gin-gonic/gin"
)

// Example struct for query parameters
type ListProductsParams struct {
	Page  int    `form:"page,default=1" json:"page,omitempty" jsonschema:"description=Page number,minimum=1"`
	Limit int    `form:"limit,default=10" json:"limit,omitempty" jsonschema:"description=Items per page,maximum=100"`
	Tag   string `form:"tag" json:"tag,omitempty" jsonschema:"description=Filter by tag"`
}

// Example struct for POST request body
type CreateProductRequest struct {
	Name  string  `json:"name" jsonschema:"required,description=Product name"`
	Price float64 `json:"price" jsonschema:"required,minimum=0,description=Product price"`
}

func main() {
	r := gin.Default()

	// --- Define Routes ---
	r.GET("/products", func(c *gin.Context) { /* ... handler ... */ })
	r.POST("/products", func(c *gin.Context) { /* ... handler ... */ })
	r.PUT("/products/:id", func(c *gin.Context) { /* ... handler ... */ })


	// --- Configure MCP Server ---
	mcp := server.New(r, &server.Config{
		Name:        "Product API",
		Description: "API for managing products.",
		BaseURL:     "http://localhost:8080",
	})

	// --- Register Schemas ---
	// Register ListProductsParams as the query schema for GET /products
	mcp.RegisterSchema("GET", "/products", ListProductsParams{}, nil)

	// Register CreateProductRequest as the request body schema for POST /products
	mcp.RegisterSchema("POST", "/products", nil, CreateProductRequest{})

	// You can register schemas for other methods/routes as needed
	// e.g., mcp.RegisterSchema("PUT", "/products/:id", nil, UpdateProductRequest{})

	mcp.Mount("/mcp")
	r.Run(":8080")
}

Explanation: