AI / Universal Tool Calling Protocol (UTCP) Interview questions

UTCP (Universal Tool Calling Protocol) is an open standard that lets AI agents discover tools and call them directly, using each tool's own native protocol. There is no wrapper or proxy server sitting in the middle.

A tool provider publishes a manual: a JSON document that lists its tools and spells out how to call each one (URL, method, auth, and so on). The agent reads the manual and then talks to the API itself.

The project's guiding idea is simple: if a human can call your API, an agent should be able to as well, with the same security and no extra infrastructure.

Most tool-integration approaches make you stand up a wrapper server for every tool and route all traffic through it. UTCP removes that layer by describing how to call the existing API directly.

According to the UTCP documentation, the wrapper-based approach forces teams to:

• build and maintain a wrapper server per tool
• send every call through a middleman protocol
• re-implement authentication and security that the API already has
• accept extra latency and operational complexity

With UTCP the API keeps its own auth, scaling and monitoring. You add one discovery endpoint (or reuse an OpenAPI spec) and agents can start calling.

A UTCP manual is a JSON document that tells an agent which tools a provider offers and exactly how to call each one. Think of it as the instruction sheet that ships with the API.

A v1.x manual typically carries manual_version, utcp_version, an optional info block, and a tools array. Each tool holds its name, description, input schema and a tool_call_template.

{
  "manual_version": "1.0.0",
  "utcp_version": "1.0.1",
  "tools": [{
    "name": "get_weather",
    "description": "Get current weather for a location",
    "inputs": {"type": "object",
               "properties": {"location": {"type": "string"}},
               "required": ["location"]},
    "tool_call_template": {"call_template_type": "http",
                           "url": "http://localhost:8000/weather",
                           "http_method": "GET"}
  }]
}

A manual can be served from an endpoint, shipped as a file, or generated by converting an OpenAPI spec. However it arrives, the client treats it the same way: parse it, register the tools and keep each tool's call template for later.

UTCP v1.x is built from four main pieces, plus a plugin layer for protocols.

The plugin system lets you add protocols, tool repositories and search strategies without touching the core package.

A useful mental split: the manual and its tools are what the provider publishes, while the call template and client are what the consumer uses to act on them.

A call template is the part of a tool definition that says how to reach the tool. Concretely, it maps a tool name plus the arguments you pass into a real request in some communication protocol.

Its call_template_type picks the protocol plugin (http, cli, sse, text, mcp), and the remaining fields are specific to that protocol. An HTTP template carries a URL and method; a CLI template carries commands.

{
  "call_template_type": "http",
  "url": "https://api.example.com/users/{user_id}",
  "http_method": "GET"
}

Tools in the same manual can use different templates, so one manual can mix an HTTP endpoint, a CLI command and a streaming source.

The UTCP client is the discovery-and-execution engine on the consumer side. You give it a configuration listing manual sources, and it fetches those manuals, registers their tools and makes them searchable and callable.

Day-to-day you use two operations: search_tools to find relevant tools for a task, and call_tool to run one. Under the hood the client picks the right protocol plugin from each tool's call template.

In the reference design its storage, search and protocol handling are pluggable interfaces, so you can swap them without rewriting your agent.

UTCP supports protocols through plugins. The stable set documented for v1.1 is below.

Older docs and comparison pages also mention WebSocket, GraphQL and gRPC. Check your SDK's plugin list before relying on those, since they are not in the stable table.

One manual can mix protocols as well. A single tool might use HTTP and another a CLI command, and the client picks the right plugin per tool.

Install the core package plus the protocol plugins you need. Plugins are separate packages, so a project only pulls in what it uses.

# Python
pip install utcp utcp-http utcp-cli

# Node.js
npm install @utcp/core @utcp/http @utcp/cli

Package names have shifted between SDK releases (some TypeScript READMEs show @utcp/sdk), so confirm against the repository for your version.

After installing, build a client from a config that lists your manual sources, then use search_tools and call_tool. Add utcp-text or utcp-mcp only if you need file-based manuals or MCP interop, and pin versions in production since the project is still evolving.

GET /utcp is the conventional endpoint where a provider returns its UTCP manual. It is how you make an existing API discoverable: add one route that returns the JSON manual and you are done.

The client then points an HTTP call template at that URL as a manual source. It is a convention rather than a fixed rule, so the path can differ, and the manual can also come from a text file or a converted OpenAPI spec.

