██╗   ██╗██╗██╗   ██╗ ██████╗ ██╗██████╗
██║   ██║██║██║   ██║██╔═══██╗██║██╔══██╗
██║   ██║██║██║   ██║██║   ██║██║██║  ██║
██║   ██║██║╚██╗ ██╔╝██║   ██║██║██║  ██║
╚██████╔╝██║ ╚████╔╝ ╚██████╔╝██║██████╔╝
 ╚═════╝ ╚═╝  ╚═══╝   ╚═════╝ ╚═╝╚═════╝

npx uivoid create my-app

OpenAPI spec  →  Selected tools  →  Hosted MCP URL  →  Your agent

UIvoid discovers your API's OpenAPI document and maps selected operations into scoped MCP tools. It hosts the gateway, so you can connect an agent without writing and deploying a separate MCP server.

Why UIvoid?

• Reuse your API. Map OpenAPI operations into MCP tools without maintaining a second set of tool definitions.
• Choose what agents can call. Select individual tools, with read, write, and destructive scopes. DELETE operations start unselected in the interactive review.
• Get a hosted MCP URL. Connect a client that supports authenticated remote MCP servers, including compatible Claude and OpenAI clients.
• Automate setup. Use an explicit tool allowlist and JSON output in scripts, or let your coding agent follow the bundled skill.

Quick start

You need Node.js 20+, a UIvoid account with an owner or admin role in an organization, and an API reachable by UIvoid with an accessible OpenAPI JSON document.

npx uivoid create my-app

1. Sign in through the browser when prompted.
2. Enter your deployed API's base URL. The CLI looks for openapi.json, api/openapi.json, or swagger.json.
3. Review the discovered operations and choose which to expose.
4. Add the returned MCP URL to your remote MCP client and complete organization login. Verify the connection by calling a selected read tool.

Illustrative output (your hostname and tool count will differ):

✓ Created my-app
✓ Found OpenAPI document at https://api.example.com/openapi.json
✓ Mapped 9 scoped tools
✓ MCP server active

Ready  https://my-app.uivoid.app/mcp
Auth: organization login · 9 tools mapped

For an API with a bearer token and a known specification URL:

# Set BASE_URL, OPENAPI_URL, and API_TOKEN to your API's values first.
# Replace the tool names with operations from your specification.
npx uivoid create my-app \
  --base-url "$BASE_URL" \
  --openapi "$OPENAPI_URL" \
  --auth-key "$API_TOKEN" \
  --include list_products,get_product

Want a sample API to connect? The inventory walkthrough includes a runnable API, an OpenAPI document, and example agent prompts.

Try the live demo

Launch Ledgerly Ops ↗ — a demo backoffice for a fictional subscription billing company. Browse sample customers, subscriptions, invoices, payments, and support tickets.

The browser demo shows the application and its sample data. To connect its API through your own UIvoid MCP project, you also need the demo API's separate x-api-key credential and a UIvoid account. The browser password is not the API key.

View the demo's OpenAPI document · Run your own inventory example

Before you connect

• Hosting: the CLI is MIT licensed; the MCP gateway runs on the UIvoid service and requires an account. Check service availability and terms in the portal.
• API access: a localhost-only API needs a separately configured public deployment or network path that UIvoid can reach.
• Specification support: the current mapper reads JSON over HTTP, supports GET/POST/PUT/PATCH/DELETE, and expects inline schemas. It does not resolve $ref schemas or load YAML/local files. Outbound API credentials are not attached when fetching the specification.
• Authentication: organization login protects the MCP endpoint. Your API's outbound credential is configured separately. If none is supplied, the CLI generates one and displays it once; your API must accept it, or tolerate the header if public.
• Scopes: defaults come from HTTP methods. Review actual behavior before exposing operations; a POST can also delete data.

If this is useful, star the repository to help other developers find it. Tried it on your API? Report a problem or suggest an improvement.

Commands

npx uivoid login
npx uivoid whoami [--json]
npx uivoid org list [--json]
npx uivoid org use <slug>
npx uivoid team list [--org SLUG] [--json]
npx uivoid team invite <email> [--role member|admin|owner] [--org SLUG] [--json]
npx uivoid team revoke <email-or-invite-id> [--org SLUG]
npx uivoid team role <email> <owner|admin|member> [--org SLUG]
npx uivoid team remove <email> [--org SLUG] [--yes]
npx uivoid team leave [--org SLUG] [--yes]
npx uivoid invite accept <link> [--use] [--json]
npx uivoid create [name] [--base-url URL] [--openapi URL] [--yes]
npx uivoid create [name] [--auth-key VALUE] [--auth-header "Header-Name:value"]
npx uivoid create [name] [--include tool1,tool2,...] [--exclude-destructive] [--json]
npx uivoid create [name] [--org SLUG] --no-discover
npx uivoid credentials <project> [--auth-key VALUE] [--auth-header "Header-Name:value"]
npx uivoid prompt
npx uivoid skill [--install]
npx uivoid logout

create discovers /openapi.json, /api/openapi.json, or /swagger.json. Use --openapi for another location. GET operations default to read, POST/PUT/PATCH to write, and DELETE to destructive; the interactive review keeps destructive tools unselected by default.

For CI, provide UIVOID_TOKEN and one non-interactive endpoint-selection flag: --yes (accept everything, including destructive), --include tool1,tool2,... (an explicit allowlist), or --exclude-destructive (everything except DELETE-derived tools). If none of those is passed and the CLI can't detect a real interactive terminal — or --json is set, since an interactive prompt would otherwise write to stdout ahead of the JSON line — it prints a clear error explaining which flag to add, instead of hanging waiting for input. UIVOID_API_URL and UIVOID_PORTAL_URL override the production services for local development. Credentials are stored at ~/.config/uivoid/config.json with mode 0600.

