mcpkit - Toolkit Go para Servidores MCP
AcidSailor/mcpkit
Helpers Go para acelerar desenvolvimento de servidores MCP
Ver no GitHubBiblioteca Go que fornece primitivos compartilhados para construir servidores MCP com o go-sdk oficial. Inclui helpers para transporte via stdio/HTTP, registro de tools e recursos tipados, validação de entrada, derivação de schemas OpenAPI e suporte a telemetria com OpenTelemetry.
Instalação
npx convez-ai AcidSailor/mcpkit1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir servidores MCP em Go com menos boilerplate
- Registrar tools e recursos com type-safety
- Implementar confirmação de ações destrutivas (elicitation)
- Integrar telemetria e logging estruturado em servidores MCP
- Testar servidores MCP com sesões em memória
Veredito

mcpkit é uma biblioteca sólida para engenheiros Go que precisam construir servidores MCP produção-ready. Reduz significativamente boilerplate com abstrações bem projetadas (toolkit, registry, elicit), mas requer familiaridade com Go 1.27+ e o ecossistema MCP.
README
A tradução para o português deste README ainda está na fila.
mcpkit
mcpkit provides Go helpers for MCP servers built with the official
modelcontextprotocol/go-sdk.
It uses the SDK protocol implementation and adds transport serving, typed tool
and resource registration, elicitation gates, OpenAPI schema assembly, and test
helpers. The only executable is cmd/mcpbstage, which stages .mcpb bundles.
Packages
serverserves an*mcp.Serverover stdio, streamable HTTP, or both.toolkitregisters typed read and write tools. Write tools use elicitation.resourceregisters static and RFC 6570 URI-template resources.registrydefines tools and resources before binding them to a server.elicitprovides the write-tool gate and confirmation builders.openapiderives tool schemas from a dereferenced OpenAPI document.validateprovides input validators with matchable error sentinels.telemetrytraces MCP requests with a caller-supplied OpenTelemetryTracerProviderand logs them to a caller-supplied*slog.Logger.mcptestcreates in-memory client and server sessions for tests.
Requirements
- Go 1.27 or later
Installation
go get github.com/acidsailor/mcpkit
Import only the required subpackages:
import (
"github.com/acidsailor/mcpkit/server"
"github.com/acidsailor/mcpkit/toolkit"
"github.com/acidsailor/mcpkit/validate"
)
Quick start
The following program registers one read tool and one confirmation-gated write tool, then serves them over HTTP:
package main
import (
"context"
"log"
"net/http"
"github.com/acidsailor/mcpkit/elicit"
"github.com/acidsailor/mcpkit/server"
"github.com/acidsailor/mcpkit/toolkit"
"github.com/acidsailor/mcpkit/validate"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type GreetInput struct {
Name string `json:"name"`
}
func main() {
mcpServer := mcp.NewServer(
&mcp.Implementation{Name: "demo", Version: "0.1.0"},
nil,
)
toolkit.AddRead(
toolkit.New(
mcpServer,
"greet",
"Greet a user by name",
toolkit.InputSchema[GreetInput](),
func(ctx context.Context, in GreetInput) (toolkit.Value[string], error) {
return toolkit.WrapValue("hello, "+in.Name, nil)
},
).WithValidateFunc(func(ctx context.Context, in GreetInput) error {
return validate.RequireNonEmpty("name", in.Name)
}),
)
// Elicitation is a user prompt, not an authorization check.
toolkit.AddWrite(
toolkit.New(
mcpServer,
"delete_thing",
"Delete a thing",
toolkit.InputSchema[GreetInput](),
func(ctx context.Context, in GreetInput) (toolkit.Value[string], error) {
return toolkit.WrapValue("deleted "+in.Name, nil)
},
).WithElicitParamsFunc(
elicit.SimpleConfirmation[GreetInput]("Delete this thing?"),
),
)
handler := mcp.NewStreamableHTTPHandler(
func(*http.Request) *mcp.Server { return mcpServer },
&mcp.StreamableHTTPOptions{Stateless: true, JSONResponse: true},
)
srv := server.New(
mcpServer,
server.WithTransport(server.HTTP),
server.WithHTTPServer(&http.Server{
Addr: ":8080",
Handler: handler,
}),
)
if err := srv.ListenAndServe(context.Background()); err != nil {
log.Fatal(err)
}
}
server.HTTP and server.Both require a caller-configured *http.Server.
Use a stateless streamable HTTP handler for protocol 2026-07-28 clients.
Clients on older protocols need stdio or a stateful handler to run gated writes.
server.WithLogger sets the logger for lifecycle events; without it, the
server logs nothing.
Resources
A static resource has one URI and returns a Content value:
import "github.com/acidsailor/mcpkit/resource"
resource.New(
mcpServer,
"config://app",
"app-config",
"The application configuration",
func(ctx context.Context) (resource.Content, error) {
return resource.NewJSON(loadConfig(ctx)), nil
},
).WithTitle("App Config").Add()
A template resource receives the concrete URI and its RFC 6570 variables.
Return resource.ErrNotFound when the requested resource does not exist:
resource.NewTemplate(
mcpServer,
"users://{id}",
"user",
"A user by id",
func(ctx context.Context, uri string, vars resource.Vars) (resource.Content, error) {
id, err := vars.Int("id")
if err != nil {
return nil, err
}
user, ok := lookupUser(id)
if !ok {
return nil, resource.ErrNotFound
}
return resource.NewJSON(user), nil
},
).WithMIMEType("application/json").Add()
Add panics on a malformed static URI. NewTemplate panics on an invalid RFC
6570 template. These are configuration errors.
The URI identifies a resource; the client does not fetch it. The read handler
produces the content. Use one URI convention per server, and keep static and
template forms consistent, such as users://42 and users://{id}.
Test resource reads and listings through mcptest:
session := mcptest.NewSession(t, mcpServer)
cfg := mcptest.ReadResourceJSON[Config](t, session, "config://app")
user := mcptest.ReadResourceJSON[User](t, session, "users://42")
uris := mcptest.ListResourceURIs(t, session)
templates := mcptest.ListResourceTemplateURIs(t, session)
Tracing
telemetry.TraceReceiving starts one server span per MCP request. Span names and
parenting follow the MCP semantic conventions, and spans carry a subset of
their attributes. Pass the TracerProvider you configured; the
package never reads OpenTelemetry globals and configures no exporter:
mcpServer.AddReceivingMiddleware(telemetry.TraceReceiving(tracerProvider))
Spans are named tools/call <tool>, prompts/get <prompt>, or the method
name. A call error or a tool result with IsError marks the span failed; a
JSON-RPC error records its code.
Incoming notifications also get a server span. Outbound calls made with the handler context,
such as otelhttp client requests, nest under the request span.
A client continues its own trace by sending W3C traceparent and tracestate
in the request's params._meta. MCP carries trace context in messages, not
HTTP headers, because one HTTP request can carry several MCP messages and
stdio has no headers. When both exist, the _meta parent wins and the
ambient span, such as an otelhttp handler span, becomes a link. Use
telemetry.WithPropagator to read other formats; baggage in _meta needs
a composite propagator that includes propagation.Baggage.
The ambient span is the one in the handler context. Stateless streamable HTTP gives each request its own context. A stateful session keeps the context of the HTTP request that created it, so later requests see that request's span.
Outgoing MCP calls and notifications can continue the same trace:
mcpServer.AddSendingMiddleware(telemetry.TraceSending(tracerProvider))
TraceSending starts a client span from the supplied context and injects
that span into a copy of params._meta. It preserves unrelated metadata
and concrete SDK request/params types. Configured propagation fields are
replaced so reused params cannot carry stale trace context. Without a
parent in the context, the send starts a new trace. Notification spans end
when sending completes, not when the peer finishes handling the message.
Both tracing constructors also work on an SDK client.
The middleware copies only the structs and metadata it modifies. It does not mutate the params it receives, though the SDK may add its own protocol metadata before invoking middleware.
API migration: telemetry.Middleware is now telemetry.TraceReceiving;
the previous LogMiddleware name is now Log.
Request logging
telemetry.Log logs requests and notifications to the
*slog.Logger you pass. It complements tracing and does not repeat it: the
record has the span name as its message, such as tools/call echo, a level,
and an outcome. The request attributes, duration, and error stay on the
span, and the record's trace context links the two:
| Outcome | Level | Cause |
|---|---|---|
ok | Info | Success. |
input_required | Info | A tool, prompt, or resource requested input. |
declined, canceled | Info | The user declined or canceled the prompt. |
tool_error | Warn | The tool result has IsError. |
error | Error | The request failed with a call error. |
Use WithLevelFunc to change severity while keeping the outcome and the
client response unchanged. For example, to skip notifications and log invalid-params errors at Info:
logs := telemetry.Log(logger, telemetry.WithLevelFunc(
func(method string, o telemetry.Outcome, err error) (slog.Level, bool) {
if strings.HasPrefix(method, "notifications/") {
return 0, false
}
if e, ok := errors.AsType[*jsonrpc.Error](err); ok &&
o == telemetry.OutcomeError && e.Code == jsonrpc.CodeInvalidParams {
return slog.LevelInfo, true
}
return o.DefaultLevel(), true
},
))
Params and results are not logged by default because they can hold secrets
and personal data. telemetry.WithPayload takes a function that returns the
attributes to add, so you choose what to log and how to redact it.
Pass tracing first in one AddReceivingMiddleware call, as below. With
separate calls, register logging first and tracing last: the last call wraps
the existing handler. Both forms let tracing pass its span to logging. An
OpenTelemetry log bridge such as otelslog then sets the record's trace and
span IDs, as it does for records your handlers log with the request context:
logger := slog.New(otelslog.NewHandler(
"myserver",
otelslog.WithLoggerProvider(loggerProvider),
))
mcpServer.AddReceivingMiddleware(
telemetry.TraceReceiving(tracerProvider),
telemetry.Log(logger),
)
The same logger middleware can be installed for outgoing messages:
mcpServer.AddSendingMiddleware(
telemetry.TraceSending(tracerProvider),
telemetry.Log(logger.With("direction", "send")),
)
For an outgoing notification, ok means send completion, not confirmation
that the peer handled it. A tool error received from the peer has no Go
error in GetError(), so WithLevelFunc receives a nil cause for it.
Pass the same logger as mcp.ServerOptions.Logger to include the SDK's
session events. The SDK logs them without a request context, so they carry
no trace. A stdio server must not log to stdout.
Result envelopes
MCP structured results must have a JSON object at the root. Wrap slice and scalar results with the supplied envelopes:
return toolkit.WrapItems(client.List(ctx))
return toolkit.WrapValue(client.Count(ctx))
Items.MarshalJSON encodes a nil slice as [].
Error matching
Each package defines its own sentinels. Match them with errors.Is:
if errors.Is(err, toolkit.ErrUserDeclined) { /* user declined */ }
if errors.Is(err, server.ErrInvalidAddr) { /* invalid listen address */ }
Test tools
mcptest runs registered tools through the SDK in-memory transport:
session := mcptest.NewSession(t, mcpServer)
session = mcptest.NewSessionWithElicitation(t, mcpServer, handler)
Use NewSessionWithElicitation for gated write tools.
Development
task testruns all tests.task lintformats code and applies lint fixes.task ciruns read-only format and lint checks.task checkrunstask lintandtask test.
License
Licensed under the Apache-2.0. See LICENSE.