Skip to main content

tesseron (Python)

The Python SDK lives at Eigenwise/tesseron-python. The Tesseron hub owns the protocol, docs, and issues.

The Python implementation of the Tesseron host protocol. Your application listens on loopback, the MCP gateway dials in, and the agent gets typed actions and readable resources instead of a scraper.

Speaks protocol 1.2.0. Compatibility is decided by protocol version, never by matching package numbers: see the compatibility contract.

Not on PyPI yet.

Install

uv add tesseron

Python 3.11 or newer. The only runtime dependencies are Pydantic v2 and websockets.

A first action

import asyncio

from pydantic import BaseModel, Field
from tesseron import ActionContext, TesseronApp

app = TesseronApp(id="todo", name="Todo", origin="http://127.0.0.1")


class AddTodo(BaseModel):
    text: str = Field(min_length=1)
    tag: str | None = None


@app.action("addTodo", description="Add one todo")
async def add_todo(input: AddTodo, context: ActionContext) -> dict[str, object]:
    await context.progress(percent=100, message="saved")
    return {"id": "1", "text": input.text, "done": False, "tag": input.tag}


async def main() -> None:
    host = await app.listen()
    print(host.url)
    await asyncio.Event().wait()


asyncio.run(main())

The input type comes from the handler annotation. Its validation-mode JSON Schema is what the manifest publishes, and model_validate is what rejects bad input with -32004 before the handler body runs.

What it covers

Handshake and claiming, session resume with in-memory token rotation, action invocation with validation, cancellation, timeouts, progress, sampling, confirmation, schema-checked elicitation, structured logs, and resources with reads, subscriptions, and pushes.

Gateway-minted claims only. WebSocket only: no Unix domain sockets and no host-minted bind in this release, so the conformance suite skips those fixtures honestly.

Examples

From the repo root, run the headless todo app with:

uv run --locked --directory sdks/python python -m examples.todo

Run the prompt library with:

uv run --locked --directory sdks/python python -m examples.prompts

Each prints a claim code after the gateway connects. In Claude Code with the Tesseron plugin loaded, ask Claude to claim that code, then call the actions. The todo app includes the canonical todos://all resource and the prompt app includes library and lastTest resources.

Validate both examples against the real gateway with pnpm example:python:e2e.

Development

Run everything from this directory:

uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run mypy --strict src tests
uv run pytest
uv build

The conformance host lives in conformance_host/, beside the package rather than inside it, so the published wheel carries the SDK and nothing else. See the conformance page for how the runner drives it.

Documentation

License

Tesseron is licensed under the Business Source License 1.1. Each release auto-converts to Apache-2.0, the Change License, four years after publication.

Metadata

Release files for tesseron 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tesseron 0.2.0
File Size Uploaded Provenance Actions
tesseron-0.2.0.tar.gz 41.0 kB With provenance Details for tesseron-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tesseron 0.2.0
File Interpreter ABI Platform Actions
tesseron-0.2.0-py3-none-any.whl Python 3 none any Details for tesseron-0.2.0-py3-none-any.whl

Total release size: 76.6 kB

Release files / tesseron-0.2.0.tar.gz

Download URL tesseron-0.2.0.tar.gz
Size 41.0 kB
Tags Source
SHA-256 checksum
How to use checksums
357514c36d1d041c01dd00bc3884bf347ed078c3097c91f1a724f1ddfd06328c
BLAKE2b-256 checksum
How to use checksums
3c2ec4c81d2eb6aa6fbb42d66c8d5a2357faeeaa5db95080c06dd14ec43a4c22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.

Transparency log

Release files / tesseron-0.2.0-py3-none-any.whl

Download URL tesseron-0.2.0-py3-none-any.whl
Size 35.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31b2efff6a1e25db337b7d1cca7db3158d46d6109c08d0cf9e7fe26db65ce7cd
BLAKE2b-256 checksum
How to use checksums
b0ca875e94a5d20999dd31883bace82ba82a139bc38603063b2e853c7d11d299
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.

Transparency log

Security for tesseron 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tesseron-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page