Metadata-Version: 2.4
Name: mcpzero-sdk
Version: 0.1.1
Summary: MCPZERO SDK: expose your MCP server through the MCPZERO tunnel
Author: MCPZERO
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: anyio>=4.0.0; extra == 'mcp'
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# mcpzero (Python)

Python SDK for MCPZERO (open source, MIT). Expose your own MCP server through the
MCPZERO tunnel — a public Streamable-HTTP endpoint plus full dashboard visibility
— directly from code, without the CLI.

```bash
pip install mcpzero-sdk          # embedded proxy only
pip install "mcpzero[mcp]"   # + in-process adapter for the official MCP SDK
```

Create an endpoint and a **management key** in the [dashboard](https://mcpzero.io).
A management key is a user-level credential that lets the SDK publish (register a
tunnel for) any endpoint you own — the headless alternative to `mcpzero login`.
By convention they are read from `MCPZERO_ENDPOINT_ID` / `MCPZERO_MGMT_KEY`
(gateway base from `MCPZERO_GW_BASE`, default `https://gw.mcpzero.io`).

> Not to be confused with an **API key**, which is the consumer-side credential
> AI clients use to *call* your published endpoint.

## Tunnel an in-process MCP server (primary API)

Run your official `mcp` SDK server with its streams backed by the tunnel:

```python
import asyncio
import mcpzero
from mcp.server.lowlevel import Server

server = Server("my-mcp")
# ... @server.list_tools() / @server.call_tool() ...

asyncio.run(mcpzero.serve(server, endpoint_id="ep_...", management_key="mzm_..."))
```

Or drive the streams yourself:

```python
async with mcpzero.tunnel(endpoint_id="ep_...", management_key="mzm_...") as (read, write):
    await server.run(read, write, server.create_initialization_options())
```

## Tunnel a local MCP server (lower-level primitive)

A library version of `mcpzero tunnel`, for a server running as a separate
process or HTTP service:

```python
# stdio:
handle = await mcpzero.tunnel_proxy(command=["python", "server.py"])
# or HTTP:
handle = await mcpzero.tunnel_proxy(url="http://localhost:3000/mcp")

print("Live at", handle.endpoint_url)
# ... later:
await handle.aclose()
```

## Visibility

In tunnel mode, visibility is produced by the gateway automatically — the
dashboard reflects calls exactly as it does for the CLI tunnel. No extra code is
needed.

See [`../PROTOCOL.md`](../PROTOCOL.md) for the tunnel wire protocol.

Docs: https://mcpzero.io/docs/sdk/tunnel/python
