---
name: mcp-go-scaffolder
description: Autonomously scaffolds, customizes, tests, and deploys production-grade Model Context Protocol (MCP) servers in Go using the official go-sdk, dual-transport multiplexing (Stateless Streamable HTTP + SSE), and zero-trust OAuth 2.1 authentication.
license: Apache-2.0
metadata:
  version: "1.0.0"
  trigger: When creating, scaffolding, customizing, or auditing a Go MCP server.
---

# MCP Go Scaffolder

Scaffolds and customizes high-performance, production-ready Go Model Context Protocol (MCP) servers conforming to Go SDK v1.7.0 and modern stateless transport standards.

## The Five Production Pillars

Every Go MCP server constructed by this skill must enforce five architectural pillars:

1. **Dual-Transport Ingress (`multiplexer.go`):** Routes requests over a single endpoint (`/sse` and root `/`), supporting both modern Streamable HTTP (`Stateless: true`) and legacy SSE streams for Cursor, Claude, OpenCode, Spark, Antigravity Desktop, and agy CLI.
2. **Stateless Serverless Resilience:** Every tool execution over Streamable HTTP is self-contained. Cold starts and instance scaling on Cloud Run/AWS ECS never drop active sessions or return `404 session not found`.
3. **Zero-Trust Identity & SSRF Defense (`auth.go`):** Dynamic client onboarding via OAuth 2.1 (RFC 7591 DCR / CIMD) and PKCE S256, protected by an SSRF-safe connection dialer blocking private and loopback IPs.
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 executing business logic.
5. **Sub-Millisecond In-Memory Execution:** Ephemeral authorization codes use datastores with TTL (e.g. Firestore) during handshakes, while active tool queries validate stateless signed HMAC-SHA256 JWTs locally in memory.

---

## Interactive Scaffolding Workflow

Follow these steps when creating or customizing a Go MCP server:

### 1. Gather Tool & Domain Requirements
Identify:
- **Tool Names & Functions:** What actions should the LLM be able to invoke?
- **Argument Schemas:** What inputs are required vs. optional?
- **Read/Write Behavior:** Are tools read-only (`ReadOnlyHint: true`) or destructive?
- **Authentication Strategy:** Local/No-Auth (`DISABLE_AUTH=true`), Bearer JWT, or Full OAuth 2.1.

### 2. Define Typed Structs with `jsonschema` Tags
Define argument structs using standard Go types and `jsonschema` struct tags. The SDK automatically extracts tool schemas from these tags:

```go
type QueryDataArgs struct {
    Query    string `json:"query" jsonschema:"The search keyword or SQL query to execute"`
    Limit    int    `json:"limit,omitempty" jsonschema:"Optional maximum number of records (default: 20)"`
    Category string `json:"category,omitempty" jsonschema:"Optional domain filter category"`
}
```

### 3. Implement Dual-Emit Tool Handlers
Ensure tool handlers implement dual-emit output (returning Markdown text for general LLMs and typed structs for programmatic agents):

```go
func queryDataHandler(ctx context.Context, req *mcp.CallToolRequest, args QueryDataArgs) (*mcp.CallToolResult, *QueryDataResult, error) {
    if strings.TrimSpace(args.Query) == "" {
        return &mcp.CallToolResult{
            Content: []mcp.Content{
                &mcp.TextContent{Text: "Error: query cannot be empty."},
            },
            IsError: true,
        }, nil, nil
    }

    result := &QueryDataResult{ ... }

    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: formatMarkdown(result)},
        },
    }, result, nil
}
```

### 4. Register Tools in `mcp.go`
Use the type-safe `mcp.AddTool` helper:

```go
mcp.AddTool(server, &mcp.Tool{
    Name:        "query_data",
    Title:       "Query Data",
    Description: "Search and retrieve records from the operational dataset.",
    Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
}, queryDataHandler)
```

### 5. Generate Integration Tests
Create integration tests in `main_test.go` utilizing `httptest.NewServer` and `mcp.NewClient` to verify:
- Tool listing (`cs.ListTools`)
- Argument validation and error conditions
- Successful invocation output

### 6. Verify & Lint
Run the test suite:
```bash
go test -v ./...
```

### 7. Package as an Agent Plugin (v1.0.0)
Once the Go MCP server is operational, package it as an **[Agent Plugin](https://agent-plugins.org)**:
- Generate `plugin.json` at root targeting `$schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"`.
- Generate `mcp.json` at root declaring remote Streamable HTTP or local stdio transports.
- Bundle workflow skills in `skills/<skill-name>/SKILL.md` teaching AI agents how to orchestrate the MCP tools.
- For multi-plugin authoring and automated validation, refer to the [agent-plugin-authoring toolchain](https://github.com/ghchinoy/agent-skills/tree/main/plugins/agent-plugin-authoring).

---

## References & Playbooks
- `references/architecture-pillars.md` — Technical analysis of the 4 production pillars.
- `references/persistence-adapter-guide.md` — How to connect Firestore, PostgreSQL, or Redis for multi-instance OAuth code storage.
- `references/scope-gating-playbook.md` — How to implement granular ACL scope gating per tool.