mcpkit

Production-grade MCP (Model Context Protocol) server and client library for Go.

Docs site · Examples · Conformance report · Capabilities · Changelog · Quick Start

Quick Start

import (
    "time"

    "github.com/panyam/mcpkit/core"
    "github.com/panyam/mcpkit/server"
)

srv := server.NewServer(
    core.ServerInfo{Name: "my-server", Version: "0.1.0"},
    server.WithToolTimeout(30 * time.Second),
)

srv.RegisterTool(core.ToolDef{
    Name: "greet", Description: "Say hello",
    InputSchema: map[string]any{"type": "object", "properties": map[string]any{"name": map[string]any{"type": "string"}}},
}, func(ctx core.ToolContext, req core.ToolRequest) (core.ToolResponse, error) {
    var args struct{ Name string `json:"name"` }
    req.Bind(&args)
    return core.TextResult("Hello, " + args.Name + "!"), nil
})

srv.Run(":8787") // Streamable HTTP — blocks

Run blocks. When you start it in a goroutine, wait for Ready() instead of
sleeping. It closes once the listener is bound and the port is accepting:

go srv.Run(":8787")
<-srv.Ready()
// safe to connect; srv.Addr() has the bound address (useful with ":0")

A client mirrors it. Every method that talks to the server takes a context:

ctx := context.Background()

c := client.NewClient("http://localhost:8787/mcp",
    core.ClientInfo{Name: "my-client", Version: "0.1.0"},
)
if err := c.Connect(ctx); err != nil { // bounds the handshake, not the session
    log.Fatal(err)
}
defer c.Close()

out, err := c.ToolCall(ctx, "greet", map[string]any{"name": "world"})

Packages

Conformance

mcpkit passes the official MCP conformance suite for the base protocol and the conformance scenarios for a long list of draft/recent SEPs, the "batteries" that set it apart from a minimal SDK:

Tasks v2, MRTR, and the SEP-2575 stateless wire all run against modelcontextprotocol/conformance main directly (merged upstream). The full per-SEP rollup is published at panyam.github.io/mcpkit/conformance.

On SEP-2356: the working group closed it on 2026-06-26 in favour of SEP-2631 (File Objects and Transfer), which is still in draft. The file-input surface mcpkit ships and the scenarios above continue to work and are still exercised in CI; the row is kept so the behaviour stays covered, not as a claim of conformance to a live proposal. Migration to SEP-2631 is tracked in issue 827.

Three artifacts describe mcpkit's conformance posture at increasing granularity:

• CONFORMANCE.md — auto-generated per-SEP rollup (regenerated on every PR; CI-gated for staleness). Live site.
• conformance/UPSTREAM_AUDIT.md — per-scenario pass/fail against upstream's full test set (just testconf-upstream-audit). Live site.
• conformance/AUTH_SPEC_COVERAGE.md — hand-curated per-clause traceability for the auth surface: every MUST/SHOULD → mcpkit impl file:line → test that proves it.

Testing

make is the supported task runner and the only one CI uses, so make is
preinstalled everywhere and needs no setup step.

make test          # Unit tests (200+ across core/server/client)
make testall       # ALL tests + Keycloak + conformance + HTML report
make testconf      # MCP conformance suite
make testconfauth  # Auth conformance
make test-e2e      # E2E tests (auth + apps)
make test-apps-playwright  # ext-apps Playwright suite (needs Node.js)

Justfiles mirroring the same target names also exist and are kept as an
experiment. They are not used by CI, and make is authoritative when the two
disagree.

Documentation

Client Features

Subprocess MCP Servers

Spawn and manage subprocess MCP servers with CommandTransport:

c := client.NewClient("", info,
    client.WithCommandTransport("python", []string{"my_server.py"},
        client.WithEnv("DEBUG=1"),
        client.WithShutdownTimeout(10*time.Second),
    ),
    client.WithMaxRetries(3), // auto-restart on crash
)
c.Connect()
defer c.Close()

Custom Request Headers

Inject headers into all outgoing HTTP requests:

c := client.NewClient(url, info,
    client.WithModifyRequest(func(req *http.Request) {
        req.Header.Set("X-Tenant-ID", "acme")
        req.Header.Set("X-Request-ID", uuid.New().String())
    }),
)

Auth Performance

For best performance, configure your authorization server to use ES256 (ECDSA P-256) instead of RS256. ES256 verification is ~10x faster, with smaller keys and tokens. See auth design doc for details.

Dependencies

• servicekit v0.1.3 — SSE hub, graceful shutdown, HTTP error types
• oneauth v0.1.31 — JWT/OIDC (only via ext/auth sub-module)

Star History

If mcpkit is useful to you, starring the repo is the cheapest way to help, since it's the main signal we use to prioritize what to ship next.