SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsgomcp

gomcp

Gin-like Go framework for building MCP servers: struct-tag schemas, middleware, tool groups, Gin/OpenAPI/gRPC adapters, async tasks and an inspector UI.

Open website

About this tool

Purpose

GoMCP is a Go framework for building Model Context Protocol (MCP) servers, not just an SDK. MCP is an open protocol that lets AI applications (Claude Desktop, Cursor, Kiro, VS Code Copilot, etc.) call external tools, read data sources, and use prompt templates. GoMCP's goal is to make building such servers straightforward, and it is described as "the Gin of the MCP world," offering a Gin-like development experience.

Main Capabilities

Tool Development

  • Automatic schema from struct tags: Define parameters with Go structs and mcp tags to automatically generate JSON Schema.
  • Typed handlers: Use func(*Context, Input) (Output, error) handlers, with no need to manually parse parameters.
  • Parameter validation: Supports required, min/max, enum, and pattern, with checks completed before the handler function executes; invalid parameters are rejected in advance.
  • Component versioning: Multiple versions can be registered, and clients call them via name@version.
  • Asynchronous tasks: Long-running tools return a task ID, with support for polling and cancellation.

Adapters

  • Gin adapter: Import existing Gin routes as MCP tools with one line of code.
  • OpenAPI adapter: Generate tools from Swagger/OpenAPI 3.x documents.
  • gRPC adapter: Import gRPC service methods as MCP tools.

Authentication and Authorization

  • BearerAuth: Perform Bearer token checks via a custom validator (the documentation states that this library does not decode JWT; JWT parsing is handled by the user).
  • APIKeyAuth: Validate the API Key via a request header.
  • BasicAuth: HTTP Basic authentication.
  • RequireRole / RequirePermission: Implement RBAC authorization on tool groups.

Framework Features

  • Middleware chain: Logger, Recovery, RequestID, Timeout, RateLimit, OpenTelemetry.
  • Tool grouping: Supports prefix naming, group-level middleware, and nested groups.
  • Resource and Prompt: Full MCP support, including URI templates and parameterized prompts, and can provide autocomplete suggestions for prompt/resource parameters.

Production-Related

  • Multiple transports: stdio (Claude Desktop, Cursor, Kiro) and Streamable HTTP (including SSE).
  • MCP Inspector: Built-in web debugging interface for browsing and testing tools.
  • Hot reload: Load tool definitions from YAML files and watch for file changes.
  • mcptest package: An in-memory client for unit testing, with snapshot testing support.
  • Lifecycle: Close(), idle session reclamation, and asynchronous concurrency control.

Usage

Environment Requirements

  • go.mod declares go 1.25.0. If the local version is Go 1.21+ and usesthe default GOTOOLCHAIN=auto, Go will automatically download and use a matching toolchain; if it is fixed to GOTOOLCHAIN=local, then Go 1.25+ must be installed or the pin must be removed.

Basic Usage

  • Define an input struct and use mcp tags, for example the combined form mcp:"required,desc=User email,pattern=^[^@]+@[^@]+$".
  • Supported types: string, int, float64, bool, []T, nested structs.
  • Simple handlers or the recommended typed handlers can be used.

Authentication error shape

When the BearerAuth / APIKeyAuth / BasicAuth / RequireRole / RequirePermission middleware rejects a call, the framework returns a normal JSON-RPC result where isError = true and the reason is in content[0].text, not a JSON-RPC error object, and not an HTTP 401/403. Clients must check the isError of the tool call result to identify authentication failures.

Adapter examples

  • Gin: import an existing API in one line.
  • OpenAPI: generate from a Swagger document.

Component versions and YAML

  • The version field renames the tool: a non-empty version causes the Provider to register it as name@version (e.g. search@1.0), which is the name shown in the client's tools/call and tools/list. If you want the tool name to be the versionless search, remove the version field entirely.
  • YAML tool files support the corresponding structure definitions.

