mcptrail 0.2.0

Python SDK for the MCP Trail management API (/api/v1).

mcptrail (Python SDK)

Python SDK for the MCP Trail management API (/api/v1) — govern guardian servers and policies as code. Runtime-dependency-free (stdlib only).

Install

pip install mcptrail

Usage

from mcptrail import McpTrailClient, McpProxyClient

# Token resolution: explicit token=... -> MCPTRAIL_TOKEN env.
# base_url defaults to the cloud; set it when self-hosting.
client = McpTrailClient(token="mg_mgmt_...")

# Provision a server (bearer token is returned ONCE)
created = client.servers.create(
    display_name="GitHub",
    slug="github",
    upstream_mcp_url="https://api.githubcopilot.com/mcp",
)

# Policy as code
client.servers.set_tool_policy("github", "delete_repository", "hitl")
client.servers.set_dlp_mode("github", "block")

# Read audit, resolve approvals
page = client.audit.list(scope="github", limit=100)
for pending in client.hitl.list():
    client.hitl.resolve(pending.id, "approve")

Calling a guarded tool (data plane)

proxy = McpProxyClient(slug="github", token="mg_live_...")  # per-server token
result = proxy.call_tool("get_issue", {"number": 42})

Tokens

• Servers / CI: mint a scoped management API key in the dashboard (/dashboard/api-keys); pass as token= or MCPTRAIL_TOKEN. Data-plane calls use the per-server token (MCPTRAIL_PROXY_TOKEN).
• Errors raise McpTrailApiError (status/code) or, for the proxy, McpProxyError (JSON-RPC code).

Mirrors @mcptrail/sdk and is generated against openapi/mcptrail.yaml.