# Claimable Kaiva Bridge

You need an MCP server for a public API and no human is signed in to Kaiva Bridge. Create
one now, with no account. A human claims it later if they want to keep it.

This file is https://kaiv.ai/bridge/auth.md. The full setup guide, including databases, documents
and signed-in accounts, is https://kaiv.ai/bridge/SKILL.md.

If `KAIVA_BRIDGE_TOKEN` is set, or `npx -y @kaiva/bridge whoami` prints a workspace, there is
an account: use it (see SKILL.md) and stop. "not signed in" means there is no account; do not
run `login` on this path, because it needs the human.

This path is for a public REST API described by an OpenAPI or Swagger spec, or by a docs page
that publishes one. A database, documents, a GraphQL API or a private API needs an account.

## Provision

### CLI

```bash
npx -y @kaiva/bridge try --openapi https://api.example.com/openapi.json --json
```

`--openapi` takes the spec's link or the API's docs page; Bridge follows a docs page to the
spec it publishes. Use `--spec-file ./openapi.yaml` for a local spec and `--name short-name`
to name the server.

### REST

```http
POST https://api.kaiv.ai/api/bridge/claimable
Content-Type: application/json

{"specUrl": "https://api.example.com/openapi.json", "name": "my-api"}
```

Send `"spec": "<the spec text>"` instead of `specUrl` for a spec you have locally (900 KB at
most). `name` is optional. Never send a credential: a key, a password or a link carrying one
is refused.

Created returns 201. Keep:

- `mcpUrl`: the server's address.
- `apiKey`: shown once. Send it as `Authorization: Bearer <apiKey>`. It works for this one
  server only. Store it like any secret; do not print it in your reply.
- `claimUrl`: for the human. Treat it like a secret too: whoever opens it can take the server.
- `expiresAt`: the server is deleted then if nobody claimed it.
- `tools`: the tools it offers, each a GET operation of the spec.

Any other status: stop and show the `message` to the human as it is. The codes:

| Status | `error` | Meaning |
|---|---|---|
| 400 | `spec_required`, `spec_url_invalid` | Send one of `specUrl` (http or https) or `spec` |
| 400 | `credentials_not_accepted` | A credential was sent; use a public spec |
| 409 | `claimable_duplicate` | The same spec was sent a moment ago; wait a few seconds |
| 413 | `spec_too_large` | Send the spec's link instead of its text |
| 422 | `no_read_tools` | The spec has no GET operations; this path needs at least one |
| 429 | `rate_limited` | 5 servers an hour from one address; wait, or the human signs up |
| 503 | `claimable_busy`, `claimable_interrupted`, `claimable_disabled` | Try again later, or the human signs up at app.kaiv.ai |

`GET https://api.kaiv.ai/api/bridge/claimable` returns the same rules as JSON.

## Use

Add `mcpUrl` to the AI client with the header `Authorization: Bearer <apiKey>`. Claude Code:

```bash
claude mcp add --transport http my-api <mcpUrl> --header "Authorization: Bearer <apiKey>"
```

Cursor (`~/.cursor/mcp.json`; add this entry, keep the others):

```json
{ "mcpServers": { "my-api": { "url": "<mcpUrl>", "headers": { "Authorization": "Bearer <apiKey>" } } } }
```

A client usually needs restarting (Claude Code: `/mcp`) before it lists new tools.

Limits before a claim: GET operations only, at most 40 tools, 500 tool calls, 25 MB of
answers, 72 hours from creation. A call past a limit is refused with a message saying so.

## Claim

Give the human the `claimUrl` and say what it does: they sign up or sign in (free, no card),
and the server moves into their workspace at the same address, under their plan's limits.
After that they can add the API's own key and switch on other operations.

At claim your `apiKey` stops working. Tell the human to connect you again from the server's
Connect tab in the console (https://app.kaiv.ai/bridge/app).

A claim link that was already used answers "already claimed"; an expired one answers that
the server expired. Then create a new server.