Server lifecycle, sessions, and async tasks

  • Server.Close(): call once when a process or test teardown uses LoadDir(..., Watch: true) or a long-running HTTP server. It stops the YAML watch loop, the session reclamation background goroutine, and the async task manager reclamation loop, and is idempotent.
  • Sessions: session state is stored only in memory. The identifier comes from the client's Mcp-Session-Id request header. Sessions idle for 30 minutes (no access with that ID) are removed; the next request with the same ID gets a new empty session. Do not rely on session storage during long idle periods unless the client keeps traffic going or refreshes state itself.
  • SetMaxConcurrentTasks(n): must be set before the first AsyncTool / AsyncToolFunc; calling it after the internal task manager is created is a no-op (to avoid races with in-progress work).
  • Shutdown and asyncwork: Close() does not wait for async tool handlers that are still running; if you need a hard guarantee before exit, add your own timeout or wait.

HTTP transport and authentication key points

  • Middleware runs for every JSON-RPC method (except the notification notifications/initialized, which has no response), including initialize, tools/list, tools/call, resources/read, prompts/get, tasks/*, completion/complete, etc. When exposing POST /mcp, use BearerAuth / APIKeyAuth / BasicAuth. For APIKeyAuth, when no header is sent, api_key (and other merged parameters) come from the tools/call parameters, prompts/get parameters, or the params JSON of resources/read; in production, using a request header is recommended.
  • BearerAuthSkipHandshake / APIKeyAuthSkipHandshake / BasicAuthSkipHandshake (or SkipAuthForMCPMethods) allow initialize and ping to run without credentials while protecting other methods, which is suitable for MCP HTTP clients that negotiate first and then send a token.
  • The request context is passed to tool, resource, and prompt handlers (deadline, Authorization, and request headers injected by Streamable HTTP).
  • SSE (GET /mcp) does not execute MCP middleware. Use WithSSEAuth with SSEBearerAuth, SSEAPIKeyAuth, SSEBasicAuth, or a custom gate. If WithSSEAuth is not used, any client that can open a GET will receive broadcast notifications.
  • Browser fetch: wrap the /mcp handler with transport.WrapCORS(h, allowedOrigins) (from github.com/zhangpanda/gomcp/transport); never use * with credentials, and list only trusted origins.
  • When deploying Streamable HTTP in production, you should combine TLS, authentication middleware on POST, and use WithSSEAuth when notifications should not be public.

Working with AI clients

Can be used with Claude Desktop, Cursor, Kiro, Windsurf, VS Code Copilot, and any MCP-compatible client.

Use cases

  • Developers who need to quickly implement an MCP server in Go.
  • Those who want to quickly expose existing Gin routes, OpenAPI documentation, or gRPC services as MCP tools.
  • MCP services that need production-grade capabilities such as authentication, RBAC, rate limiting, timeouts, and observability.
  • Development and testing workflows that need YAML hot reload, a built-in debugging interface, and an in-memory test client.

Limitations and notes

  • Session state is stored in memory only and is reclaimed after 30 minutes of inactivity.
  • Close() does not wait for asynchronous tool handlers that are still running.
  • SetMaxConcurrentTasks must be called before the first asynchronous tool is created.
  • The SSE channel does not pass through MCP middleware and requires separate SSE authentication configuration.
  • BearerAuth is not responsible for JWT decoding; users must implement the validator themselves.
  • Authentication failures are returned as a JSON-RPC result with isError=true, rather than HTTP 401/403 or a JSON-RPC error object.
  • For more details, step-by-step guides, and code examples, see the project repository documentation.

Copyright and license

Copyright © 2026 GoMCP Contributors. Open sourced under the Apache License 2.0; free to use for both personal and commercial purposes, provided that the copyright notice, license text, and attribution notice are retained. Apache 2.0 includes an explicit patent grant from contributors to users; code contributed to this project is likewise licensed under Apache 2.0. Some features in the framework (struct tag schema generation, HTTP-to-MCP auto adapter, OpenAPI-to-MCP auto adapter) have patent applications pending, and Apache 2.0 grants a perpetual, worldwide, royalty-free patent license to use these features as part of this software.

Related tools

Browse category