uivoid-cli MCP server
Commit Oct 22, 2026Converts OpenAPI specifications into hosted MCP servers with scoped tools for AI agents.
Also known as corrideluca/uivoid-cli
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 22, 2026
- License
- MIT
What is uivoid-cli MCP?
uivoid-cli converts OpenAPI specifications into hosted MCP servers with scoped tools for AI agents.
Summary generated from the project's README
About uivoid-cli MCP server
Converting existing OpenAPI specifications into hosted MCP servers is the primary function of uivoid-cli. This tool allows developers to turn their existing APIs into scoped tools for AI agents without writing or deploying a new MCP server. By discovering an OpenAPI JSON document, the CLI maps specific operations into tools that can be used by remote clients like Claude or OpenAI.
Users interact with the service via a command line interface using Node.js 20 or higher. The setup process involves signing into a UIvoid account, providing a base URL for the API, and selecting which operations to expose. The system categorizes tools into read, write, and destructive scopes, with DELETE operations unselected by default during the interactive review.
Once configured, the service provides a dedicated hosted URL for the MCP gateway. Developers can manage outbound credentials, such as bearer tokens or custom headers, to ensure the agent can securely communicate with the original API. The tool also supports automated setup through an explicit tool allowlist or by using a bundled agent skill.
What you can do with it
- 1Expose API operations to agentsA developer can transform an existing OpenAPI specification into a set of scoped tools for an AI client.
- 2Control agent tool permissionsYou can selectively choose which API operations are available to an agent and assign them specific scopes.
- 3Securely connect remote clientsConnect compatible AI clients to a hosted MCP endpoint using organization-based authentication.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecorrideluca/uivoid-cli is public and reachablegithub.com/corrideluca/uivoid-cli ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-22github.com/corrideluca/uivoid-cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubThe uivoid CLI
Your API. Your tools. One MCP endpoint.
Turn your OpenAPI API into a hosted MCP server. Choose the operations. Connect your agent. Keep your API where it is. No API yet? Start from zero with a free hosted Postgres database.
Quick start · Live demo · Agent skill · Commands
npx uivoid create my-app
Or paste the setup prompt (npx uivoid prompt, or the copy button on uivoid.app) into your coding agent and let it do the setup.
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
- Sign in through the browser when prompted.
- Enter your deployed API's base URL. The CLI looks for
openapi.json,api/openapi.json, orswagger.json. - Review the discovered operations and choose which to expose.
- 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.
| Demo login | Value |
|---|---|
| Username | admin |
| Password | ledgerly-demo |
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
$refschemas 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 teammate@company.com --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/meGET /api/projectsPOST /api/projects(acceptsorganization_id)POST /api/projects/:id/keysPOST /api/projects/:id/toolsPATCH /api/projects/:id/credentialsGET /api/orgs/:id/members,PATCH|DELETE /api/orgs/:id/members/:userIdGET|POST /api/orgs/:id/invitations,DELETE /api/orgs/:id/invitations/:inviteIdPOST /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
| Change | Rule |
|---|---|
| Add optional column | Allowed; existing rows get NULL |
Add required column (add-column --required) |
Only when the table is empty |
Make optional (set-required --required false) |
Allowed |
Make required (set-required --required true) |
Only when no row contains NULL in that column |
| Rename column | Requires --confirm <current-name>; breaks agents using the old name |
| Drop column | Requires --confirm <name>; permanently deletes that column's data; cannot drop the last column |
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.
Publish to the MCP Registry
List a project in the official MCP Registry as app.uivoid/<project>, so other people's agents and MCP directories can find it. uivoid reviews new listings first; edits to a published listing go live directly. Only active projects with public or OAuth passthrough auth and at least one tool can be listed.
npx uivoid publish my-app --title "My App" --description "Manage orders and customers"
npx uivoid publish my-app --status
npx uivoid unpublish my-app
uivoid-cli MCP questions
How do I turn my API into an MCP server?
You can use the command npx uivoid create my-app to discover your OpenAPI document and map operations into scoped MCP tools.
Can I choose which API operations are exposed to the agent?
Yes, you can select individual tools and define scopes such as read, write, or destructive.