from fastapi import FastAPI
app = FastAPI()

@app.get("/utcp")
def utcp_discovery():
    return {"manual_version": "1.0.0",
            "utcp_version": "1.0.1",
            "tools": [...]}

Many providers simply return a static JSON document from that route, which is why the docs describe the extra infrastructure as one endpoint.

Each entry in the manual's tools array describes one capability. The essentials are a name, a description the agent can reason over, an inputs JSON Schema, and a tool_call_template.

Optional but useful fields include outputs (return schema), tags for categorising tools, and average_response_size so a client can plan resources before calling.

A clear description matters more than people expect. It is what the agent reads when deciding whether this tool fits the task.

Treat the description as part of your prompt design. Say what the tool does, when to use it and what it returns, in a sentence or two.

UTCP does not invent a new auth layer. A call template (or the manual) carries an auth block describing the credentials the API already expects.

The documented types are api_key (with api_key, var_name and location such as header or query) and oauth2 (client id, secret, token URL, optional scope).

"auth": {
  "auth_type": "api_key",
  "api_key": "${WEATHER_API_KEY}",
  "var_name": "appid",
  "location": "query"
}

Secrets are written as ${VAR} placeholders and supplied by the client at runtime, so the manual itself never has to contain a real key.

Auth can sit at the manual level so every tool reuses the same credentials, while a sensitive tool can carry its own auth block for tighter control.

UTCP call templates use two placeholder styles, and they mean different things.

Single braces are filled from what the agent passes when calling the tool. Dollar-brace values come from the client's variables or a loaded .env file, which keeps secrets out of manuals.

Single braces are only for values the agent supplies per call, so never put secrets there. Test each tool once after renaming variables or changing config, because a half-resolved placeholder is easy to miss.

UTCP is designed to extend OpenAPI for agents rather than replace it. OpenAPI describes an API for human developers; UTCP adds agent-oriented details such as tags, average_response_size, multi-protocol call templates and direct execution instructions.

You do not have to rewrite anything to get started. Point the client at an OpenAPI document and it converts the endpoints into UTCP tools, or run the OpenApiConverter yourself and save the manual to a file.

That makes OpenAPI-described services the cheapest on-ramp to UTCP.

The CLI call template wraps local command-line tools so an agent can run them as UTCP tools. It holds an ordered list of commands, and each command can decide whether its output counts toward the final result.

Tool arguments are injected with UTCP_ARG_name_UTCP_END placeholders. You can also set working_dir and env_vars.

{
  "call_template_type": "cli",
  "commands": [
    {"command": "cd /app", "append_to_final_output": false},
    {"command": "python script.py UTCP_ARG_input_UTCP_END",
     "append_to_final_output": true}
  ],
  "working_dir": "/app"
}

The docs flag CLI as a high-risk protocol, so sandbox it and sanitise inputs.

Prefer one narrowly scoped command per tool, such as 'list backups', over a generic shell tool, and keep arguments to the few values the schema allows.

The text call template, from the utcp-text plugin, reads content from a file. It has two jobs: loading a manual that is saved on disk, and exposing static file content as a tool.

A typical use is converting a big OpenAPI spec once, saving the resulting manual as JSON, and then loading it like this:

{
  "manual_call_templates": [{
    "name": "github_manual",
    "call_template_type": "text",
    "file_path": "./github_manual.json"
  }]
}

Because it touches the filesystem, restrict paths to approved directories and block traversal.

It is also handy for tests: a text template pointing at a local manual lets you try an agent against fixed tools with no network involved.

The UTCP documentation site is published under Apache-2.0, except for the API reference docs, which are under MPL-2.0. The project lives in an open GitHub organisation with separate repositories for the specification and each language SDK.

Changes to the specification go through an RFC process, and the community gathers on GitHub discussions and Discord. That open process is why the spec has versioned docs (0.1, 1.0, 1.1) and migration guides between them.

Apache-2.0 is permissive, so companies can embed the SDKs in commercial products without copyleft obligations, which matters for enterprise adoption.

The UTCP GitHub organisation hosts implementations in several languages. The docs call out Python, TypeScript and Go, and the ecosystem notes also list Rust.

Because the standard is language-agnostic JSON plus protocol plugins, a manual written once works with any compliant client. The TypeScript SDK additionally ships a Code Mode library for agents that write code.

