@bayonai/mcp

Shared MCP OAuth and protocol helpers for Bayon apps.

This package contains app-agnostic helpers for remote MCP servers:

• OAuth protected-resource and authorization-server metadata.
• WWW-Authenticate bearer challenges that point MCP clients to metadata.
• PKCE S256 challenge creation and verification.
• Secret hashing, random token generation, and constant-time comparisons.

Application code remains responsible for its own MCP tools/resources/prompts, business authorization, persistence, audit logging, and user-consent UI.

Install

pnpm add @bayonai/mcp

Metadata

import {
  createMcpWwwAuthenticateHeader,
  getOAuthAuthorizationServerMetadata,
  getOAuthProtectedResourceMetadata,
} from "@bayonai/mcp";

const baseUrl = "https://bounded.example/api";
const scopes = ["bounded.read", "bounded.write"];

export const protectedResource = getOAuthProtectedResourceMetadata({
  documentationUrl: "https://bounded.example/docs/mcp",
  scopes,
  serviceUrl: baseUrl,
});

export const authorizationServer = getOAuthAuthorizationServerMetadata({
  scopes,
  serviceUrl: baseUrl,
});

export const wwwAuthenticate = createMcpWwwAuthenticateHeader({
  metadataUrl: `${baseUrl}/.well-known/oauth-protected-resource`,
  realm: "Bounded MCP",
  scopes,
});

PKCE

import { buildPkceChallenge, verifyPkceChallenge } from "@bayonai/mcp";

const challenge = buildPkceChallenge(codeVerifier);

if (!verifyPkceChallenge({ challenge, method: "S256", verifier })) {
  throw new Error("Invalid PKCE verifier.");
}

Token Secrets

import { createMcpRandomToken, hashMcpSecret } from "@bayonai/mcp";

const accessToken = `app_mcp_access_${createMcpRandomToken(40)}`;
const accessTokenHash = hashMcpSecret(accessToken);

Store token hashes, not bearer tokens. The app owns expiry, revocation, refresh rotation, and user/session lookup.

Package Boundaries

Keep these app-specific concerns outside @bayonai/mcp:

• Tool/resource/prompt registries.
• Firestore collection names and indexes.
• Firebase Auth, service-token, or admin consent flows.
• Product-specific scopes such as thunderlist.read or bounded.write.
• Audit logging and mutation authorization.

Release Checks

corepack pnpm --dir packages/bayonai-mcp run lint
corepack pnpm --dir packages/bayonai-mcp run build
corepack pnpm exec vitest run packages/bayonai-mcp/src/metadata.test.ts packages/bayonai-mcp/src/pkce.test.ts packages/bayonai-mcp/src/secrets.test.ts
corepack pnpm --dir packages/bayonai-mcp run smoke:pack