Model or dataset
universal-tool-calling-protocol/python-utcp avatar
universal-tool-calling-protocol/python-utcp

python-utcp: two registries decide who owns a protocol's state

Official python implementation of UTCP. UTCP is an open standard that lets AI agents call any API directly, without extra middleware.

672 stars58 forksPythonMPL-2.0

At a glance

What is it?
UTCP is an open standard for letting agents call tools across many kinds of transport, and this is its official Python implementation under a modular core with per-protocol plugins. The part worth reading is the lifetime rule: a plugin registers either a shared instance or a factory, and that single choice decides whether its sessions belong to the process or to the client that opened them.
Who is it for?
python-utcp is worth reading if you are implementing the Python side of a tool protocol, because the shared-instance versus factory rule is the part every plugin framework eventually gets wrong, and this one names it, defaults the shipped plugins sensibly, and migrates existing plugins without changing callers. Three cautions.
Can I use it commercially?
Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Yes. The repository last received commits 21 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • universal-tool-calling-protocol/python-utcp672 ★ · +23
Star history
Repository2026-09-122026-11-15
universal-tool-calling-protocol/python-utcp649672

23 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two registries decide who owns a protocol's state

A protocol plugin registers itself in one of two registries, and the documentation is unusually clear that the choice decides ownership rather than configuration. Register an instance and it is shared by every client in the process, along with any state it keeps. That is correct for state that is meant to be shared, such as a credential cache or a registry a decorator writes into, and wrong for state that belongs to one client. A shared instance lives as long as the process and no client closes it. Register a factory instead when the state must not be shared: live sessions or connections keyed per manual, child processes, anything that one client's use or its teardown would take away from another. Each client then calls the factory once, at creation or on first use if the plugin was registered later, and gets its own instance, its own connections and its own teardown. This is what makes one client per tenant actually isolate tenants.

Sessions belong to the client that opened them

The shipped plugins are split by that rule, and the split is the interesting part of the design. The protocol plugin and the WebSocket plugin register as factories, because their state is exactly the kind that must not be shared: sessions, and for the standard-output transport the child processes themselves, plus WebSocket connections keyed per manual. Those belong to the client that opened them, and no other client should inherit them. The HTTP plugin and the GraphQL plugin stay shared instances, and the reason given is that the only state they keep is an OAuth token cache, which is meant to be reused across clients, and because every request opens its own session. A type registered as a factory wins over the same type registered as an instance, so a plugin that needs to change its mind migrates by moving its registration from one call to the other and callers change nothing at all. That is a well-chosen migration story for a plugin ecosystem.

Teardown closes everything the client created, even when one fails

Two failure paths are specified, and both are the kind most documentation leaves out. When a client is closed, it closes every instance that client created, and it does so even if one of those closes fails; only afterwards are the failures raised together as a single aggregated close error. So one misbehaving plugin cannot strand the connections the other plugins opened, and you still learn about all of them at once rather than one per run. The second path is the creation failure. If client creation fails after some protocol instances have already been made, those instances are closed the same way before the original error is re-raised. That ordering matters: without it, a failed startup would leak exactly the connections the plugin architecture was designed to bound. Together with the factory rule, it means the lifetime story is specified at four points, at registration, at creation, at first use, and at close, which is more than most plugin systems attempt.

A tool is a dotted name over a typed call template

The usage is short enough to read as the whole data model. A client is created with a configuration carrying a list of manual call templates, each one a name, a type and an endpoint:

python
from utcp.utcp_client import UtcpClient

# Create client with HTTP API
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "my_api",
        "call_template_type": "http",
        "url": "https://api.example.com/utcp"
    }]
})

# Call a tool
result = await client.call_tool("my_api.get_data", {"id": "123"})

# Release the connections this client opened
await client.close()

Calling is then a two-part address, a manual name and a tool name joined by a dot, with the arguments as a mapping. The templates are data rather than code, which is what lets the same client reach several services, and the type field selects which protocol plugin handles the call. The last line is the one most examples omit: closing the client, which releases the connections it opened. Given the lifetime rules, that call is not housekeeping. It is the only thing that tears down the factory-made instances, so skipping it means the process holds them until it exits.

Five stable transports and two unfinished ones

The plugin table carries a status column, and reading it is how you know what you can depend on today. HTTP with server-sent events and streaming is stable, as are the command line plugin, the protocol plugin, the text plugin for local file-based tools, and the WebSocket plugin for real-time bidirectional work. Two are unfinished: raw TCP and UDP sockets, and GraphQL. So the transports actually usable in production today are five, spanning request-response, streaming, subprocess, local files and bidirectional sockets, which is a wide base for an agent tool layer. The unfinished two are the ones you would reach for when a service speaks a non-HTTP protocol, so the gap is exactly where the abstraction is thinnest. The documentation also marks the raw socket plugin as in progress in the structure section above the table, which is consistent, and that section omits the WebSocket plugin entirely while the table and the lifetime discussion both include it.