Maturity differs by language, so look at each repository's release notes before betting a production system on one.

If your language has no official SDK, the protocol is plain JSON plus common transports, so a minimal client is feasible, though you would lose the plugin ecosystem.

Code Mode is a pattern, shipped as the @utcp/code-mode library, where the model is given one tool: run a TypeScript program in a sandbox that already has your UTCP and MCP tools wired in.

Instead of emitting one JSON tool call per turn, the model writes a single script that calls several tools, loops, filters results and returns only what matters. The library's authors report fewer round trips and lower token use on multi-step tasks; treat the exact percentages as vendor figures to verify on your own workloads.

The client entry point is callToolChain, and searchTools lets the agent load only the tool interfaces it needs.

The core difference is architecture. UTCP describes how to call a tool directly, while MCP standardises a server that sits between the agent and the tool.

UTCP's own documentation argues its approach cuts infrastructure and keeps native auth. MCP's strengths are strict standardisation, centralised control and features beyond tool calling. Both can coexist, since UTCP has an MCP plugin.

The flow has four moves: discover, learn, call, respond.

1. The client fetches the manual from the provider or file.
2. It registers the tools and their call templates.
3. When the agent picks a tool, the client resolves variables and builds the native request.
4. The API answers normally and the client returns the result.

sequenceDiagram
  participant A as Agent
  participant C as UTCP Client
  participant M as Manual Source
  participant T as Tool API
  C->>M: Fetch manual
  M-->>C: Tools and call templates
  A->>C: search_tools and pick a tool
  A->>C: call_tool with arguments
  C->>T: Native request built from template
  T-->>C: Native response
  C-->>A: Result

Notice that the provider only participates in step one. After that, the client talks to the real API.

Search is optional but typical. With a small catalogue you can list every tool, while with a large one the client ranks tools against the task. Errors come back as the API's own errors, because the client does not translate them into a protocol-specific format.

Because the manual already contains everything required to make the call: the URL, method, headers, auth and argument mapping. A client can build that request itself, so nothing has to translate on its behalf.

A wrapper server exists to receive a protocol-specific request and re-issue it to the real API. When the client speaks the API's native protocol, that translation hop has no job left. The API's existing gateway, rate limits and logging stay in force.

The one piece of infrastructure you may add is a route that serves the manual, and even that can be a static file or a converted OpenAPI spec.

A tool's inputs field is a JSON Schema object. It tells the agent which arguments exist, their types and which are required. The optional outputs field does the same for the return value.

That schema serves two audiences. The model reads it to decide what to send, and the client or provider can validate arguments against it. The security guide suggests tightening schemas with maxLength, pattern, numeric bounds and additionalProperties: false.

"inputs": {
  "type": "object",
  "properties": {
    "email": {"type": "string", "format": "email", "maxLength": 254}
  },
  "required": ["email"],
  "additionalProperties": false
}

Keep schemas honest. Leave optional fields out of required, trim properties the tool does not need, and use enum for fixed choices, since models tend to fill in every property they see and enums cut down invented values.

The HTTP call template applies simple rules. Arguments that match {name} placeholders in the URL path fill those slots. Remaining arguments go to the query string for GET requests, or into the request body for POST, PUT and PATCH.

When a tool needs a specific argument to become the whole body, set body_field to that argument's name.

{
  "call_template_type": "http",
  "url": "https://api.example.com/users/{user_id}/notes",
  "http_method": "POST",
  "body_field": "body"
}

So a call with user_id and body hits the user's path and sends body as the payload.

Argument values can also be used in headers, which suits APIs that expect tenant or request IDs there. Test one GET tool and one POST tool, because argument routing differs between them.

An oauth2 auth block gives the client a client id, secret, token URL and optional scope. The client fetches an access token and attaches it to calls, so the secrets stay in configuration rather than in the agent's prompt.

The security guide adds several safeguards that reference clients apply:

• the token endpoint must satisfy the HTTPS-or-loopback rule before any credential is sent
• redirects from the token endpoint are handled under the same rule
• tokens are cached per full credential configuration, never shared just because two configs use the same client id

That last point prevents one configuration from borrowing another's token.

You have two low-effort routes and neither touches your API's business logic.

1. Reuse OpenAPI. If you already publish a spec, point the client's manual call template at it and the spec is converted into tools automatically.
2. Add a discovery endpoint. Serve a manual from GET /utcp that lists tools and references your real URLs.

