mcp-registry-spec-sdk weekly downloads statistics

MCP Registry SDK (TypeScript)

A minimal, typed client for the official Model Context Protocol (MCP) Registry API.

Install

• bun: bun add mcp-registry-spec-sdk
• npm: npm install mcp-registry-spec-sdk
• pnpm: pnpm add mcp-registry-spec-sdk
• yarn: yarn add mcp-registry-spec-sdk

Requires Bun 1.3.10+ for development. Published package supports maintained Node.js releases starting with Node.js 22.

Development

bun install
bun run test
bun run build

Quick start

import { MCPRegistryClient } from "mcp-registry-spec-sdk";

// Default: v0.1 (stable) API
const client = new MCPRegistryClient();

// Optionally set a default Bearer token for publish/admin
client.setAuthToken(process.env.MCP_REGISTRY_TOKEN);

// Ping
const ping = await client.ping.ping();
console.log("ping:", ping);

// Health
const health = await client.health.getHealth();
console.log("health:", health);

// List servers (with optional filters)
const list = await client.server.listServers({
  search: "openai",
  limit: 10,
  updatedSince: "2024-01-01T00:00:00Z",
});
console.log("servers:", list.servers?.length ?? 0, "next:", list.metadata.nextCursor);

// Get a specific server version
const server = await client.server.getServerVersion("org/server-name", "latest");
console.log("server:", server.server.name);

API Versions:

• v0.1 (default): Stable version, only additive backward-compatible changes
• v0: Development version, may evolve with breaking changes

// Explicit v0 if needed
const devClient = new MCPRegistryClient(undefined, "v0");

API surface

The client is namespaced by feature:

• auth — Token exchange helpers
• health — Health check
• ping — Connectivity check
• server — List/get servers (+ version endpoints)
• publish — Publish a server
• admin — Admin-only edit and status operations

Client

import { MCPRegistryClient } from "mcp-registry-spec-sdk";

const client = new MCPRegistryClient(); // default: official registry, v0.1

// Custom base URL
const custom = new MCPRegistryClient("https://my-registry.example.com");

// Set or clear a default token used by publish/admin
client.setAuthToken("YOUR_REGISTRY_JWT"); // omit or pass undefined to clear

Servers

List servers with optional pagination and filters:

const response = await client.server.listServers({
  cursor: "opaque-cursor",   // optional
  limit: 20,                 // optional
  search: "my query",        // optional
  updatedSince: "2024-01-01T00:00:00Z", // optional (ISO-8601)
  version: "1.0.0",          // optional
  includeDeleted: true,      // optional — include deleted servers
});
// response.servers: ServerResponse[] | null
// response.metadata: { count: number, nextCursor?: string }

When updatedSince is present, the Registry always includes deleted records. Passing includeDeleted: false with updatedSince is invalid and the SDK rejects it before sending a request. Limits must be integers from 1 through 100.

Get a specific server version:

const latest = await client.server.getServerVersion("org/server-name", "latest");
const specific = await client.server.getServerVersion("org/server-name", "1.2.3");

// With include_deleted
const deleted = await client.server.getServerVersion("org/server-name", "1.0.0", {
  includeDeleted: true,
});

List all versions for a server:

const versions = await client.server.listServerVersions("org/server-name");
// Also supports { includeDeleted: true }

Publish

Publish or update a server entry. Requires a registry token (JWT).

import type { ServerJSON } from "mcp-registry-spec-sdk";

const serverPayload: ServerJSON = {
  $schema: "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  name: "org/my-server",
  description: "My MCP server",
  version: "1.0.0",
};

// Uses default token set via client.setAuthToken()
const published = await client.publish.publishServer(serverPayload);

// Or pass token per call
const published2 = await client.publish.publishServer(serverPayload, "my-jwt-token");

Admin

Edit and update the status of server versions. All require a registry token. The optional generic-registry DELETE endpoint is not exposed because the official Registry does not implement it.

// Edit a server version
const edited = await client.admin.editServerVersion(
  "org/server-name", "1.0.0",
  {
    $schema: "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
    name: "org/server-name",
    description: "Updated",
    version: "1.0.0",
  },
);

// Update status of a single version
const updated = await client.admin.updateVersionStatus(
  "org/server-name", "1.0.0",
  { status: "deprecated", statusMessage: "Use v2 instead" },
);

// Update status of ALL versions
const allUpdated = await client.admin.updateAllVersionsStatus(
  "org/server-name",
  { status: "deprecated", statusMessage: "Project archived" },
);
// allUpdated: { updatedCount: number, servers: ServerResponse[] }

Auth (token exchange)

Exchange third-party tokens/signatures for a registry JWT.

// GitHub OAuth access token -> Registry JWT
const jwt1 = await client.auth.exchangeGitHubOAuthAccessTokenForRegistryJWT({
  github_token: "gho_xxx",
});

// GitHub OIDC token -> Registry JWT
const jwt2 = await client.auth.exchangeGitHubOIDCTokenForRegistryJWT({
  oidc_token: "gh-oidc-xxx",
});

// Configured OIDC provider -> Registry JWT. This endpoint is deployment-dependent
// and is primarily used for official Registry administration.
const jwt3 = await client.auth.exchangeOIDCIDTokenForRegistryJWT({
  oidc_token: "oidc-xxx",
});

// HTTP signature -> Registry JWT
const jwt4 = await client.auth.exchangeHTTPSignatureForRegistryJWT({
  domain: "yourdomain.com",
  signed_timestamp: "abcdef1234567890", // hex-encoded signature
  timestamp: new Date().toISOString(),
});…