Version: 1.0

For Tool Providers

Language Note

This guide covers how to expose your existing APIs and services as UTCP tools. UTCP implementations are available in multiple languages - check the UTCP GitHub organization for Python, TypeScript, Go, and other language implementations.

This guide helps you expose your tools through UTCP so they can be discovered and used by AI agents and other applications.

Overview

As a tool provider, you'll create a UTCP Manual - a standardized description of your tools that tells clients how to call them directly using their native protocols. This eliminates the need for wrapper servers and allows direct communication.

Quick Start

1. Create a Simple Manual

{
  "manual_version": "1.0.0",
  "utcp_version": "1.0.1",
  "tools": [
    {
      "name": "get_user",
      "description": "Retrieve user information by ID",
      "inputs": {
        "type": "object",
        "properties": {
          "user_id": {"type": "string", "description": "User identifier"}
        },
        "required": ["user_id"]
      },
      "outputs": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "email": {"type": "string"}
        }
      },
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/users/{user_id}",
        "http_method": "GET"
      }
    }
  ]
}

2. Expose via Discovery Endpoint

Create an HTTP endpoint that returns your UTCP manual:

Endpoint: GET /utcp Response:

{
  "manual_version": "1.0.0",
  "utcp_version": "1.0.1",
  "tools": [
    // ... your tools here
  ]
}

Your existing API endpoints remain unchanged. For example:

GET /users/{user_id} - Returns user data
POST /orders - Creates new orders
etc.

Manual Structure

The UTCP manual follows a standardized structure that defines your tools and how to call them. For complete field specifications, data types, and validation rules, see the UTCP Manual API Reference.

Key Components

Manual metadata: Version information and API details
Tool definitions: Description of available tools and their capabilities
Call templates: Instructions for invoking each tool
Authentication: Security configuration for tool access
Variables: Dynamic values for tool parameters

Tool Definition

Tools are defined in your UTCP manual with their input parameters, call instructions, and optional metadata. For complete field specifications, see the Tool API Reference.

Communication Protocol Plugins

HTTP Tools

Most common for REST APIs:

{
  "name": "create_user",
  "description": "Create a new user account",
  "inputs": {
    "type": "object",
    "properties": {
      "user_fields": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string", "format": "email"}
        },
        "required": ["name", "email"]
      }
    },
    "required": ["user_fields"]
  },
  "tool_call_template": {
    "call_template_type": "http",
    "url": "https://api.example.com/users",
    "http_method": "POST",
    "auth": {
        "auth_type": "api_key",
        "api_key": "Bearer ${API_TOKEN}",
        "var_name": "Authorization",
        "location": "header"
    },
    "body_field": "user_fields"
  }
}

CLI Tools

For command-line applications:

{
  "name": "git_analysis",
  "description": "Analyze git repository status and commit history",
  "inputs": {
    "type": "object",
    "properties": {
      "repo_path": {"type": "string", "description": "Path to git repository"}
    },
    "required": ["repo_path"]
  },
  "tool_call_template": {
    "call_template_type": "cli",
    "commands": [
      {
        "command": "cd UTCP_ARG_repo_path_UTCP_END",
        "append_to_final_output": false
      },
      {
        "command": "git status --porcelain",
        "append_to_final_output": false
      },
      {
        "command": "echo \"Status: $CMD_1_OUTPUT, Files changed: $(echo \"$CMD_1_OUTPUT\" | wc -l)\"",
        "append_to_final_output": true
      }
    ]
  }
}

Authentication

API Key Authentication

{
  "auth": {
    "auth_type": "api_key",
    "api_key": "${API_KEY}",
    "var_name": "X-API-Key",
    "location": "header"
  }
}

Bearer Token

To use a Bearer Token, you can use the api_key authentication type.

{
  "auth": {
    "auth_type": "api_key",
    "api_key": "Bearer ${ACCESS_TOKEN}",
    "var_name": "Authorization",
    "location": "header"
  }
}

OAuth2

{
  "auth": {
    "auth_type": "oauth2",
    "client_id": "${CLIENT_ID}",
    "client_secret": "${CLIENT_SECRET}",
    "token_url": "https://auth.example.com/token",
    "scope": "read:users write:users"
  }
}