A third option is to convert the spec once with OpenApiConverter, save the manual as JSON and load it through the text call template, which suits specs that rarely change.

Whichever route you take, describe each tool clearly and keep authentication on the API itself.

The utcp-mcp plugin lets a UTCP client treat MCP servers as another tool source. You register an MCP call template whose config lists the servers, and their tools appear next to native UTCP tools.

{
  "call_template_type": "mcp",
  "config": {
    "mcpServers": {
      "server_name": {
        "transport": "stdio",
        "command": ["python", "-m", "my_mcp_server"]
      }
    }
  }
}

This is the basis of the hybrid and migration story: keep legacy MCP servers running while new tools use direct HTTP or CLI templates. Server URLs follow the same HTTPS-or-loopback rule, and processes should be sandboxed.

Remember the trade-off. Tools reached through MCP still pay MCP's server overhead and follow MCP's behaviour. The plugin gives you one client interface, but the direct-call benefits only arrive once a tool moves to a native template.

Use them when a tool returns data over time instead of in a single reply: log tails, live feeds, progress events. Both are provided by the utcp-http plugin.

A standard HTTP template waits for one response. An SSE template keeps the connection open and collects events until the stream ends, the timeout hits or a limit such as max_events is reached.

{
  "call_template_type": "sse",
  "url": "https://api.example.com/logs/stream",
  "timeout": 300
}

Authenticate these connections, cap events and set timeouts. An open stream is an easy way to tie up resources.

Pick plain HTTP when the answer is small and bounded. Pick SSE when partial results are useful as they arrive, and accept the cost of managing a longer-lived connection.

The client exposes search_tools, which takes a task description and returns the most relevant registered tools. This matters once you have dozens or thousands of tools and cannot paste them all into a prompt.

The ranking logic is a pluggable search strategy, so you can swap in your own, for example one that uses embeddings. Tool names, descriptions and tags are the raw material, which is why good descriptions pay off.

Typical agent loop: search, show the model only the top few tools, let it choose, then call.

Keep descriptions concrete: 'create a refund for an order' ranks better than 'handles payments'. Re-test retrieval after adding large batches of tools, because new entries can crowd out older matches.

UTCP fits best when you already have working APIs and want agents to use them with the least new infrastructure.

• You have existing REST or OpenAPI services.
• You want to keep your own auth, scaling and monitoring.
• You need several protocols (HTTP, CLI, SSE) behind one client.
• You have limited capacity to run and monitor extra servers.
• You want agents calling tools quickly with minimal code changes.

Treat the project's own cost and latency comparisons as a starting hypothesis. Measure with your workload, because a direct call is only faster if the extra hop was your real bottleneck.

A quick test: if the need sounds like 'call these existing endpoints', UTCP is probably enough. If it sounds like 'serve context, prompts and tools from one standard server', look at MCP.

MCP is the better pick when the things UTCP deliberately leaves out are exactly what you want.

• You need resources and prompts, not just tool calls.
• You want strict protocol standardisation across every tool.
• You prefer centralised control over what agents can reach.
• Your clients and tooling are already built around MCP servers.
• You are building a closed ecosystem where you own both sides.

A central server can also be a feature: one place to enforce policy and log access. UTCP trades that for directness. The two are not exclusive, since UTCP can call MCP servers through its plugin.

These fields exist because agents consume tools differently than humans reading API docs.

tags let a client group and filter tools, which helps search_tools narrow a large catalogue before the model sees anything. For example, tags such as billing or read-only can steer selection.

average_response_size hints at how big a reply usually is, so the client or agent can budget context and avoid calling a tool that will flood the window. Both are optional metadata, but they are two of the concrete ways UTCP goes beyond plain OpenAPI.

Neither field changes how a call is made. They guide selection and planning, so leaving them out never breaks execution.

Registration turns a pointer to a manual into usable tools.

1. The client reads the manual call template (for example an HTTP URL, a file or an OpenAPI document).
2. The matching protocol plugin fetches and parses the manual.
3. OpenAPI input is converted into UTCP tools.
4. The tools and their call templates are stored in the tool repository.
5. They become visible to search_tools and callable by name.

Because the repository is pluggable, storage can be in memory or something shared. Re-registering a source refreshes its tools.

If a source is unreachable or its manual fails validation, registration for that source should fail and its tools will not appear, so check the result before assuming the tools exist.

