utcp-cli

utcp cli

utcp (npm: @utcp/code-mode-cli) lets you call UTCP tools by writing TypeScript that executes in an isolated sandbox. It needs only a shell and a working folder — no MCP, no environment variables.

Run everything via npx @utcp/code-mode-cli <command> (or utcp <command> if installed). All output is JSON on stdout.

1. Read the guide

npx @utcp/code-mode-cli prompt

2. Configure (write a file — no env vars)

Write .utcp_config.json in the working directory listing the manuals (APIs / MCP servers / CLIs) you need:

{
  "load_variables_from": [
    { "variable_loader_type": "dotenv", "env_file_path": ".env" }
  ],
  "manual_call_templates": [
    {
      "name": "openlibrary",
      "call_template_type": "http",
      "http_method": "GET",
      "url": "https://openlibrary.org/static/openapi.json",
      "content_type": "application/json"
    }
  ]
}

Transports: http (incl. OpenAPI URLs), mcp (remote/local MCP servers), cli, text, file.

3. Discover

utcp search "search for books"   # returns tools + TypeScript interfaces
utcp list                        # all tool names
utcp info <tool>                 # full interface for a tool
utcp keys <tool>                 # required variables (tokens) for a tool

4. Run a tool-chain

Call tools as manual.tool({ args }). Top-level await and return work. Use a heredoc for multi-line code:

utcp run <<'EOF'
const r = await openlibrary.read_search_json_search_json_get({ q: "tolkien", limit: 3 });
return (r.docs || []).map(b => b.title);
EOF

Output: {"success":true,"result":<value>,"logs":[...]}.

5. Interactive OAuth (user signs into a page)

Declare an oauth2_user auth block on the manual. For a remote MCP server the block is just { "auth_type": "oauth2_user", "access_token": "${MY_TOKEN}" } — endpoints are auto-discovered. Then:

utcp login <manual>

login prints NDJSON describing what to do next. Handle it like this: