Go to file

Mathias 67decddc8a feat: initial mcp-chassis with auth primitives

Shared Go library for Mathias-owned MCP servers, born from spike S3 of
the 2026-05 homelab architecture review (see
gitea.d-ma.be/mathias/infra/docs/superpowers/handoffs/2026-05-22-mcp-chassis-spike.md
for the viability assessment and abort-criterion check).

Provides three primitives every MCP server today re-implements:

- auth.JWTValidator — Dex OIDC JWT validation. nil-safe (nil = "JWT
  disabled"), audience-optional. Lifted from the identical
  ~80-LOC implementations in gitea-mcp and hyperguild/ingestion.
- auth.BearerMiddleware — dual-mode static-Bearer-or-Dex-JWT gate.
  Static wins first to avoid emitting a WWW-Authenticate challenge
  that would flip claude.ai's MCP client into OAuth discovery for
  static-only deployments. The fall-through 401 emits the RFC 9728
  resource_metadata header only when explicitly configured.
- auth.ProtectedResourceHandler — RFC 9728
  /.well-known/oauth-protected-resource metadata document handler.

Test coverage exercises every branch (static OK, JWT-disabled,
empty bearer, wrong static, with-challenge vs without-challenge,
nil-validator-Validate). go test -race clean.

Deps: github.com/lestrrat-go/jwx/v2 (already a dep of every consumer)
and testify (test-only). No new transitive deps.

First migration target: gitea-mcp. If that port lands in one PR
(abort criterion from spec), brain-mcp (ingestion) follows. Otherwise
chassis reverts per the spec.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-22 09:07:53 +02:00

auth

feat: initial mcp-chassis with auth primitives

2026-05-22 09:07:53 +02:00

go.mod

feat: initial mcp-chassis with auth primitives

2026-05-22 09:07:53 +02:00

go.sum

feat: initial mcp-chassis with auth primitives

2026-05-22 09:07:53 +02:00

README.md

feat: initial mcp-chassis with auth primitives

2026-05-22 09:07:53 +02:00

README.md

mcp-chassis

Shared Go library for Mathias-owned MCP servers. Provides the auth + middleware primitives that every MCP server needs.

Why

By 2026-05-22 there were three+ MCP servers (gitea-mcp, brain-mcp / ingestion, future ones from template-go-agent) each carrying their own near-identical:

Dex JWT validator (~80 LOC, identical jwx/v2 plumbing)
Bearer middleware (~50 LOC, dual-mode static + JWT)
RFC 9728 protected-resource metadata handler (~25 LOC)

The homelab architecture review's spike S3 (see gitea.d-ma.be/mathias/infra/docs/superpowers/handoffs/2026-05-22-mcp-chassis-spike.md) concluded a thin shared lib pays for itself within the first migration. This is that lib.

Non-goals

Replacing each MCP's tool registration / handler logic — that is per-domain.
Solving HTTP routing — consumers keep their own http.ServeMux.
Solving observability — see gitea.d-ma.be/mathias/hyperguild/ingestion/internal/metrics for the hand-rolled Prometheus pattern. May absorb a metrics subpackage here later, once a second consumer needs it.

Packages

`auth`

JWTValidator — Dex OIDC JWT validation. nil is a valid value meaning "JWT auth disabled".
BearerMiddleware — static-Bearer-or-Dex-JWT gate. Static wins first; only emits WWW-Authenticate: Bearer ... resource_metadata=... on 401 when resourceMetadataURL is non-empty (claude.ai OAuth discovery).
ProtectedResourceHandler — RFC 9728 metadata document for GET /.well-known/oauth-protected-resource.

Usage

package main

import (
	"context"
	"net/http"
	"os"

	"gitea.d-ma.be/mathias/mcp-chassis/auth"
)

func main() {
	staticToken := os.Getenv("BRAIN_MCP_TOKEN")
	dexIssuer := os.Getenv("DEX_ISSUER_URL")
	audience := os.Getenv("MCP_AUDIENCE")
	resourceURL := os.Getenv("MCP_RESOURCE_URL")

	validator, err := auth.NewJWTValidator(context.Background(), dexIssuer, audience)
	if err != nil {
		panic(err)
	}

	mux := http.NewServeMux()
	mux.HandleFunc("GET /.well-known/oauth-protected-resource",
		auth.ProtectedResourceHandler(resourceURL, dexIssuer))
	mux.Handle("/mcp", auth.BearerMiddleware(
		staticToken,
		validator,
		"brain",
		resourceURL+"/.well-known/oauth-protected-resource",
		mcpHandler(),
	))

	_ = http.ListenAndServe(":3300", mux)
}

func mcpHandler() http.Handler { /* per-domain */ return nil }

Versioning

Trunk-based development on main. Tagged with semver. Consumers pin specific tags (go.mod require gitea.d-ma.be/mathias/mcp-chassis v0.x.y) and bump deliberately.

Migrations are documented per-consumer in the consumer's CHANGELOG / commits.

Dependencies

github.com/lestrrat-go/jwx/v2 — JWKS cache + JWT parsing. Same dep every MCP already had; no new transitive cost when adopting the chassis.
github.com/stretchr/testify — tests only.

stdlib otherwise.