Keep real values out of manuals and source control. Manuals reference ${VAR} placeholders, and the client resolves them from its variables block or from files named in load_variables_from.

manual_call_templates:
  - name: weather_service
    call_template_type: http
    url: https://api.weather.com/utcp

variables:
  WEATHER_API_KEY: your-api-key

load_variables_from:
  - variable_loader_type: dotenv
    env_file_path: .env

In practice, put the key in .env or your secret manager and leave the inline example value out. The security guide also suggests restricting which variable names are allowed and logging access.

Keep a separate variable set per environment, such as dev and prod, so a staging key can never hit production APIs. Rotate keys on a schedule and avoid logging resolved values.

The headline change is architectural. Early UTCP described tools through providers bundled in one Python package, with provider types such as http, sse and a few work-in-progress ones. Version 1.0 reorganised around call templates and a modular plugin system.

• a small core package with protocols in separate plugins (utcp-http, utcp-cli, utcp-mcp)
• manuals that carry tool_call_template for each tool
• pluggable repositories and search strategies
• SDKs in more than one language

Version 1.1 followed with its own migration guide. For exact field renames, follow the official guides rather than guessing.

In practice, treat the move as a small project: upgrade the SDK, regenerate or edit the manuals, adjust client config, then rerun your tool tests.

They version two different things.

Bump manual_version whenever you add, remove or change tools. Change utcp_version only when you adopt a newer protocol release. Clients can use the second field to judge whether they understand the document's format.

Treat the manual as a versioned artifact. A changelog beside manual_version helps teams know when agents should refresh cached tools.

Manual endpoints are discovery targets: they reveal which tools exist and how they are called. Treat them as sensitive.

• Require authentication on the manual endpoint.
• Validate discovery tokens.
• Return only tools the caller is authorised to see.
• Filter by user permissions rather than publishing one global manual.
• Log every discovery attempt.

Hiding a tool from the manual is not a substitute for enforcing authorisation on the tool itself. Keep per-tool auth on the real endpoint as well.

Protect discovery with the same stack as the API itself, such as OAuth, gateway rules or mTLS. Reviewing discovery logs is also a good way to spot scanners enumerating your tools.

Reference clients apply a fixed set of destination rules no matter what a manual or config says. The point is that a malicious or careless manual cannot talk the client into unsafe connections.

Design your tools and manuals with these rules in mind. For instance, a staging manual served over plain HTTP from a non-loopback host will simply be rejected, so use HTTPS even in test environments.

If it could, a manual fetched from an untrusted host could point your tools at 127.0.0.1 and make the client call services running on your own machine: local admin panels, databases with HTTP interfaces, development servers. That is a server-side request forgery style attack launched through a manual.

The rule works like this:

• A manual or OpenAPI spec discovered from a non-loopback origin may not declare tool or server URLs on the loopback interface.
• The local-development exemption is decided by the final origin after redirects.
• A loopback URL that redirects to a remote origin therefore does not keep the exemption.

Developers can still point a client at a locally served manual that calls local tools, which keeps the normal dev workflow intact.

The CLI protocol runs real commands with model-influenced arguments, so the guide marks it as high risk. Defence is layered.

1. Use absolute paths for executables so a modified PATH cannot swap them.
2. Sanitise every argument: strip or reject shell metacharacters such as ;, &, |, backticks, $, brackets and redirects.
3. Validate arguments against expected patterns and length limits before they reach the command.
4. Run in a sandbox with a fixed working_dir and a minimal env_vars set.
5. Apply strict timeouts, check exit codes and use a low-privilege user.

{
  "call_template_type": "cli",
  "commands": [
    {"command": "/usr/local/bin/safe-script --input UTCP_ARG_value_UTCP_END",
     "append_to_final_output": true}
  ],
  "working_dir": "/safe/sandbox",
  "env_vars": {"PATH": "/usr/local/bin:/usr/bin", "HOME": "/tmp/sandbox"}
}

Where possible, prefer parameterised execution over building command strings, and expose narrow, single-purpose commands instead of a generic shell.

Test with hostile input such as semicolons, subshell syntax and very long strings, and confirm each is rejected before any process starts.

The text template reads files, so a manipulated file_path such as ../../etc/passwd could expose things it should not. Validate the path before opening anything.

