mcp server go
- Repo stars 0
- Author repo skills-registry
- 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.
# 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 -->
Sections and files
Listed in source order.
sections -> When to load → The four facts that change everything → 1. Use the official Go SDK → 2. stdio transport is newline-delimited JSON → 3. The initialize handshake is mandatory and ordered → 4. Two error kinds, don't conflate them
terms -> Never write to stdout from anywhere else · stderr is for logs · do not · JSON-RPC errors · Tool execution errors · Tool name regex · Input schema is auto-generated from the struct. · Output schema is optional.
files/cmd -> modelcontextprotocol/go-sdk · projects/pg-ai-stewards/cmd/stewards-mcp/ · github.com/modelcontextprotocol/go-sdk · Content-Length · mcp.StdioTransport{} · initialize · notifications/initialized · tools/list
body sha256 -> 80028225ebc5
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 shape1. 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-Lengthheaders. One JSON-RPC message per line, embedded newlines forbidden inside messages. The SDK handles this for you viamcp.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 logs3. The initialize handshake is mandatory and ordered
Three steps, in order, before any tool call: Client → server:
initializerequest (protocol version, capabilities) Server → client:initializeresponse (protocol version, server capabilities, serverInfo) Client → server:notifications/initialized(one-way, no response) Only after step 3 may the client sendtools/listortools/call. The SDK enforces this. If you hand-roll, do not lettools/listsucceed beforeinitializedarrives — strict clients reject early-tool servers.4. Two error kinds, don't conflate them
JSON-RPC errors (code
-32602etc.): protocol-level. "Unknown tool", "malformed params". Returned via the JSON-RPCerrorobject. Tool execution errors (isError: trueinsideresult): 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. Usemcp.NewToolResultError(...)for the latter.