13 releases (breaking)

new 0.11.1	Mar 11, 2026
0.10.0	Mar 8, 2026

#293 in Development tools

MIT license

1.5MB
31K SLoC

UXC

Universal X-Protocol CLI

English | 简体中文

UXC is a universal X-protocol CLI that lets you discover and invoke OpenAPI, gRPC, GraphQL, MCP, and JSON-RPC interfaces directly from a URL.

It turns remote schema-exposed interfaces into executable command-line operations without SDKs, code generation, or endpoint pre-registration.

What Is UXC

Modern services increasingly expose machine-readable interface metadata. UXC treats those schemas as runtime execution contracts:

Discover operations from a host
Inspect operation inputs/outputs
Execute operations with structured input
Return deterministic JSON envelopes by default

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

Why It Exists

Teams and agents often need to interact with many protocol styles: OpenAPI, GraphQL, gRPC, MCP, and JSON-RPC.

Traditional workflows create repeated overhead:

language-specific SDK setup
generated clients that drift from server reality
one-off wrappers for each endpoint
large embedded tool schemas in agent prompts

UXC provides one URL-first CLI contract across protocols.

Why UXC Works Well With Skills

UXC is a practical fit for skill-based agents:

On-demand discovery and invocation, without preloading large MCP tool definitions into prompt context
Portable by endpoint URL and auth binding, not tied to per-user local MCP server names
Reusable as one shared calling interface across many skills

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 and endpoint bindings
Host shortcut commands via uxc link
Link-level default OpenAPI schema persistence via uxc link --schema-url
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:

flowchart LR
    A[User / Skill / Agent] --> B[UXC CLI]
    B --> C[Command Router]
    C --> D[Protocol Detector]
    D --> E[Adapter Layer]

    E --> E1[OpenAPI Adapter]
    E --> E2[gRPC Adapter]
    E --> E3[GraphQL Adapter]
    E --> E4[MCP Adapter]
    E --> E5[JSON-RPC Adapter]

    C --> F[Auth Resolver]
    F --> F1[Credential Sources<br/>literal / env / 1Password]
    C --> G[Schema + Response Cache]
    C --> H[JSON Envelope Output]

    E1 --> R[Remote Endpoints]
    E2 --> R
    E3 --> R
    E5 --> R
    E4 --> M1[MCP HTTP Endpoint]
    E4 --> M2[MCP stdio via Daemon]

    M2 --> D1[Daemon Process Registry]
    D1 --> D2[Reused stdio MCP Process]

This design keeps invocation UX 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 an execution interface for schema-exposed remote capabilities.

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.11.0

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.

Discover operations:

uxc petstore3.swagger.io/api/v3 -h

Inspect operation schema:

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

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> '{...}'

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

Core

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

Browser Automation

playwright-mcp-skill: run @playwright/mcp over MCP stdio through uxc

Knowledge and Docs

context7-mcp-skill: query up-to-date library documentation and examples
deepwiki-mcp-skill: query repository documentation and ask codebase questions

Workspace and Collaboration

notion-mcp-skill: operate Notion MCP workflows with OAuth-aware guidance
linear-graphql-skill: operate Linear issues, projects, and teams through GraphQL
discord-openapi-skill: operate Discord REST API via UXC and OpenAPI schema mapping

Crypto and Onchain Data

bitquery-graphql-skill: query Bitquery GraphQL for onchain trades, transfers, holders, balances, and market structure with OAuth client credentials
binance-web3-openapi-skill: query Binance Web3 token discovery, rankings, smart money, audits, and address positions through OpenAPI
binance-spot-openapi-skill: operate Binance Spot public market data and signed account/order flows through OpenAPI
okx-mcp-skill: query OKX MCP for token, market, wallet, and swap workflows
dune-mcp-skill: discover blockchain tables, run SQL, fetch results, and build charts via Dune MCP
thegraph-mcp-skill: discover subgraphs, inspect schemas, and execute GraphQL via The Graph Subgraph MCP bridge
thegraph-token-mcp-skill: query token, wallet, transfer, holder, and market data via The Graph Token API MCP
etherscan-mcp-skill: investigate addresses, token holders, and contracts via Etherscan MCP

Install Skills

Install from this repository using npx skills:

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

# Add browser and knowledge skills
npx -y skills@latest add holon-run/uxc --skill playwright-mcp-skill --skill context7-mcp-skill --skill deepwiki-mcp-skill --agent codex -y

# Add workspace skills
npx -y skills@latest add holon-run/uxc --skill notion-mcp-skill --skill linear-graphql-skill --skill discord-openapi-skill --agent codex -y

# Add crypto and onchain skills
npx -y skills@latest add holon-run/uxc --skill bitquery-graphql-skill --skill binance-web3-openapi-skill --skill binance-spot-openapi-skill --skill okx-mcp-skill --skill dune-mcp-skill --skill thegraph-mcp-skill --skill thegraph-token-mcp-skill --skill etherscan-mcp-skill --agent codex -y

Install published skills from ClawHub:

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

# Add browser and knowledge skills
clawhub --workdir ~/.openclaw --dir skills install playwright-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install context7-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install deepwiki-mcp-skill

# Add workspace skills
clawhub --workdir ~/.openclaw --dir skills install notion-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install linear-graphql-skill
clawhub --workdir ~/.openclaw --dir skills install discord-openapi-skill

# Add crypto and onchain skills
clawhub --workdir ~/.openclaw --dir skills install bitquery-graphql-skill
clawhub --workdir ~/.openclaw --dir skills install binance-web3-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install binance-spot-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install okx-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install dune-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install thegraph-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install thegraph-token-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install etherscan-mcp-skill

See docs/skills.md for install methods 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

Extended quickstart and protocol walkthroughs: docs/quickstart.md
Public no-key endpoints for protocol checks: docs/public-endpoints.md
Logging and troubleshooting with RUST_LOG: docs/logging.md
Auth credential secret sources (literal/env/op): docs/auth-secret-sources.md
Run daemon with service managers (systemd/launchd): docs/daemon-service.md
OpenAPI schema mapping and --schema-url: docs/schema-mapping.md
Skills overview and install/maintenance guidance: docs/skills.md
Release process: docs/release.md

Contributing

Contributions are welcome.

Development workflow and quality bar: CONTRIBUTING.md
CI and release flows: GitHub Actions

License

MIT License - see LICENSE.

Dependencies

~26–46MB
~646K SLoC