@mcptrail/sdk

TypeScript SDK for the MCP Trail management API (/api/v1) — govern guardian servers and policies as code.

Install

npm install @mcptrail/sdk

Usage

import { McpTrailClient } from "@mcptrail/sdk";

// Token resolution: explicit option → MCPTRAIL_TOKEN env var.
// baseUrl defaults to the cloud; set it when self-hosting.
const client = new McpTrailClient({
  token: process.env.MCPTRAIL_TOKEN,
  // baseUrl: "https://guardian.mycorp.internal",
});

// Provision a server (returns its proxy bearer token ONCE)
const created = await client.servers.create({
  displayName: "GitHub",
  slug: "github",
  upstreamMcpUrl: "https://api.githubcopilot.com/mcp",
});

// Policy as code
await client.servers.setToolPolicy("github", "delete_repository", "hitl");
await client.servers.setDlpMode("github", "block");

// Read audit, resolve approvals
const page = await client.audit.list({ scope: "github", limit: 100 });
for (const pending of await client.hitl.list()) {
  await client.hitl.resolve(pending.id, "approve");
}

Auth tokens

• Servers / CI: mint a scoped management API key in the dashboard (/dashboard/api-keys) and pass it as token or MCPTRAIL_TOKEN.
• Local dev: mcptrail login (browser) caches a token the CLI uses; pass it explicitly to the SDK if you want the same identity.

Errors surface as McpTrailApiError carrying status, code, and message.

API surface

client.servers (list/get/create/update, listTools/setToolPolicy, getDlpMode/setDlpMode) · client.audit.list · client.hitl (list/resolve) · client.bundles (list/create) · client.dlpRules (list/create/delete).

Generated against openapi/mcptrail.yaml — the source of truth.