1. Resolve the requested path to an absolute path.
2. Resolve symbolic links first so a link cannot escape.
3. Check the result sits inside an allow-listed directory.
4. Treat any path-resolution error as a denial.
5. Enforce file size limits and extension allow-lists.

from pathlib import Path

ALLOWED = Path("/safe/data").resolve()

def is_allowed(requested: str) -> bool:
    try:
        target = (ALLOWED / requested).resolve()
        return target.is_relative_to(ALLOWED)
    except Exception:
        return False

Validate after resolving, not before. Checking the raw string for .. misses encoded and symlink-based escapes.

Cap file sizes so a tool cannot push a huge file into an agent's context, and log denied attempts, since repeated traversal tries are a useful alarm signal.

The client treats a redirect as a new connection, not a continuation. Each hop is checked against the same destination rule (HTTPS/WSS, or loopback-only plain HTTP/WS), so a redirect cannot downgrade the connection to unsafe plain HTTP on a remote host.

Credentials are also protected. Auth headers, cookies, query-string keys and request bodies are not forwarded across origins, so an API key sent to api.example.com never leaks to a different host the response bounced to.

For OAuth2, redirects from the token endpoint are handled under the same rule, and for MCP's token flow they are refused outright. If your API legitimately moves between hosts, update the manual to the new URL rather than depending on redirects carrying auth.

To verify this in testing, point a manual at a URL that redirects to a different host and confirm that no auth header reaches the second host.

Code Mode swaps many JSON tool calls for one code-execution tool. The model sees a single capability and writes a TypeScript program using your tools as typed functions.

flowchart TD
  A["User task"] --> B["LLM writes TypeScript"]
  B --> C[callToolChain]
  C --> D["Sandbox runs the script"]
  D --> E["Script calls UTCP and MCP tools"]
  E --> F["Results stay inside the script"]
  F --> G["Script returns final result and logs"]
  G --> H["LLM answers the user"]

The sandbox has the registered tools wired in, with auto-generated TypeScript interfaces and runtime introspection so the model can look up a tool's signature on demand. Intermediate results stay in the script's variables instead of passing back through the model's context.

That is where the claimed gains come from: fewer LLM round trips and fewer tokens. The trade-off is that you now run model-written code, so the sandbox and the tools it can reach become your security boundary.

Plan observability up front: keep the generated script and its console output with each run, because debugging a failed chain means reading the code the model wrote. Set execution time limits, restrict network and filesystem access inside the sandbox and register only the tools the task needs.

Loading hundreds of tool definitions into every prompt is the expensive mistake. UTCP gives you several ways to avoid it.

1. Search before exposing. Use search_tools and show the model only the top few matches.
2. Tag and describe well. Short, distinctive descriptions and useful tags make retrieval accurate, so you can show fewer candidates.
3. Use Code Mode. Let the model introspect interfaces on demand and batch several calls in one script.
4. Mind response sizes. Use average_response_size to avoid tools that return huge payloads, and trim output inside the script.
5. Cache discovery. Register manuals once and reuse the repository.

Measure tokens per task before and after. Retrieval that misses the right tool costs more than it saves.

Watch for tool-selection drift too. Trimming tags or descriptions to save tokens can reduce retrieval accuracy, so rerun a regression set of typical tasks after each change.

The client is a thin coordinator over pluggable parts. Roughly, a call travels like this.

flowchart LR
  CFG["Config and variables"] --> REG["Register manual sources"]
  REG --> PROTO["Protocol plugin per call template type"]
  PROTO --> REPO[(Tool repository)]
  Q[search_tools] --> SS["Search strategy"]
  SS --> REPO
  CALL[call_tool] --> RES["Resolve variables and arguments"]
  RES --> PROTO
  PROTO --> API["Native tool or API"]

Registration uses a communication protocol plugin matching each manual source's call_template_type to fetch and parse manuals. Tools land in a tool repository that is itself an interface, so storage can be swapped.

Search runs through a replaceable search strategy. Execution resolves ${VAR} values and tool arguments, picks the plugin named in the tool's template, applies auth and sends the native request.

The main interfaces in the core package are the communication protocol, the concurrent tool repository and the search strategy. Everything else is configuration.

That separation is the point: the agent only sees search_tools and call_tool while plugins handle protocol details. Swapping an in-memory repository for a shared one, or keyword search for embeddings, needs no change to manuals or the agent loop.

