mcp server go

AI Community

Skill notes

When to load

Editing or building Go code in projects/pg-ai-stewards/cmd/stewards-mcp/ Adding a new MCP tool to an existing server Wiring up a new MCP server to Claude Code or another MCP client Hitting "tool not found" / "JSON-RPC error" / silent connection failures Reading another project's MCP server code to understand its shape

1. Use the official Go SDK

github.com/modelcontextprotocol/go-sdk — maintained jointly by Anthropic and Google. v1.6.0 as of 2026-05-08. Schema reflection from struct tags, transport handling, capability negotiation, error wrapping all built in. Going from scratch in Go is ~250 lines for a tools-only stdio server; using the SDK is ~30. Use the SDK.

2. stdio transport is newline-delimited JSON

NOT LSP-style with Content-Length headers. One JSON-RPC message per line, embedded newlines forbidden inside messages. The SDK handles this for you via mcp.StdioTransport{}. If you ever roll your own: Read stdin line by line Write each response as one line to stdout Never write to stdout from anywhere else — that corrupts the protocol stream stderr is for logs

3. The initialize handshake is mandatory and ordered

Three steps, in order, before any tool call: Client → server: initialize request (protocol version, capabilities) Server → client: initialize response (protocol version, server capabilities, serverInfo) Client → server: notifications/initialized (one-way, no response) Only after step 3 may the client send tools/list or tools/call. The SDK enforces this. If you hand-roll, do not let tools/list succeed before initialized arrives — strict clients reject early-tool servers.

4. Two error kinds, don't conflate them

JSON-RPC errors (code -32602 etc.): protocol-level. "Unknown tool", "malformed params". Returned via the JSON-RPC error object. Tool execution errors (isError: true inside result): runtime. "DB connection failed", "Tool returned no results". The model SEES these and can self-correct. Mixing them up means the model treats DB outages as unrecoverable system errors. Use mcp.NewToolResultError(...) for the latter.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Manual integration
External API key
Not required
Operating systems
Windows · Docker
Runtime requirements
Docker
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# mcp-server-go — building MCP servers in Go

This skill answers the questions that block productive MCP server work in Go. Verified against the 2025-11-25 spec and the official `modelcontextprotocol/go-sdk` v1.6.0 (released 2026-05-08).

## When to load

- Editing or building Go code in `projects/pg-ai-stewards/cmd/stewards-mcp/`
- Adding a new MCP tool to an existing server
- Wiring up a new MCP server to Claude Code or another MCP client
- Hitting "tool not found" / "JSON-RPC error" / silent connection failures
- Reading another project's MCP server code to understand its shape

## The four facts that change everything

### 1. Use the official Go SDK

`github.com/modelcontextprotocol/go-sdk` — maintained jointly by Anthropic and Google. v1.6.0 as of 2026-05-08. Schema reflection from struct tags, transport handling, capability negotiation, error wrapping all built in. Going from scratch in Go is ~250 lines for a tools-only stdio server; using the SDK is ~30. Use the SDK.

```go
import "github.com/modelcontextprotocol/go-sdk/mcp"
```

### 2. stdio transport is newline-delimited JSON

NOT LSP-style with `Content-Length` headers. One JSON-RPC message per line, embedded newlines forbidden inside messages. The SDK handles this for you via `mcp.StdioTransport{}`. If you ever roll your own:

- Read stdin line by line
- Write each response as one line to stdout
- **Never write to stdout from anywhere else** — that corrupts the protocol stream
- **stderr is for logs**

### 3. The `initialize` handshake is mandatory and ordered

Three steps, in order, before any tool call:
1. Client → server: `initialize` request (protocol version, capabilities)
2. Server → client: `initialize` response (protocol version, server capabilities, serverInfo)
3. Client → server: `notifications/initialized` (one-way, no response)

