DOCSEARCHbyAlgolia
Submit Docs

Universal Tool Calling Protocol

repository·main·Indexed 43 days ago

https://github.com/universal-tool-calling-protocol/utcp-specification

A standardized specification for tool discovery and execution that allows AI clients to interact with tools across diverse transport layers—including HTTP, WebSockets, CLI, gRPC, and GraphQL—via a unified interface. UTCP utilizes a 'Manual' philosophy where tool providers publish a JSON-based UTCPManual to define tool purposes, input/output schemas, and transport mechanisms, enabling direct communication to eliminate proxy latency.

Tokens
65.3K
Snippets
209
Records
308
Agent score
55%

What's inside UTCP

  1. Overview of UTCP API Architecture

    main

    The Universal Tool Calling Protocol (UTCP) API is organized into two primary categories: Core Modules and Plugin Modules.

    • Core Modules: Define the fundamental interfaces, data structures, and implementations required for any UTCP-compliant client. This includes authentication (utcp.data.auth), tool definitions (utcp.data.tool), client configuration (utcp.data.utcp_client_config), and core interfaces like communication protocols and serializers.
    • Plugin Modules: Provide specific implementations of transport protocols. These extend the core functionality to support various communication methods such as CLI, File, HTTP (including SSE and Streamable HTTP), MCP, Socket (TCP/UDP), Text, and WebSocket.

    To be considered a UTCP-compliant client, an implementation must provide all the classes, functions, and fields described in the specification, though the internal organization may differ from the reference Python implementation.

  3. What is UTCP?

    main

    The Universal Tool Calling Protocol (UTCP) is a standardized specification for defining and interacting with tools across various communication protocols (e.g., HTTP, WebSocket, CLI). It enables AI systems and clients to discover and call tools from different providers in a scalable and flexible manner.

    Key components defined by the specification include:

    • Tool discovery mechanisms
    • Tool call formats and templates
    • A plugin-based architecture for extensibility
    • Enhanced authentication methods (API key, OAuth, custom auth)
    • Comprehensive error handling and response validation

  4. What is UTCP and how does it differ from MCP?

    main

    The Universal Tool Calling Protocol (UTCP) is a standard for defining and interacting with tools across various communication protocols. Unlike the Model Context Protocol (MCP), which uses a proxy-based architecture, UTCP enables direct tool calls to eliminate latency.

    Key advantages include:

    • Zero Latency Overhead: Direct communication between AI agents and tools without intermediary layers.
    • Enhanced Security: Built-in authentication mechanisms and direct protocol support.
    • Protocol Flexibility: Supports HTTP/HTTPS, GraphQL, gRPC, WebSockets, CLI interfaces, and custom protocols.

  5. What is a UTCP Manual?

    main

    A UTCP manual is a JSON document that describes available tools and how to call them. It serves as the source of truth for tool providers. A manual must include:

    1. Info Section: Metadata about the API (title, version, description).
    2. Tools Array: A list of available tools, each defining its name, description, inputs (JSON Schema), and outputs (JSON Schema).
    3. Call Templates: Instructions on how to invoke each tool using specific protocols (e.g., http or cli).
    {
  "manual_version": "1.0.0",
  "utcp_version": "1.0.1",
  "info": {
    "title": "API Name",
    "version": "1.0.0",
    "description": "API description"
  },
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "inputs": {
        "type": "object",
        "properties": {
          "param": {"type": "string"}
        }
      },
      "outputs": {
        "type": "object",
        "properties": {
          "result": {"type": "string"}
        }
      },
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/endpoint",
        "http_method": "POST"
      }
    }
  ]
}

  7. Note on streaming with McpCommunicationProtocol

    main

    Streaming calls are not supported by the MCP protocol implementation. When calling call_tool_streaming, the protocol will execute the tool call and return the full result as a single item within the async generator.

    async call_tool_streaming(
    self, 
    caller: UtcpClient, 
    tool_name: str, 
    tool_args: Dict[str, Any], 
    tool_call_template: CallTemplate
) -> AsyncGenerator[Any, None]

  9. Choose between UTCP and MCP

    main

    Both protocols solve tool integration, but they serve different architectural needs.

    Use UTCP when:

    • You want to leverage existing APIs without adding extra infrastructure.
    • You need support for multiple communication protocols (HTTP, WebSocket, SSE, etc.).
    • You prioritize performance and direct communication.
    • You have limited resources for server maintenance.
    • You want rapid deployment and minimal complexity.

    Use MCP when:

    • You need strict protocol standardization.
    • You are building a controlled ecosystem.
    • You have dedicated resources for managing server infrastructure.
    • You need MCP-specific features beyond basic tool calling.
    • You prefer centralized tool management.

  10. Security rules for HTTP connections

    main

    To prevent man-in-the-middle attacks, the protocol enforces strict connection rules:

    • HTTPS Enforcement: Only https:// URLs are allowed.
    • Loopback Exception: Plain http:// is permitted only for literal loopback addresses (e.g., localhost, 127.0.0.1, ::1).
    • Redirect Security: Every redirect hop is re-validated against the HTTPS/loopback rules. Credentials are never forwarded across different origins.
    • Path Injection Prevention: URL path parameters are automatically URL-encoded.

  11. Handle Streamed HTTP Responses by Content-Type

    main

    The protocol automatically determines how to process the incoming stream based on the response's Content-Type header:

    • application/x-ndjson: Parsed as Newline Delimited JSON. Each line is yielded as a separate JSON object.
    • application/octet-stream: Yielded in binary chunks of the specified chunk_size.
    • application/json: The entire response is buffered and yielded as a single JSON object (used for large single JSON documents).
    • Other Types: Treated as a binary stream and yielded in chunks of chunk_size.

  12. Configure Command Line Interface (CLI) tool providers with CliCallTemplate

    main

    The CliCallTemplate class is used to define how command-line tools and programs are executed as UTCP tool providers. Commands are executed within a single subprocess, allowing state (such as directory changes via cd) to persist between steps.

    Key Features

    • Cross-Platform Scripting: Automatically converts commands to PowerShell on Windows and Bash on Unix/Linux/macOS.
    • Argument Substitution: Uses UTCP_ARG_argname_UTCP_END placeholders. These are injected via environment variables to prevent command injection.
    • Output Referencing: Access the output of previous commands using $CMD_N_OUTPUT (where N is the zero-based index of the command).
    • Environment Control: Manage host environment variables via inherit_env_vars and custom variables via env_vars.

    Security Note

    tool_args values are never inlined into the command text. They are passed via per-invocation environment variables, meaning the shell expands them after parsing, preventing attackers from escaping quoting contexts. However, you must never assemble the command template itself from untrusted input.

    {
  "name": "python_multi_step_tool",
  "call_template_type": "cli",
  "commands": [
    {
      "command": "python setup.py install",
      "append_to_final_output": false
    },
    {
      "command": "python script.py --input UTCP_ARG_input_file_UTCP_END --result "$CMD_0_OUTPUT""
    }
  ],
  "env_vars": {
    "PYTHONPATH": "/custom/path",
    "API_KEY": "${API_KEY_VAR}"
  },
  "inherit_env_vars": ["OPENAI_API_KEY", "AWS_PROFILE"]
}