Extending UTCP to a new transport follows three steps from the implementation guide.

1. Define a call template. Choose a unique call_template_type and the fields your protocol needs (host, topic, timeout, auth).
2. Implement the communication handler. Write the logic that registers manuals (if the protocol serves them) and executes calls, mapping arguments to the wire format.
3. Register the protocol. Make it available to the client so templates of that type are routed to your handler.

{
  "call_template_type": "custom",
  "custom_field": "value",
  "timeout": 30,
  "auth": {"auth_type": "api_key", "api_key": "${API_KEY}"}
}

Keep the same safeguards the built-in plugins follow: validate destinations, support timeouts and avoid forwarding credentials across origins.

Test the plugin against a fake server first and cover timeout and error paths. Write a security section for your template the way the built-in docs do (destinations, credentials, input validation), and publish the template's fields so provider authors know which are required.

Don't switch overnight. The UTCP docs describe a phased plan that keeps everything working while you move.

flowchart LR
  A["1 Assess MCP servers"] --> B["2 Hybrid: UTCP client plus MCP plugin"]
  B --> C["3 Migrate tools one by one to native UTCP"]
  C --> D["4 Retire MCP servers"]

1. Assess. Inventory servers and pick high-value tools.
2. Hybrid. Install UTCP with the MCP plugin and confirm existing tools work through it.
3. Migrate. Add manuals or /utcp endpoints for the underlying APIs and update client configs.
4. Clean up. Deprecate servers you no longer need and monitor.

Not every server should go. If a tool depends on MCP-only features such as resources or prompts, keep it behind the plugin.

Keep a rollback plan: leave the MCP server definition in config, disabled, until the native tool has run cleanly under real traffic. During the hybrid phase compare outputs from both paths to catch differences such as error formats or field names.

Removing the middleman changes the security picture rather than just improving it.

To compensate, secure manual discovery, validate every argument, lock down CLI and text protocols and rely on the client's destination rules. If you need central policy, put it at your API gateway, or accept that an MCP-style server gives you one place to enforce it. Which model is safer depends on how well your existing API security is run.

A practical posture: treat the manual as untrusted input to the client, treat tool arguments as untrusted input to the API, and put rate limits and audit logs on both sides.

Start by noticing the source. The comparison tables on the UTCP site, including the latency and resource figures, are published by the UTCP project and read as illustrations rather than independent benchmarks. The Code Mode percentages come from that library's own README and project listings.

A sound evaluation looks like this:

1. Define the task: tool count, call pattern, response sizes, concurrency.
2. Test the same tools via UTCP direct, via an MCP server and, if relevant, via the MCP plugin.
3. Measure end-to-end latency, tokens per task, error rate and operational cost, not only the network hop.
4. Run enough trials to see variance, and include cold starts.
5. Check where time really goes. LLM inference often dwarfs one extra network hop.

The extra hop is real, but it may not be your bottleneck.

A failing call that mentions a missing ${VAR} or an unfilled {arg} placeholder is almost always a configuration slip. Work through it in order.

1. Identify the syntax. {arg} comes from tool arguments, ${VAR} from config or environment.
2. Check the argument. Make sure the agent actually passed a value for each {arg} in the URL, and that the input schema marks it required.
3. Check the variable source. Confirm the name exists in variables or in the file referenced by load_variables_from, with exact spelling and case.
4. Check the loader path. A wrong env_file_path fails quietly more often than you would think.
5. Retest in isolation. Call the tool directly with known-good values before involving the model.

If the value is present but rejected, look at the substitution safeguards: values with characters like <, quotes or ; may be refused when sanitisation is on.

When a client cannot load tools from a source, check the layers from the outside in.

1. URL and scheme. Remote manuals must use HTTPS. Plain HTTP only works to a literal loopback address.
2. Authentication. A protected manual endpoint needs credentials or a discovery token. A 401 or 403 here is a config problem, not a UTCP bug.
3. Redirects. A redirect to another origin is re-validated and drops credentials, so the manual may load without auth and fail.
4. Loopback declarations. A remote manual listing loopback tool URLs is refused.
5. Document shape. Confirm valid JSON with tools and tool_call_template fields and a supported utcp_version.
6. Plugin presence. The plugin for the manual's call template type must be installed.

Fetch the manual with curl first. If that works but the client fails, the problem is almost certainly one of the client-enforced rules above.