Teams and organizations

An account can belong to several organizations. Commands that act on one take --org <slug>; without it they use the default set by uivoid org use <slug> (or your only organization). uivoid whoami shows the current default and your role.

Roles: owner (everything, including roles and owner invites), admin (manage projects, keys and credentials; invite members and admins) and member (read-only in the control plane; can use the organization's MCP servers with read and write tools, but not destructive ones).

uivoid team invite [email protected] --role admin prints a one-time invite link. Send it yourself — it works only for that email address and expires after 7 days; inviting the same address again replaces it. The teammate runs uivoid invite accept <link> (or opens the link in the portal).

Outbound credentials

The MCP tools uivoid generates call back into your existing API, and that API usually expects its own credential. Pass --auth-key <value> (sent as Authorization: Bearer <value>) or --auth-header "Header-Name:value" (a custom header) at create time, or set/replace it later without recreating the project:

npx uivoid credentials my-app --auth-key sk_live_...

If you pass neither flag at create time, uivoid generates a credential for you and prints it once — save it immediately, since it isn't shown again.

Hosted MCP domain and existing API hosting

Each project gets a dedicated https://<project>.uivoid.app/mcp subdomain. UIvoid hosts the MCP gateway; your existing API can stay self-hosted wherever UIvoid can reach it. The CLI does not purchase a domain or deploy the gateway onto your infrastructure.

Manage projects at portal.uivoid.app. In addition to static outbound credentials, npx uivoid oauth-config --help describes per-user OAuth/JWT passthrough configuration. Register the callback URL printed by that command with your identity provider and test login before treating the integration as ready.

Agent prompt and skill

npx uivoid prompt prints a provider-neutral prompt that Claude, Codex, or another coding agent can use to prepare the current project and run the integration.

The UIvoid skill guides API discovery, missing BASE_URL questions, endpoint selection, dedicated subdomain provisioning, authentication, and verification. Install the GitHub version with the skills CLI:

npx skills add corrideluca/uivoid-cli --skill uivoid

The npm package also ships an optional SKILL.md for clients that support agent skills. Its bundled copy follows the installed npm release; use the GitHub command above for the latest skill. Install it into Codex's personal skills directory with:

npx uivoid skill --install

Backend contract

The CLI uses these control-plane endpoints:

• GET /api/auth/me
• GET /api/projects
• POST /api/projects (accepts organization_id)
• POST /api/projects/:id/keys
• POST /api/projects/:id/tools
• PATCH /api/projects/:id/credentials
• GET /api/orgs/:id/members, PATCH|DELETE /api/orgs/:id/members/:userId
• GET|POST /api/orgs/:id/invitations, DELETE /api/orgs/:id/invitations/:inviteId
• POST /api/invitations/:token/accept

Browser login uses /cli/auth?callback=...&state=... to return a revocable personal access token to a loopback callback. uivoid login --token and UIVOID_TOKEN are also available for non-interactive environments.

Development

npm install
npm test
npm run build
node dist/cli.js --help

Hosted databases

Requires a backend configured with hosted PostgreSQL support. Database commands
output JSON and accept --project <subdomain-or-UUID> and --token (or your stored
login / UIVOID_TOKEN). Database credentials stay on the backend.

uivoid create sowe --no-discover --json
uivoid db create inventory --project sowe
uivoid db table create products --project sowe --db inventory --schema products.schema.json
uivoid db expose products --project sowe --db inventory --operation insert --name add_product --path /products --description "Create a product"
uivoid db expose products --project sowe --db inventory --operation list --name list_products --path /products --description "List products"
uivoid db call add_product --project sowe --args '{"data":{"name":"Book","stock":5}}'
uivoid db call list_products --project sowe
uivoid db size inventory --project sowe

products.schema.json contains column definitions:

{"name":{"type":"text","required":true},"stock":{"type":"integer"}}

Supported types: text, integer, number, boolean. The server creates an id UUID.
Operations are list, get, insert, update, delete. Get/delete require
{"id":"<UUID>"}; update requires {"id":"<UUID>","data":{...}}. Deleting a row
requires the destructive scope. Use --file arguments.json for sensitive values.
Reads/deletes stay available at the hardcoded 500 MB limit; growth is rejected.

Use db list and db table list --db <name> to discover resources. Database/table
creation can be retried with the same name/definition. Row inserts are not
idempotent: inspect results before retrying an ambiguous failure. Unrestricted SQL,
column type changes, table rename/drop, defaults, indexes and custom constraints
are not supported. Existing tools API endpoints manage endpoint descriptions,
activation and removal.

Change an existing table without creating a replacement or re-exposing its tools:

uivoid db table add-column products priority --db inventory --type text --project sowe
uivoid db table set-required products priority --db inventory --required true --project sowe
uivoid db table rename-column products priority importance --db inventory --confirm priority --project sowe
uivoid db table drop-column products importance --db inventory --confirm importance --project sowe

All commands accept a table name or UUID. Rename/drop never prompt interactively:
missing --confirm is a CLI error; an incorrect confirmation shows the backend
error. The existing database quota applies to schema operations.

Existing endpoint IDs, descriptions and routes are preserved, and their input
schemas are regenerated automatically. Re-list MCP tools afterwards; clients
that cache schemas may need to reconnect. Identical add-column retries are safe;
a conflicting definition is rejected. After an interrupted schema change, retry
the same command to reconcile metadata with PostgreSQL before doing other work.