Per-Tool Authentication

{
  "name": "admin_action",
  "description": "Perform admin action",
  "tool_call_template": {
    "call_template_type": "http",
    "url": "https://api.example.com/admin/action",
    "http_method": "POST",
    "auth": {
      "auth_type": "api_key",
      "api_key": "${ADMIN_TOKEN}",
      "var_name": "Authorization",
      "location": "header"
    }
  }
}

Variable Substitution

Use ${VARIABLE_NAME} syntax for dynamic values:

From Tool Arguments

{
  "url": "https://api.example.com/users/{user_id}"
}

From Environment Variables

{
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}",
    "X-Client-ID": "${CLIENT_ID}"
  }
}

Default Values

{
  "manual_version": "1.0.0",
  "utcp_version": "1.0.1",
  "variables": {
    "base_url": "https://api.example.com",
    "timeout": 30
  },
  "tools": [
    {
      "name": "get_data",
      "tool_call_template": {
        "call_template_type": "http",
        "url": "${base_url}/data"
      }
    }
  ]
}

Implementation Examples

REST API Implementation

For a typical REST API, you'll need to:

Keep your existing endpoints unchanged
Add a UTCP discovery endpoint at /utcp
Map your API operations to UTCP tools

Example API structure:

GET  /users/{user_id}     # Your existing endpoint
POST /users               # Your existing endpoint  
GET  /utcp                # New UTCP discovery endpoint

The UTCP manual describes how to call your existing endpoints:

{
  "manual_version": "1.0.0",
  "utcp_version": "1.0.1",
  "info": {
    "title": "User Management API",
    "version": "1.0.0",
    "description": "API for managing user accounts"
  },
  "tools": [
    {
      "name": "get_user",
      "description": "Retrieve user information by ID",
      "inputs": {
        "type": "object",
        "properties": {
          "user_id": {"type": "string"}
        },
        "required": ["user_id"]
      },
      "outputs": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "email": {"type": "string"}
        }
      },
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/users/{user_id}",
        "http_method": "GET",
        "auth": {
          "auth_type": "api_key",
          "api_key": "Bearer ${API_TOKEN}",
          "var_name": "Authorization",
          "location": "header"
        }
      }
    },
    {
      "name": "create_user",
      "description": "Create a new user account",
      "inputs": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"}
        },
        "required": ["name", "email"]
      },
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/users",
        "http_method": "POST",
        "auth": {
          "auth_type": "api_key",
          "api_key": "Bearer ${API_TOKEN}",
          "var_name": "Authorization",
          "location": "header"
        },
        "body_field": "user_data"
      }
    }
  ]
}

OpenAPI Integration

If you already have an OpenAPI/Swagger specification, you can automatically convert it to a UTCP manual:

Automatic Conversion

Many UTCP implementations provide OpenAPI converters that can:

Parse OpenAPI specifications from URLs or files
Convert paths to UTCP tools automatically
Map authentication schemes to UTCP auth types
Generate proper input/output schemas

Conversion Configuration

You can customize the conversion process:

{
  "source": "https://api.example.com/openapi.json",
  "base_url": "https://api.example.com",
  "include_operations": ["get", "post"],
  "exclude_paths": ["/internal/*"],
  "auth_template": {
    "auth_type": "api_key",
    "api_key": "${API_KEY}",
    "var_name": "X-API-Key",
    "location": "header"
  }
}

Manual Review

After automatic conversion:

Review generated tools for accuracy
Add missing descriptions and examples
Validate input/output schemas
Test with UTCP clients
Customize authentication as needed

Best Practices

Manual Design

Clear Descriptions: Write clear, concise tool descriptions
Comprehensive Schemas: Use detailed JSON schemas for inputs/outputs
Consistent Naming: Use consistent naming conventions
Version Management: Use semantic versioning for your manual
Documentation: Include examples and usage notes

Security

Authentication: Always implement proper authentication
Input Validation: Validate all inputs on your API side
Rate Limiting: Implement rate limiting to prevent abuse
HTTPS Only: Use HTTPS for all production endpoints
Credential Management: Never hardcode credentials in manuals