Only after step 3 may the client send `tools/list` or `tools/call`. The SDK enforces this. If you hand-roll, **do not** let `tools/list` succeed before `initialized` arrives — strict clients reject early-tool servers.

### 4. Two error kinds, don't conflate them

- **JSON-RPC errors** (code `-32602` etc.): protocol-level. "Unknown tool", "malformed params". Returned via the JSON-RPC `error` object.
- **Tool execution errors** (`isError: true` inside `result`): runtime. "DB connection failed", "Tool returned no results". The model SEES these and can self-correct.

Mixing them up means the model treats DB outages as unrecoverable system errors. Use `mcp.NewToolResultError(...)` for the latter.

## Minimum viable server (uses official SDK)

```go
package main

import (
    "context"
    "log"
    "os"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

// Tool input. SDK reflects struct tags into JSON Schema 2020-12.
type SearchInput struct {
    Query string `json:"query" jsonschema:"description=topic to search"`
    Limit int    `json:"limit,omitempty" jsonschema:"description=max results,minimum=1,maximum=100"`
}

// Tool output. SDK reflects struct tags into outputSchema if you declare it.
type SearchOutput struct {
    Results []map[string]any `json:"results"`
}

// Tool handler. Three returns: optional pre-built result, structured output,
// optional error. SDK builds the standard {content, structuredContent, isError}
// shape automatically.
func studySearch(
    ctx context.Context,
    req *mcp.CallToolRequest,
    in SearchInput,
) (*mcp.CallToolResult, SearchOutput, error) {
    // ... query DB, build results ...
    return nil, SearchOutput{Results: []map[string]any{}}, nil
}

func main() {
    // CRITICAL: pin logger to stderr. Anything to stdout corrupts the protocol.
    logger := log.New(os.Stderr, "stewards-mcp: ", log.LstdFlags)

    s := mcp.NewServer(&mcp.Implementation{
        Name:    "pg-ai-stewards",
        Version: "0.1.0",
    }, nil)

    mcp.AddTool(s, &mcp.Tool{
        Name:        "study_search",
        Description: "Find studies in the substrate by topic.",
    }, studySearch)

    if err := s.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        logger.Fatalf("server.Run: %v", err)
    }
}
```

That's a fully spec-compliant tools-only MCP server. Build, register in `.mcp.json`, restart Claude Code session.

## Tool registration patterns

**Tool name regex:** `[A-Za-z0-9_.-]{1,128}`. Slashes and spaces are silently rejected by some clients. Pick a convention (`study_search`, `study.search`, or `study-search`) and stick to it.

**Input schema is auto-generated from the struct.** Use `json:"..."` tags and `jsonschema:"..."` for descriptions, ranges, enums.

**Output schema is optional.** If you declare it, you MUST return `structuredContent` matching it. Strict clients reject mismatches. Either:
- Declare and validate (best for typed APIs)
- Omit and rely on the auto-generated text block (best for free-form results)

