mcpkit

mcpkit

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

Docs site · 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

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.

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 (make 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 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)

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.2 — 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 — it's the main signal we use to prioritize what to ship next.