Performance

Efficient Endpoints: Design efficient API endpoints
Caching: Implement appropriate caching strategies
Pagination: Use pagination for large result sets
Timeouts: Set reasonable timeout values
Monitoring: Monitor API performance and usage

Maintenance

Versioning: Version your manual and API together
Backward Compatibility: Maintain backward compatibility when possible
Deprecation: Provide clear deprecation notices
Testing: Test your manual with UTCP clients
Documentation: Keep documentation up to date

Testing Your Manual

Manual Validation

Validate your UTCP manual structure:

JSON Schema Validation: Ensure your manual follows the UTCP schema
Tool Definition Validation: Check that all tools have required fields
Call Template Validation: Verify call templates are properly formatted
Authentication Validation: Test authentication configurations

Integration Testing

Test your manual with UTCP clients:

Tool Discovery: Verify clients can discover your tools
Tool Execution: Test actual tool calls with various inputs
Error Handling: Test error scenarios and responses
Authentication: Verify authentication works correctly
Performance: Test response times and reliability

Testing Checklist

Manual validates against UTCP schema
All tools have unique names
All required fields are present
Call templates are correctly formatted
Authentication works as expected
Tools return expected outputs
Error responses are properly formatted
Performance meets requirements

Migration Strategies

From OpenAPI

Automatic Conversion: Use OpenAPI converter for initial conversion
Manual Refinement: Refine converted manual for better descriptions
Authentication Setup: Configure authentication properly
Testing: Test converted manual thoroughly

From MCP

Wrapper Approach: Use UTCP-MCP plugin initially
Gradual Migration: Migrate tools one by one to native protocols
Direct Implementation: Implement tools using native UTCP protocols
Deprecation: Remove MCP dependency once migration is complete

Common Patterns

CRUD Operations

{
  "tools": [
    {
      "name": "create_resource",
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/resources",
        "http_method": "POST"
      }
    },
    {
      "name": "get_resource",
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/resources/${id}",
        "http_method": "GET"
      }
    },
    {
      "name": "update_resource",
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/resources/${id}",
        "http_method": "PUT"
      }
    },
    {
      "name": "delete_resource",
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://api.example.com/resources/${id}",
        "http_method": "DELETE"
      }
    }
  ]
}

Batch Operations

{
  "name": "batch_process",
  "description": "Process multiple items in batch",
  "inputs": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": {"type": "object"}
      }
    }
  },
  "tool_call_template": {
    "call_template_type": "http",
    "url": "https://api.example.com/batch",
    "http_method": "POST",
    "body_field": "items"
  }
}

Next Steps

Design Your Manual: Plan your tool structure and descriptions
Choose Protocols: Select appropriate communication protocols
Implement Discovery: Add the /utcp endpoint to your API
Test Integration: Test with UTCP clients
Monitor Usage: Monitor how your tools are being used
Iterate: Improve based on usage patterns and feedback

For more information, see:

Language-Specific Implementation

For detailed implementation examples and code samples in your programming language:

Multi-language: UTCP Implementation Examples - Examples across Python, TypeScript, Go, and other languages
TypeScript: TypeScript UTCP Documentation
Other languages: Check respective repositories in the UTCP GitHub organization

Overview​

Quick Start​

1. Create a Simple Manual​

2. Expose via Discovery Endpoint​

Manual Structure​

Key Components​

Tool Definition​

Communication Protocol Plugins​

HTTP Tools​

CLI Tools​

Authentication​

API Key Authentication​

Bearer Token​

OAuth2​

Per-Tool Authentication​

Variable Substitution​

From Tool Arguments​

From Environment Variables​

Default Values​

Implementation Examples​

REST API Implementation​

OpenAPI Integration​

Automatic Conversion​

Conversion Configuration​

Manual Review​

Best Practices​

Manual Design​

Security​

Performance​

Maintenance​

Testing Your Manual​

Manual Validation​

Integration Testing​

Testing Checklist​

Migration Strategies​

From OpenAPI​

From MCP​

Common Patterns​

CRUD Operations​

Batch Operations​

Next Steps​

Language-Specific Implementation​