Metadata-Version: 2.4
Name: mcptrail
Version: 0.1.1
Summary: Python SDK for the MCP Trail management API (/api/v1).
License: MIT
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# mcptrail (Python SDK)

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

## Install

```bash
pip install mcptrail
```

## Usage

```python
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)

```python
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`](../sdk-ts) and is generated against
[`openapi/mcptrail.yaml`](../../openapi/mcptrail.yaml).
