What does 'kavachOS' mean?

kavachOS is a portmanteau of 'kavach' (Sanskrit for 'armor') and 'OS' (operating system). The name describes the library's role: an operating layer that shields every identity, call, token, and delegation in an application.

How is 'kavach' pronounced?

Ka-vach. In Sanskrit (कवच), it means 'armor': the layered, protective armor warriors wore into battle.

A TypeScript library for authentication and authorization, covering both AI agents and human users. It provides identity, permissions, delegation chains, audit trails, and MCP OAuth 2.1 in a single package. MIT licensed, edge-native.

00/Use case · MCP servers

OAuth 2.1 for MCP servers, without the six-week detour.

The MCP specification asks authorization servers to implement OAuth 2.1 with PKCE S256, protected resource metadata, dynamic client registration, and server metadata. KavachOS ships all of it, RFC-compliant, edge-ready. Point your resource server at it and get back to building tools.

Set up MCP OAuth Read the protocol overview

01/TL;DR

Three things that matter.

RFC-correct, not hand-rolled

RFC 9728 protected resource metadata, RFC 8414 server metadata, RFC 7591 dynamic client registration, PKCE S256 everywhere.

Works at the edge

Deploy on Cloudflare Workers, Vercel Edge, Deno, or Node. No JVM, no extra infrastructure, no secondary database.

One configuration file

Describe your resources, scopes, and issuer in a single config. KavachOS handles discovery, token exchange, and revocation.

02/The problem

Building OAuth 2.1 by hand is where MCP server launches die.

The MCP spec is generous about what clients expect: an authorization server that advertises itself with RFC 8414, issues tokens with PKCE S256, accepts dynamic client registration per RFC 7591, and serves protected resource metadata per RFC 9728. Most teams underestimate this and lose weeks.

PKCE S256 done wrong

Plain PKCE is trivially replayable. Clients expect S256 specifically. Getting the code challenge encoding right is a common stumble.

Metadata endpoints missing or wrong

MCP clients look for /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. If either is missing or returns the wrong shape, connection fails silently.

Dynamic client registration not implemented

RFC 7591 is optional in OAuth 2.1 but required in practice for MCP. Skipping it means every new client needs a manual onboarding.

Tokens not bound to an audience

Without an aud claim, a token issued for one MCP server can be replayed against another. Clients expect tight audience binding.

03/How kavachOS fits

A drop-in OAuth 2.1 server that speaks MCP natively.

KavachOS ships the full authorization server surface that MCP clients expect. You point your resource server at it, declare your scopes, and go. No custom endpoint code.

Metadata

Discovery endpoints served for you

The /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource responses are generated from your config. Schemas match RFC 8414 and RFC 9728 exactly.

Primitive 01

PKCE

S256 enforced at the authorize endpoint

Plain PKCE and missing code challenges are rejected. The authorization endpoint validates the code_challenge_method before issuing a code.

Primitive 02

DCR

Dynamic client registration included

New MCP clients register at /register per RFC 7591 and receive a client_id and client_secret on the fly. You can gate registration by policy or accept it open.

Primitive 03

Audience

Tokens are bound to one resource server

Every access token carries an aud claim. Your resource server verifies it on every request. Replay across servers is blocked at the protocol level.

Primitive 04

Revocation

Token revocation per RFC 7009

When a user or admin revokes a client, all outstanding tokens stop verifying at the next resource call. No cache staleness.

Primitive 05

04/In code

The minimum you need to write.

Full examples with framework adapters live in the docs. This is the shape of what you wire into your app.

Open the quickstart

mcp-server.ts

typescript

Wire a KavachOS authorization server into a Hono-based MCP server. The middleware verifies the token, the audience, and the scope on every tool call.

import { Hono } from "hono";
import { kavachosMCP } from "kavachos/mcp";

const app = new Hono();

app.use("/tools/*", kavachosMCP({
  issuer: "https://auth.example.com",
  audience: "https://mcp.example.com",
  requiredScope: "tools:call"
}));

app.post("/tools/:name", async (c) => {
  const { subject, scopes } = c.get("kavachos");
  // subject is the MCP client, scopes enforced above.
  return c.json(await runTool(c.req.param("name"), c.req.json()));
});

export default app;

RFC 9728

Protected resource metadata

RFC 8414

Auth server metadata

RFC 7591

Dynamic client registration

PKCE S256

Enforced at authorize

05/Before / after

The difference shows up in the audit log.

Without scoped identity

pkce s256 done wrong
metadata endpoints missing or wrong
dynamic client registration not implemented

With kavachOS

discovery endpoints served for you
s256 enforced at the authorize endpoint
dynamic client registration included

We estimated three weeks to build OAuth 2.1 for our MCP server. We pointed it at KavachOS in under an hour and spent the saved time on the tools themselves. That was the whole point.

MCP server maintainer· Developer tools platform

06/FAQ

What teams building for mcp server operators usually ask.

Short answers. Link out to the docs if you want the long version.

Does KavachOS support the full MCP OAuth 2.1 spec?

Yes. PKCE S256 is enforced, RFC 8414 server metadata and RFC 9728 protected resource metadata are served, RFC 7591 dynamic client registration is implemented, and RFC 7009 token revocation is supported. Audience-bound access tokens are the default.

Can I host the authorization server myself or do I need KavachOS Cloud?

Both options work. The kavachos library is MIT licensed and runs the same authorization server logic on your infrastructure. KavachOS Cloud runs it as a managed service with a dashboard, hosted OAuth, and metered billing.

How do I register the MCP clients that will connect to my server?

If you enable dynamic client registration, clients register themselves by POSTing to the /register endpoint per RFC 7591. If you want manual control, you can register clients in the dashboard or via the management API and distribute client_id and client_secret out of band.

Does it run on Cloudflare Workers?

Yes, and this is the recommended deployment for MCP servers. The full authorization server runs on Workers with D1 for storage and KV for token cache. Cold start is under 50ms.

What about resource server integration with my existing Hono, Express, or Node server?

We ship middleware for Hono, Express, Fastify, Next.js route handlers, and a generic JWKS-based verifier for anything else. The middleware reads the Bearer token, verifies the signature, checks the audience, and enforces the required scope before your handler runs.

How does KavachOS compare to writing this myself with Hydra or Keycloak?

Hydra and Keycloak are full-featured OAuth servers, but neither is edge-native and neither ships with MCP-shaped defaults. You will still write RFC 9728 metadata by hand and wire audience binding correctly. KavachOS assumes the MCP shape out of the box.

07/Related reading

Keep going.

On kavachos.com

Point your MCP server at KavachOS and ship this week.

Managed cloud or self-hosted, both options run the same RFC-compliant authorization server. Free to start, no credit card.

Join early access Read the docs Star on GitHub