**Tool list changes** can be announced at runtime via `notifications/tools/list_changed` if your server has dynamic tool sets. For static tool sets, declare `capabilities.tools.listChanged: false` (the SDK default — don't override unless needed).

## Claude Code integration

Three scopes for registering an MCP server:

| Scope | File | Use for |
|-------|------|---------|
| Project | `.mcp.json` (repo root) | Servers that ship with the project, work for all teammates |
| Local user | `~/.claude.json` | Personal experiments, tools |
| Global user | `~/.claude/settings.json` (rarely used) | System-wide tools |

For project sidecars (the case here), use **`.mcp.json` at repo root**:

```json
{
  "mcpServers": {
    "pg-ai-stewards": {
      "type": "stdio",
      "command": "${WORKSPACE_FOLDER}/projects/pg-ai-stewards/bin/stewards-mcp.exe",
      "args": ["--dsn", "${STEWARDS_DSN:-postgres://stewards:stewards@localhost:55433/stewards?sslmode=disable}"],
      "env": {}
    }
  }
}
```

Env-var expansion: `${VAR}` and `${VAR:-default}`. Project-scoped servers prompt for approval on first run; clear with `claude mcp reset-project-choices` if testing a config change.

**Restart the Claude Code session** after editing `.mcp.json`. The MCP client only re-reads the config at session start. The skill listing in subsequent turns will then show the new tools.

## Gotchas (recurring failures)

1. **stderr discipline.** Any `fmt.Println` or default-logger call writes to stdout and corrupts the protocol. Pin all logging to `os.Stderr`. Audit dependencies — pgx's default logger writes to stdout in some configurations.

2. **Don't respond to notifications.** `notifications/initialized` and `notifications/cancelled` arrive without `id`. Sending a response is a protocol violation. The SDK handles this; rolled-your-own constantly breaks it.

3. **Tool name characters.** Stick to `[A-Za-z0-9_.-]`. Underscores are safest.

4. **`isError: true` vs JSON-RPC error.** Tool-execution failures use `isError: true` so the model can react. JSON-RPC errors are for protocol violations. `mcp.NewToolResultError(...)` is the SDK helper.

5. **Buffered stdout.** Go's stdout is fully buffered when not connected to a TTY (Claude Code spawns you as a pipe). The SDK flushes after each message. If you write a custom transport, wrap stdout in a `bufio.Writer` and flush every line.

6. **Initialize before tools.** Do not let `tools/list` succeed before `notifications/initialized` arrives. Strict clients enforce ordering.

7. **`outputSchema` is a contract.** If declared, validate matches before sending. Either be rigorous or omit the schema.

8. **First-run approval dialog.** Project-scoped MCP servers prompt the user for approval on first invocation. Document this for teammates so they don't think the server is broken.

9. **pgx connection lifecycle.** Use `pgxpool.New(ctx, dsn)` for connection pooling. Close the pool on `s.Run()` exit. Don't share `*pgx.Conn` across goroutines — use the pool.

10. **Context cancellation.** The SDK passes `context.Context` through to handlers. Honor it. If a tool call is mid-flight and the client cancels, abort cleanly via `ctx.Done()`.

## Real-world references

When in doubt, look at how production Go MCP servers are structured:

- **[subnetmarco/pgmcp](https://github.com/subnetmarco/pgmcp)** — Postgres MCP using the official Go SDK. Closest analog to what we're building. Has CI, Docker, schema fixtures.
- **[mark3labs/mcp-go examples/](https://github.com/mark3labs/mcp-go/tree/main/examples)** — even if you use the official SDK, the example servers are clean reference implementations of the protocol flow.
- **[modelcontextprotocol/go-sdk examples/](https://github.com/modelcontextprotocol/go-sdk/tree/main/examples)** — the official SDK's bundled examples.

## Project-specific (pg-ai-stewards)

**Binary location:** `projects/pg-ai-stewards/cmd/stewards-mcp/main.go`. Compiled to `projects/pg-ai-stewards/bin/stewards-mcp.exe` on Windows.

**Connection string:** `STEWARDS_DSN` env var, defaulting to `postgres://stewards:stewards@localhost:55433/stewards?sslmode=disable` (the docker-compose port mapping).

**First tools to register (Phase 3e.1):**
- `study_search` — wraps `stewards.study_search_text(query, kinds, limit)`, returns matched study slugs + titles + scores
- `study_get` — wraps `stewards.study_get(slug)`, returns body + frontmatter + citations

**Future tools (Phase 3e.2-3e.5):** `gospel_passthrough`, `stewards_brain`, `stewards_work_item`, `gospel_search`, `gospel_get` (the latter two via outbound MCP-client to gospel-engine-v2).

**Findings doc:** `projects/pg-ai-stewards/docs/3e-mcp-findings.md` (created when 3e.1 ships).

---
> Source: [cpuchip/scripture-study](https://github.com/cpuchip/scripture-study) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.