ckanthony/gin-mcp

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
Basic Usage: Instant MCP Server
Get your MCP server running in minutes with minimal code:
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:
**Supported Annotations:**
- **@summary** - Brief one-line description that becomes the tool's primary description
- **@description** - Additional detailed explanation appended to the summary
- **@param ** - 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 ** - 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:**