Each transport ships as its own package

Installation is by package name, one per transport, which keeps the dependency surface honest:

bash
# Install core + HTTP plugin (most common)
pip install utcp utcp-http

# Install additional plugins as needed
pip install utcp-cli utcp-mcp utcp-text

The comment marks the core plus HTTP as the common case, and the second line takes the rest. The consequence is that your dependency list tells a reader exactly which transports you support, which is more informative than a single package with everything bundled, and it means the standard input-output child processes and WebSocket machinery only enter your environment if you asked for them. The cost is that a protocol upgrade and a core upgrade are separate events, so a mismatch between your core version and a plugin version is a state you can end up in. Nothing in the documentation describes a compatibility range between the packages, which is the piece a production operator would want.

The core is four models and three extension points

The core package is small by design and its contents are named. Four Pydantic models carry the data: a tool, a call template, a manual, and an authentication object. One client class is the interface for tool interaction. The plugin system defines the extension points, and there are three kinds: communication protocols, tool repositories, and search strategies, each with a built-in default implementation. That three-way split is what makes the extensibility claim concrete rather than rhetorical, since the architecture can add a transport, a different place to store tool definitions, and a different search algorithm without touching the core library. The four emphases the standard states map onto that structure: scalability and interoperability are properties of the plugin boundary, extensibility is the three extension points, and ease of use is the four models being plain validated objects. Nothing in the core needs a language model to describe a tool, which is the structural difference from approaches that require one.

A standard and an implementation, released separately

Two things about this repository's shape matter for anyone pinning a version. It lives under an organisation named for the standard rather than for the implementation, and the package description calls it the official Python implementation of an open standard, with the standard's own site at a different address from this repository. So the specification and the code have separate homes and separate version lines. The repository itself publishes no releases at all, so the only versions that exist for the Python packages come from the package index rather than from tags here. The licence is the weak copyleft variant of the Mozilla licence, which is a reasonable choice for a protocol implementation: it allows linking into larger proprietary applications while requiring changes to this code to stay open. The last commit to the repository was in mid-September 2026, so the implementation is being worked on while the standard moves separately.

Editorial conclusion

python-utcp is worth reading if you are implementing the Python side of a tool protocol, because the shared-instance versus factory rule is the part every plugin framework eventually gets wrong, and this one names it, defaults the shipped plugins sensibly, and migrates existing plugins without changing callers. Three cautions. The standard itself is versioned separately from this repository, which publishes no releases, so pinning a Python package version does not pin the specification you are coding against. Two transports in the plugin table are unfinished, so verify the one you need rather than assuming symmetry. And the repository structure section lists fewer plugins than the status table, which is a small sign the documentation is maintained by hand.

Frequently asked questions

What is UTCP?

An open standard for defining and interacting with tools across many communication protocols, so an agent can call a service directly without extra middleware. This repository is its official Python implementation, with a modular core and one plugin per transport.

What is the alternative to MCP in the UTCP python implementation?

UTCP is positioned as the alternative, and it reaches further: the shipped plugins cover HTTP and streaming, command line tools, the Model Context Protocol itself, local file-based tools and WebSockets, plus unfinished raw socket and GraphQL transports.

How does a python-utcp plugin decide whether its state is shared?

By which registry it registers in. Registering an instance shares it across every client in the process, which suits an OAuth token cache. Registering a factory gives each client its own instance, connections and teardown, which suits sessions and child processes.

Which UTCP plugins are usable in production?

Five are marked stable: HTTP with server-sent events and streaming, command line, Model Context Protocol, local file-based tools, and WebSocket. Raw TCP and UDP sockets and GraphQL are marked in progress.

What happens when a python-utcp client is closed?

It closes every instance that client created, even if one of those closes fails, and then raises the failures together as a single aggregated error. If creation fails partway, the already-created instances are closed before the original error is re-raised.

How do I call a tool with python-utcp?

Create a client with a configuration listing manual call templates, each a name, a type and an endpoint, then call a tool by joining the manual name and the tool name with a dot and passing the arguments as a mapping. Close the client when you are done to release its connections.

Official sources

  1. Issues
  2. License: MPL-2.0
  3. Project website
  4. README
  5. universal-tool-calling-protocol/python-utcp on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/universal-tool-calling-protocol-python-utcp.svg)](https://hysenlabs.com/projects/universal-tool-calling-protocol-python-utcp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/universal-tool-calling-protocol-python-utcp.svg)](https://hysenlabs.com/projects/universal-tool-calling-protocol-python-utcp)

Was this useful?