uxc 0.12.3

Universal X-Protocol CLI for URL-first schema discovery and invocation across OpenAPI, gRPC, GraphQL, MCP, and JSON-RPC
Documentation

UXC

Universal X-Protocol CLI

A stable execution surface for agents.

English | 简体中文

CI Coverage License: MIT Rust

UXC gives agents one stable way to discover, authenticate, and call remote tools across OpenAPI, gRPC, GraphQL, MCP, and JSON-RPC.

Instead of writing separate glue for each protocol, SDK, or local MCP setup, UXC turns remote interfaces into one predictable command contract with help-first discovery, structured execution, and deterministic JSON output.

Why UXC Exists

Agent tool use usually breaks down in the same places:

  • auth scattered across prompts, scripts, and local setup
  • different invocation models for each protocol
  • local MCP server names and config that are not portable across machines
  • large tool manifests or schemas pushed into prompt context
  • one-off wrappers that drift from upstream interfaces

UXC exists to make remote capabilities feel like one stable execution surface for agents and automation.

What UXC Does

  • Discover operations from an endpoint on demand
  • Inspect input and output shape before execution
  • Execute operations with structured arguments
  • Return deterministic JSON envelopes by default
  • Reuse auth bindings, signer profiles, and linked shortcuts

If a target can describe itself, UXC can usually call it.

Why It Works Well With Agents and Skills

  • Progressive discovery keeps context small: <host> -h, <host> <operation_id> -h, then execute
  • URL-first usage avoids dependency on machine-specific MCP aliases or local wrapper names
  • Auth bindings externalize credential matching instead of burying it in prompts
  • Linked shortcuts (uxc link) turn remote endpoints into stable local commands
  • The same command contract can be reused across many skills and workflows

Core Capabilities

  • URL-first usage: call endpoints directly, no server alias required
  • Multi-protocol detection and adapter routing
  • Schema-driven operation discovery (<host> -h, <host> <operation_id> -h)
  • Structured invocation (positional JSON, key-value args)
  • Deterministic JSON envelopes for automation and agents
  • Auth model with reusable credentials, bindings, and signer profiles
  • App-credential bootstrap for short-lived bearer tokens (for example, Feishu/Lark and DingTalk)
  • Host shortcut commands via uxc link
  • Link-level default OpenAPI schema persistence via uxc link --schema-url
  • Daemon-backed background subscriptions via uxc subscribe
  • Provider-aware event transports for Slack Socket Mode, Discord Gateway, and Feishu long connection
  • Stdio child-process auth injection via --inject-env NAME={{secret}}

Supported protocols:

  • OpenAPI / Swagger
  • gRPC (server reflection)
  • GraphQL (introspection)
  • MCP (HTTP and stdio)
  • JSON-RPC (OpenRPC-based discovery)

Architecture Snapshot

UXC keeps protocol diversity behind one execution contract:

UXC architecture snapshot

This design keeps discovery, auth, and execution stable while allowing protocol-specific internals.

Target Use Cases

  • AI agents and skills that need deterministic remote tool execution
  • CI/CD and automation jobs that need schema-driven calls without SDK setup
  • Cross-protocol integration testing with one command contract
  • Controlled runtime environments where JSON envelopes and predictable errors matter

Non-Goals

UXC is not:

  • a code generator
  • an SDK framework
  • an API gateway or reverse proxy

UXC is a stable execution surface for remote capabilities that can describe themselves.

Install

Homebrew (macOS/Linux)

brew tap holon-run/homebrew-tap
brew install uxc

Install Script (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh | bash

Review before running:

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh -o install-uxc.sh
less install-uxc.sh
bash install-uxc.sh

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh | bash -s -- -v v0.12.3

Windows note: native Windows is no longer supported; run UXC through WSL.

Cargo

cargo install uxc

From Source

git clone https://github.com/holon-run/uxc.git
cd uxc
cargo install --path .

Quickstart (3 Minutes)

Most HTTP examples omit the scheme for brevity. For public hosts, UXC infers https:// when omitted.

  1. Discover operations:
uxc petstore3.swagger.io/api/v3 -h
  1. Inspect operation schema:
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} -h
  1. Execute with structured input:
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} petId=1

Use only these endpoint forms:

  • uxc <host> -h
  • uxc <host> <operation_id> -h
  • uxc <host> <operation_id> key=value or uxc <host> <operation_id> '{...}'

For nested object or array inputs, key-value mode also supports dotted and indexed paths:

uxc <host> <operation_id> \
  prompt="summarize this file" \
  attachmentPaths[0]=/tmp/spec.pdf

Protocol Examples (One Each)

Operation ID conventions:

  • OpenAPI: method:/path (example: get:/users/{id})
  • gRPC: Service/Method
  • GraphQL: query/viewer, mutation/createUser
  • MCP: tool name (example: ask_question)
  • JSON-RPC: method name (example: eth_getBalance)

OpenAPI

uxc petstore3.swagger.io/api/v3 -h
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} petId=1

For schema-separated services, you can override schema source:

uxc api.github.com -h \
  --schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

gRPC

uxc grpcb.in:9000 -h
uxc grpcb.in:9000 addsvc.Add/Sum a=1 b=2

Note: gRPC unary runtime invocation requires grpcurl on PATH.

GraphQL

