kaiva BRIDGE
reference

CLI & Management API

One command, or the bearer-key REST API underneath it. Everything the console does: create servers, expose tools, publish, issue keys, test-call a tool, read the audit log, and release a held contract change. Base URL https://api.kaiv.ai/api/bridge/v1

The full description is an OpenAPI 3.1 spec: kaiv.ai/bridge/openapi.json. Bridge can turn it into an MCP server too.

Authentication

Mint a management key in the console (Access → New key, admin or owner role). Management keys are refused by the MCP gateway, and gateway keys are refused here, the two credential types are never interchangeable. A management key can mint gateway keys, but never another management key.

request
curl https://api.kaiv.ai/api/bridge/v1/servers \
  -H "Authorization: Bearer kv_mgmt_..."
Endpoints
GET/serversList servers in the workspace
POST/serversCreate a server, { name, sourceType: openapi|graphql|postgres|mysql|sqlserver|mcp, sourceUrl, auth? }
GET/servers/{id}Server detail with its tools and input schemas
DELETE/servers/{id}Delete a server
POST/servers/{id}/introspectRead the source and register its tools
PATCH/servers/{id}/tools/{toolId}Expose or hide one tool, { exposed: true|false }
POST/servers/{id}/publishPublish, the endpoint goes live
POST/servers/{id}/tools/{toolId}/invokeTest-call a tool through the real governed path (audited)
POST/documents/serversCreate a documents server, { name }
POST/documents/servers/{id}/documentsUpload one file (multipart, field file); the same file name replaces that document
GET/documents/servers/{id}Its documents and how each is getting on (queued, page n of m, ready, failed)
GET/keysList gateway keys
POST/keysMint a gateway key, { label, serverIds: [id], policyId? } (shown once)
DELETE/keys/{id}Revoke a key
GET/policiesList policies
POST/policiesCreate a policy, { name, subjects, rules }
GET/audit?limit=100Audit log, newest first
GET/metrics?range=24hWorkspace KPIs, 1h · 24h · 7d · 30d
Every request is scoped to the key's workspace. Errors return { error, message } with the HTTP status.
CLI

The same API, one command. Zero dependencies, Node 18+. It uses the runtime's built-in fetch rather than pulling in an HTTP library, so there is nothing to install and nothing to audit. The CLI is open source under MIT: github.com/ai-kaiva/bridge.

Try it with no account
terminal
# A public spec: a server for 72 hours, a key, and a claim link to keep it
npx @kaiva/bridge try --openapi https://petstore3.swagger.io/api/v3/openapi.json
Sign in
terminal
# Console -> Keys & access -> Issue a key -> Management
export KAIVA_BRIDGE_TOKEN=kv_mgmt_...
npx @kaiva/bridge servers             # verify the token, read-only
Create a server
terminal
# An API
npx @kaiva/bridge push my-api --openapi https://api.example.com/openapi.json --read-only
# → LIVE  https://api.kaiv.ai/api/bridge/mcp/my-api-a1b2c3d4

# A database: the connection string comes from stdin, not the command line
printf %s "$DATABASE_URL" | npx @kaiva/bridge push shop-db --mysql --secret-stdin --read-only

# Documents: files or a folder; waits until each is read
npx @kaiva/bridge push handbook --docs ./policies
Test it and connect your agent
terminal
npx @kaiva/bridge tools <server-id>   # ids, names, required args
npx @kaiva/bridge invoke <server-id> findPetsByStatus --args '{"status":"available"}'
npx @kaiva/bridge key <server-id> --label claude-code --replace   # gateway key for agents
Keep it current
terminal
npx @kaiva/bridge introspect <server-id>   # re-read the source; reports anything held
npx @kaiva/bridge promote <server-id>      # publish a held contract change
npx @kaiva/bridge reject <server-id>       # discard it, restore what is served
npx @kaiva/bridge logs --limit 20          # tail the audit log
Help
terminal
npx @kaiva/bridge --help              # every command and flag
push also accepts --mcp <url> to wrap an existing MCP server, --postgres <conn>, --mysql <conn> or --sqlserver <conn> for a database (MySQL and MariaDB use --mysql), and --graphql <endpoint> for a GraphQL API. Every setup command is safe to run again: push reuses a server with the same name, and key --replace revokes the earlier key with that label. --read-only exposes only operations that read. A database with a self-signed certificate takes --ca-file <pem>, or --no-verify-tls to connect without checking it. --json prints one result for scripts and agents. Other commands: publish · metrics · revisions · auto-publish. invoke takes a tool name or id, run tools to see both. introspect exits 3 when a contract change is held, so a pipeline stops rather than reporting success on tools that are not live yet.push creates and publishes a live server, so start with servers if you only want to check your token.
Let your coding agent set it up

Install the setup skill, then ask Claude Code to connect your database or API. It creates the server, makes a key, adds it to your client and confirms with a first tool call. It asks you before connecting without a certificate check or turning on operations that write.

terminal
npx @kaiva/bridge skill install        # adds it to ~/.claude/skills
# then ask: "connect my database to Claude Code with Kaiva Bridge"
Examples

Runnable scripts, safe to run again: