utcp

go-utcp

go-utcp is a Go client for the Universal Tool Calling Protocol (UTCP). It discovers tools from configured providers, keeps their metadata in a local repository, and exposes one API for searching, calling, and streaming tool results across different transports.

Features

• One client API for tool discovery, invocation, and streaming.
• Provider configuration through JSON or Go values.
• Built-in HTTP, CLI, SSE, streamable HTTP, WebSocket, gRPC, GraphQL, TCP, UDP, WebRTC, MCP, and local text transports.
• OpenAPI discovery for HTTP providers.
• Runtime provider registration and deregistration.
• $VAR and ${VAR} substitution from explicit values, .env files, or the process environment.
• An in-memory tool repository, with interfaces for custom repositories and search strategies.
• CodeMode for composing several tool calls with a small Go-like program.

Requirements

• Go 1.25 or newer

Install

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

Quick start

Create providers.json with a local text-template provider. This transport needs no external service:

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

Load the provider, inspect its tools, and call greetings.hello:

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)
}

go run .

Tools are qualified as <provider>.<tool>, which prevents collisions when several providers expose the same tool name.

Configure providers

ProvidersFilePath accepts any of these JSON root shapes:

• An array of provider objects.
• A single provider object.
• An object with a providers array or object.

Every provider needs a provider_type. The built-in values are:

Provider-specific fields and complete client/server pairs are available in examples/.

Variables and secrets

Provider strings can reference $NAME or ${NAME}. Values are resolved in this order:

1. UtcpClientConfig.Variables
2. Entries in UtcpClientConfig.LoadVariablesFrom
3. Process environment variables

For example:

cfg := &utcp.UtcpClientConfig{
	ProvidersFilePath: "providers.json",
	Variables: map[string]string{
		"API_HOST": "api.example.com",
	},
	LoadVariablesFrom: []utcp.UtcpVariablesConfig{
		utcp.NewDotEnv(".env"),
	},
}

{
  "provider_type": "http",
  "name": "catalog",
  "http_method": "POST",
  "url": "https://${API_HOST}/tools",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

Keep secrets outside committed provider files.

Client API

Pass an empty prefix to SearchTools to list every registered tool, or pass a provider name to restrict the result to that provider.

Stream results

Streaming calls return a StreamResult. Read until io.EOF and always close the stream:

stream, err := client.CallToolStream(ctx, "events.watch", args)
if err != nil {
	log.Fatal(err)
}
defer stream.Close()

for {
	item, err := stream.Next()
	if errors.Is(err, io.EOF) {
		break
	}
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(item)
}

Streaming support depends on the selected transport and tool.

CodeMode

CodeMode executes a constrained Go-like snippet with helpers for calling registered UTCP tools. It is useful for loops, branching, multi-tool composition, and processing intermediate results without serializing every step as a separate tool request.

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

cm := codemode.NewCodeModeUTCP(client, nil)
result, err := cm.Execute(ctx, codemode.CodeModeArgs{
	Code: `
		value, err := codemode.CallTool("greetings.hello", map[string]any{
			"name": "CodeMode",
		})
		if err != nil {
			__out = err
			return
		}
		__out = value
	`,
	Timeout: 5_000,
})

Snippets can use codemode.CallTool, codemode.CallToolStream, and codemode.SearchTools. CodeModeResult contains the resulting value plus captured standard output and standard error.

Examples

The examples directory contains standalone modules for each client and transport. Run an example from its directory with workspace mode disabled so that Go uses the example's own module:

cd examples/text_client
GOWORK=off go run -mod=mod .

Some network examples start an in-process demo server; others require the matching transport example or another local dependency. See the source in each directory for its setup.

Development

git clone https://github.com/universal-tool-calling-protocol/go-utcp.git
cd go-utcp
go test ./...

New contributors can also follow onboarding.md.

License

This project is licensed under the Mozilla Public License 2.0.