uxc countries.trevorblades.com -h
uxc countries.trevorblades.com query/country code=US
# Prefer positional JSON for non-string object arguments
uxc api.linear.app/graphql mutation/issueCreate '{"input":{"teamId":"TEAM_ID","title":"Test"}}'
# Optional: control GraphQL return fields via reserved _select argument
uxc api.linear.app/graphql query/issues '{"first":5,"_select":"nodes { identifier title url state { name } }"}'

MCP

uxc mcp.deepwiki.com/mcp -h
uxc mcp.deepwiki.com/mcp ask_question repoName=holon-run/uxc question='What does this project do?'

MCP (stdio)

UXC can also invoke MCP servers started as local processes over stdio. For stdio endpoints, the "URL" is a quoted command line.

Playwright MCP (stdio) example:

# One-off discovery
uxc "npx -y @playwright/mcp@latest --headless --isolated" -h

# Create a stable command name for repeated use (recommended)
uxc link playwright-mcp-cli "npx -y @playwright/mcp@latest --headless --isolated"
playwright-mcp-cli -h

# Inspect an operation before calling it
playwright-mcp-cli browser_navigate -h

# Call operations with key=value args
playwright-mcp-cli browser_navigate url=https://example.com
playwright-mcp-cli browser_snapshot

JSON-RPC

uxc fullnode.mainnet.sui.io -h
uxc fullnode.mainnet.sui.io sui_getLatestCheckpointSequenceNumber

Skills

UXC provides one canonical skill plus scenario-specific official wrappers. Use uxc skill as the shared execution layer, and add wrappers when they fit your workflow.

Start Here

  • uxc: canonical schema discovery and multi-protocol execution layer
  • playwright-mcp-skill: browser automation over MCP stdio through uxc
  • context7-mcp-skill: current library documentation and examples over MCP

See docs/skills.md for publish history, validation notes, and ClawHub maintenance details.

  • uxc: canonical schema discovery and multi-protocol execution layer
  • uxc-skill-creator: templates and workflow guidance for building new UXC-based skills

Install Skills

Use the skill folder name as the skill id for both npx skills and ClawHub.

Install from this repository using npx skills:

# Install the shared execution layer only
npx -y skills@latest add holon-run/uxc --skill uxc --agent codex -y

# Install any selected bundle of skills from this repo
npx -y skills@latest add holon-run/uxc \
  --skill uxc \
  --skill slack-openapi-skill \
  --skill discord-openapi-skill \
  --skill bitquery-graphql-skill \
  --agent codex -y

Install published skills from ClawHub:

# Install the shared execution layer only
clawhub --workdir ~/.openclaw --dir skills install uxc

# Install any selected published skill by its folder/slug name
clawhub --workdir ~/.openclaw --dir skills install slack-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install chrome-devtools-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install defillama-openapi-skill

See docs/skills.md for the complete publish log and maintenance rules.

Output and Help Conventions

UXC is JSON-first by default. Use --text (or --format text) when you want human-readable CLI output.

Examples:

uxc
uxc help
uxc <host> -h
uxc <host> <operation_id> -h
uxc --text help

Note: In endpoint routing, help is treated as a literal operation name, not a help alias.

Success envelope shape:

{
  "ok": true,
  "kind": "call_result",
  "protocol": "openapi",
  "endpoint": "https://petstore3.swagger.io/api/v3",
  "operation": "get:/pet/{petId}",
  "data": {},
  "meta": {
    "version": "v1",
    "duration_ms": 128
  }
}

For MCP tools/call, data may include content, optional structuredContent, and optional isError.

Failure envelope shape:

{
  "ok": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Field 'id' must be an integer"
  },
  "meta": {
    "version": "v1"
  }
}

Auth (Credentials + Bindings)

UXC authentication has two resources:

  • Credentials: secret material and auth type
  • Bindings: endpoint matching rules that select a credential

For non-OAuth credentials, use two auth tracks:

  • simple auth: keep using --secret, --secret-env, or --secret-op
  • complex auth: use repeatable --field <name>=<source> plus optional binding-level --signer-json

Example:

uxc auth credential set deepwiki --auth-type bearer --secret-env DEEPWIKI_TOKEN
uxc auth credential set deepwiki --secret-op op://Engineering/deepwiki/token
uxc auth binding add --id deepwiki-mcp --host mcp.deepwiki.com --path-prefix /mcp --scheme https --credential deepwiki --priority 100

# api_key supports configurable header names and templates
uxc auth credential set okx --auth-type api_key --secret-env OKX_ACCESS_KEY --api-key-header OK-ACCESS-KEY
uxc auth credential set okx-advanced --auth-type api_key --header "OK-ACCESS-KEY={{secret}}" --header "OK-ACCESS-PASSPHRASE={{env:OKX_PASSPHRASE}}"

# multi-field auth for signed APIs
uxc auth credential set binance --auth-type api_key --field api_key=env:BINANCE_API_KEY --field secret_key=env:BINANCE_SECRET_KEY
uxc auth binding add --id binance-account --host api.binance.com --path-prefix /api/v3 --scheme https --credential binance --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' --priority 100

For --secret-op, secret resolution happens at request runtime through daemon execution. Ensure daemon has usable 1Password auth context (for example OP_SERVICE_ACCOUNT_TOKEN), and restart daemon after env changes.

OAuth for MCP HTTP is supported (device code, client credentials, authorization code + PKCE). See docs/oauth-mcp-http.md for full workflows.

Docs Map

Contributing

Contributions are welcome.

License

MIT License - see LICENSE.