Zero Context Protocol Python SDK

zero-context-protocol-python is the reference Python SDK and runtime for Zero Context Protocol (ZCP).

It serves two goals at the same time:

• provide a native ZCP runtime that can optimize tool exposure, routing, and token usage for agent workflows
• remain compatible with MCP-facing integrations through stdio, streamable HTTP, and WebSocket surfaces

The public Python surface remains:

• distribution name: zero-context-protocol-sdk
• import path: import zcp

The companion protocol and documentation repository lives in zero-context-protocol.

What This Repository Owns

• src/zcp: official SDK, runtime, transports, gateway, auth, and profiles
• examples: public examples, migration paths, and benchmark entrypoints
• tests: SDK, MCP compatibility, transport, and benchmark regression coverage
• tools: local benchmark harnesses and benchmark suites
• benchmark_reports: published benchmark artifacts

Why ZCP Instead Of Plain MCP

ZCP keeps the MCP compatibility surface, but adds native runtime affordances for model-facing efficiency:

• handle-first results and compact tool output shaping
• semantic workflow profiles for native tool discovery
• staged tool exposure for complex workflows
• task-aware runtime behavior
• benchmark-backed token reductions in real LLM scenarios

The latest published Excel benchmark lives in benchmark_reports/full_semantic_compare_v5. Current headline result:

• overall native ZCP vs MCP surface: 8027.9 vs 30723.7 total tokens
• overall advantage: 3.83x

Install

From PyPI:

pip install zero-context-protocol-sdk

With optional extras:

pip install "zero-context-protocol-sdk[openai,mcp]"

For local development from source:

pip install -e ".[dev,openai,mcp]"

Python 3.10+ is required.

3-Minute Quickstart

Run a minimal MCP-compatible stdio server:

python3 examples/run_zcp_mcp_stdio_server.py

Run an ASGI service exposing native and MCP-compatible surfaces:

python3 examples/run_zcp_api_server.py

Run the smallest native ZCP example:

python3 examples/zcp_weather_server.py

List native semantic workflow tools from a client:

from zcp import SemanticWorkflowProfile

profile = SemanticWorkflowProfile()
tools = await client.list_tools(**profile.as_list_tools_params())

Stable, Beta, Experimental

Stable

• tools
• resources and resource templates
• prompts
• completion/complete
• MCP-compatible stdio
• MCP-compatible HTTP at /mcp
• native ZCP tool transport helpers
• bearer auth metadata and server wiring
• tool profiles and semantic workflow discovery

Beta

• streamable HTTP resume/replay behavior
• WebSocket transport
• OAuth provider integration
• task-oriented tool execution

Experimental

• advanced sampling / elicitation orchestration
• benchmark-specific semantic workflow adapters outside the public examples

Repository Layout

• SDK/runtime: src/zcp
• examples: examples/README.md
• tests: tests
• benchmark reproduction: benchmark_reports/README.md

Validation

Fast local validation:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest -q

The current repo subset used for release-focused validation includes transport, SDK, gateway, and benchmark regression coverage.

Benchmarks

Primary public benchmark entrypoints:

• compact tool-call benchmark: examples/compare_zcp_mcp_tool_call_benchmark.py
• Excel LLM token benchmark: examples/compare_excel_client_protocol_benchmark.py

Public benchmark guidance and official artifact selection:

• benchmark_reports/README.md

Security Note

Benchmark and provider-backed examples require environment variables. Do not commit API keys. Use .env.example as the reference shape.

License

Apache-2.0. See LICENSE.