Skip to content

ghchinoy/mcp-server-go-template

v1.0.0Apache-2.0

Production-grade, dual-transport, zero-trust Model Context Protocol (MCP) server starter template in Go

GitHubOpen Website

🚀 MCP Server Go Template

A production-grade, dual-transport, zero-trust Model Context Protocol (MCP) server starter template in Go, powered by the official github.com/modelcontextprotocol/go-sdk v1.7.0.

Designed for production deployments on serverless platforms (Google Cloud Run, AWS ECS, Fly.io, Kubernetes), this template provides out-of-the-box support for Cursor, Claude Desktop, OpenCode, Gemini Spark, Antigravity Desktop, and the agy CLI.

🌟 The Five Production Pillars

  1. Dual-Transport Ingress (multiplexer.go): A single HTTP endpoint handles both legacy Server-Sent Events (SSE) streams and modern Streamable HTTP requests.
  2. Stateless Serverless Resilience: Configuring Stateless: true in StreamableHTTPOptions ensures requests survive cold starts and instance replacement without 404 session not found errors.
  3. Zero-Trust OAuth 2.1 & SSRF Defense (auth.go): Supports RFC 7591 Dynamic Client Registration (DCR), Client ID Metadata Documents (CIMD), and PKCE S256, protected by an SSRF-safe connection dialer.
  4. Granular Access-Scoped Tools (auth.go): Tools declare specific required scopes (tools:read, admin:access). Generic type-safe decorators (RequireScope) enforce authorization boundaries per tool before execution.
  5. Sub-Millisecond In-Memory Execution: Active tool calls validate stateless signed HMAC-SHA256 JWTs locally in memory without database roundtrips.

🚀 Quickstart

Prerequisites

  • Go 1.25 or higher installed.

1. Clone & Run Locally

git clone https://github.com/ghchinoy/mcp-server-go-template.git
cd mcp-server-go-template

# Run the server
go run .

The server starts on http://localhost:8080:

  • MCP Endpoint: http://localhost:8080/sse
  • OAuth AS Metadata: http://localhost:8080/.well-known/oauth-authorization-server
  • Protected Resource Metadata: http://localhost:8080/.well-known/oauth-protected-resource
  • Health Check: http://localhost:8080/healthz

2. Generate a Local Testing Token

make token UID=developer@example.com

3. Run Test Suite

make test

🛠️ Included Tools, Prompts & Resources

Exposed Tools

  • echo (Title: "Echo Message"): Returns the input payload with character counts and UTC timestamps (dual-emit).
  • dictionary_lookup (Title: "Dictionary Lookup"): Searches vocabulary terms across definitions, parts of speech, and categories.
  • system_info (Title: "System Diagnostics"): Returns runtime OS, architecture, Go version, CPU count, and uptime.
  • admin_purge_cache (Title: "Purge System Cache"): Privileged tool demonstrating generic RequireScope("admin:access", handler) access control.

Exposed Prompts

  • guided-lookup: Guided dictionary analysis workflow for AI assistants.

Exposed Resources

  • template://stats: Real-time memory allocation and uptime metrics in JSON.

🔌 Connecting AI Assistants

1. Cursor (IDE)

  • Settings → Models → MCP → Add New MCP Server
  • Transport: SSE
  • URL: http://localhost:8080/sse
  • Headers: Authorization: Bearer <TOKEN>

2. Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "go-template-local": {
      "type": "remote",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

3. OpenCode

Add to opencode.json:

{
  "mcp": {
    "go-template-local": {
      "type": "remote",
      "url": "http://localhost:8080/sse",
      "enabled": true,
      "oauth": {
        "clientId": "https://example.com/metadata.json",
        "authorizationUrl": "http://localhost:8080/authorize",
        "tokenUrl": "http://localhost:8080/api/oauth/token"
      }
    }
  }
}

4. Gemini Spark

  • Enter https://your-domain.com in Connected Apps. Spark resolves RFC 9728 metadata and auto-registers via RFC 7591 DCR automatically.

5. Antigravity Desktop (AGY 2.0)

  • Settings → MCP Servers → Add Server
  • URL: https://your-domain.com/sse
  • Transport: Streamable HTTP or SSE (Multiplexed)
  • Auth: OAuth 2.1 or Bearer JWT token

6. Antigravity CLI (agy)

Run agentic tool calls directly from the command line:

agy run "Search the dictionary for 'wisdom'" --mcp-endpoint https://your-domain.com/sse

☁️ Deploying to Google Cloud Run

export GCP_PROJECT="your-gcp-project-id"

# Deploy container with session affinity for legacy SSE fallbacks
make deploy-cloudrun

🤖 Interactive Building with the Agent Skill

If you use an AI coding assistant (Cursor, OpenCode, Claude Code, Gemini CLI), you can build and customize your MCP server interactively using the bundled mcp-go-scaffolder skill (skills/mcp-go-scaffolder/SKILL.md).

How to Start:

Open your AI assistant in this repository and prompt:

"Let's start building a production-grade MCP server using the Go template."

Or with a specific objective:

"Scaffold a new MCP tool for querying PostgreSQL with OAuth 2.1 authentication."

What the Assistant Does:

  1. Gathers your custom tool names, parameters, and database or API integrations.
  2. Generates typed Go argument structs with jsonschema annotations.
  3. Implements dual-emit handlers (human-readable Markdown and typed JSON structures).
  4. Wires stateless Streamable HTTP and SSE transport multiplexing.
  5. Writes integration tests in main_test.go and executes go test to self-verify.

For advanced multi-plugin packaging and marketplace indexing, refer to the agent-plugin-authoring toolchain.

🧠 Bundled Agent Skill

This repository includes an Agent Skill conforming to agentskills.io:

  • Location: skills/mcp-go-scaffolder/SKILL.md
  • Purpose: Instructs AI coding agents on how to customize tool schemas, integrate database adapters (Firestore, PostgreSQL, Redis), and audit security.

📄 License

Apache-2.0 License. See LICENSE for details.