go-utcp

go-utcp is the Go implementation of the Universal Tool Calling Protocol (UTCP). It provides a single client-side abstraction for discovering, describing, searching, invoking, and streaming tools exposed through heterogeneous providers and transports.

The project is designed for applications that need to connect an agent, service, workflow engine, or automation runtime to many kinds of tools without coupling application logic to every transport individually.

Table of contents

• What is UTCP?
• Why go-utcp?
• Core concepts
• Features
• Requirements
• Installation
• Quick start
• Architecture
• Providers
• Provider configuration
• Variables and secrets
• Tool discovery
• Searching tools
• Calling tools
• Streaming
• Dynamic provider registration
• Transport matrix
• HTTP
• OpenAPI
• CLI
• SSE
• Streamable HTTP
• WebSocket
• gRPC
• GraphQL
• TCP
• UDP
• WebRTC
• MCP
• Text providers
• CodeMode
• Security
• Error handling
• Context cancellation
• Testing
• Examples
• Development
• Project layout
• Performance
• Troubleshooting
• FAQ
• Contributing
• License

What is UTCP?

UTCP is a protocol and architectural approach for exposing tools to software that needs to call them. A tool has metadata describing what it does, how it should be called, and which provider exposes it. A client can discover that metadata and invoke the tool without needing to implement provider-specific business logic at every call site.

The important idea is separation of concerns:

1. Providers expose capabilities.
2. The UTCP client discovers those capabilities.
3. A local repository stores tool metadata.
4. Search selects relevant tools.
5. The client dispatches calls to the appropriate transport.
6. The provider performs the operation.
7. Results are returned through one Go API.

This makes UTCP useful as infrastructure for AI agents, automation platforms, developer tools, integration services, and ordinary backend applications.

Why go-utcp?

A typical integration layer accumulates one SDK per remote system. An application may need separate code for HTTP APIs, CLIs, gRPC services, GraphQL APIs, WebSockets, MCP servers, and local utilities. go-utcp provides a common abstraction above those transports.

Instead of writing application logic such as:

if provider is HTTP -> use HTTP client
if provider is gRPC -> use gRPC client
if provider is MCP -> use MCP SDK
if provider is CLI -> start process

your application can work with:

result, err := client.CallTool(ctx, "provider.tool", args)

The transport-specific behavior stays below the tool-calling API.

Core concepts

Provider

A provider is a configured source of one or more tools. It contains enough metadata for go-utcp to discover and invoke those tools.

Tool

A tool is a callable capability. It has a name, description, input metadata, and provider association.

Tool repository

The repository stores discovered tool metadata. The default implementation is in memory, while interfaces allow applications to provide custom storage or search implementations.

Transport

A transport knows how to communicate with a provider. HTTP, gRPC, MCP, CLI, WebSocket, and other transports can implement the same higher-level tool invocation model.

Search

Search selects tools from the local repository. Applications can use provider-scoped lookup or broader search strategies.

CodeMode

CodeMode lets a constrained Go-like program compose multiple tool calls in one execution. This is useful when an agent needs loops, branching, transformation, or multi-step orchestration.

Features

• Unified discovery API.
• Unified tool invocation API.
• Streaming tool invocation.
• Provider registration and deregistration.
• Provider-scoped tool names.
• In-memory tool repository.
• Pluggable repository and search abstractions.
• HTTP and OpenAPI support.
• CLI process providers.
• Server-Sent Events.
• Streamable HTTP.
• WebSocket.
• gRPC and gNMI support.
• GraphQL queries and subscriptions.
• TCP and UDP transports.
• WebRTC data-channel transport.
• MCP over supported MCP transports.
• Local text-template providers.
• Environment variable substitution.
• .env loading.
• Runtime variables.
• CodeMode tool composition.
• Streaming result handling.
• Context-aware calls.
• Standalone examples.
• Go-native APIs.

Requirements

• Go 1.25 or newer.
• Network access for network-backed providers.
• Provider-specific runtime dependencies where applicable.

Check the module and examples for transport-specific requirements before deploying a particular provider.

Installation

Install the library with:

go get github.com/universal-tool-calling-protocol/go-utcp@latest

Then import it from Go:

import utcp "github.com/universal-tool-calling-protocol/go-utcp"

CodeMode is available under its plugin package:

import "github.com/universal-tool-calling-protocol/go-utcp/src/plugins/codemode"

Quick start

The smallest useful example can use a local text provider, so no external server is required.

Create providers.json:

{
  "providers": [
    {
      "provider_type": "text",
      "name": "greetings",
      "templates": {
        "hello": "Hello, {{.name}}!"
      }
    }
  ]
}

Create a Go program:

package main

import (
    "context"
    "fmt"
    "log"

    utcp "github.com/universal-tool-calling-protocol/go-utcp"
)

func main() {
    ctx := context.Background()

    client, err := utcp.NewUTCPClient(ctx, &utcp.UtcpClientConfig{
        ProvidersFilePath: "providers.json",
    }, nil, nil)
    if err != nil {
        log.Fatal(err)
    }

    tools, err := client.SearchTools("", 10)
    if err != nil {
        log.Fatal(err)
    }

    for _, tool := range tools {
        fmt.Printf("%s: %s\n", tool.Name, tool.Description)
    }

    result, err := client.CallTool(ctx, "greetings.hello", map[string]any{
        "name": "UTCP",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result)
}

Run it with:

go run .

The important detail is the qualified tool name:

<provider>.<tool>

For the example above:

greetings.hello

Provider qualification prevents ambiguous tool names when several providers expose tools with the same local name.

Architecture

At a high level, go-utcp follows this flow:

                  Provider configuration
                           |
                           v
                    Provider loader
                           |
                           v
                  Provider registration
                           |
                           v
                    Tool discovery
                           |
                           v
                    Tool repository
                           |
                 +---------+---------+
                 |                   |
                 v                   v
              Search              Lookup
                 |                   |
                 +---------+---------+
                           |
                           v
                      Tool call
                           |
                           v
                    Transport layer
                           |
                           v
                        Provider

The application normally interacts with the client rather than directly with individual transport implementations.

Discovery phase

During provider registration, the client asks a provider to expose its tool metadata. The metadata is stored in the configured repository.

Selection phase

An application or agent searches the repository to identify a tool. The search result gives the caller enough information to decide which tool to invoke.

Invocation phase

The client resolves the qualified tool name, finds the associated provider and transport, validates the call path, and dispatches the invocation.

Streaming phase

When a tool supports streaming, CallToolStream exposes a StreamResult. Consumers can incrementally read values until the stream reaches io.EOF or another error.

Providers

Providers are the central configuration unit in go-utcp. A provider normally contains:

• A provider type.
• A unique provider name.
• Transport-specific configuration.
• Endpoint or command information where required.
• Optional headers or credentials.
• Tool discovery metadata.
• Provider-specific options.

Provider names should be stable, descriptive, and unique within a client configuration.

Good names include:

billing
catalog
github
internal-search
weather
payments

Avoid names that expose credentials or unstable