# Librebase

> Open-source Postgres app platform. Prefer the **hosted HTTP MCP** at https://app-stage.librebase.xyz/api/mcp. A human who already has a Librebase account must click Approve at https://app-stage.librebase.xyz/mcp/authorize. Do not paste MCP keys. Do not use accounts.x.ai.

## For AI agents
Two MCP surfaces exist. If you can POST JSON-RPC, use hosted HTTP. Only clone the repo for local stdio.

- Human + agent setup: https://app-stage.librebase.xyz/for-agents
- MCP documentation: https://app-stage.librebase.xyz/docs/mcp
- Measured benches (Postgres 16 artifacts, with caveats): https://app-stage.librebase.xyz/benchmark
- Hosted MCP: https://app-stage.librebase.xyz/api/mcp
- Discovery: https://app-stage.librebase.xyz/.well-known/mcp.json
- Approve page: https://app-stage.librebase.xyz/mcp/authorize
- Agent poll (not approve): POST https://app-stage.librebase.xyz/api/mcp/device/token with deviceCode
- Console: https://app-stage.librebase.xyz

## Hosted MCP (SaaS — use this)
POST JSON-RPC to https://app-stage.librebase.xyz/api/mcp. Keep the `mcp-session-id` response header on later calls. Hosted sessions persist in the Librebase control plane and survive a Studio rebuild; the JSON-RPC body never includes the agent token.

SaaS MCP is JSON-RPC at https://app-stage.librebase.xyz/api/mcp (GET https://app-stage.librebase.xyz/api/mcp for discovery). Alias: https://app-stage.librebase.xyz/mcp. 1. tools/call auth_status. 2. If unauthenticated, tools/call auth_start. Pass access=read|write and resources=[projects,keys,logs,instances,hosts,members] for the permissions you need; omit them to request full read/write on every area. The payload includes showToHuman — your next message to the human MUST be that URL on its own first line, then the userCode. Do not bury them in a status report. 3. Open that URL (https://app-stage.librebase.xyz/mcp/authorize) in the browser, review the requested permissions, and click Approve. 4. tools/call auth_poll. Send the mcp-session-id response header back, or pass deviceCode. Repeat while status is waiting_for_user (ok:true). That is not a failure and does not need an MCP key. Hosted sessions persist across Studio rebuilds; the token is never returned in JSON-RPC. 5. Write path (human Approve required): org_whoami → host_list → instance_create(hostId) → instance_launch → project_create → sqlite_import or supabase_import (preview then write, project DB only) → knowledge_bootstrap then knowledge_put/search (durable project notes in the project DB) → app_deploy (appId template or image) → instance_health → report URL. Hermes dogfood (LIB-55): hermes_bootstrap → hermes_gap_upsert → hermes_sync_linear (Linear key stays on the server). Read-only tokens must auth_start again with access=write. auth_logout drops the session token. Do not paste an MCP key into chat or config for interactive use. Do not send the operator to accounts.x.ai or Grok OAuth. Do not call admin_login / admin_setup on the hosted SaaS MCP.

```json
{
  "mcpServers": {
    "librebase": {
      "url": "https://app-stage.librebase.xyz/api/mcp"
    }
  }
}
```

Auth tools: `auth_status`, `auth_start`, `auth_poll`, `auth_logout`. Hosted clients should use `auth_start`; `auth_login` remains only as a legacy compatibility alias.
After `auth_start`, paste `showToHuman` as your next chat message: the URL on the first line, then the user code. Do not bury them.
After login: `org_whoami`, `project_list`, `project_create`, `instance_*` (pass `hostId` on create), `host_*`, `app_list` / `app_deploy` / `app_remove` (todo-app or crm-app on a host VM), `member_*`, `key_*`, `auth_provider_*`, `storage_bucket_*` / `storage_object_*`, `function_list` / `function_upsert` / `function_invoke` (project-instance functions: 32 KiB source, 2 second timeout, no imports, not a Deno global edge), `generate_embedding` / `semantic_search`, `run_sql` / `describe_table` / `list_tables` / `insert_row` / `update_rows` / `delete_rows` / `schema_migrate` (project instance, not the SaaS database), `log_list` / `log_search`, `billing_get` / `billing_invoice_list` (no stored Stripe invoices), `eval_list` / `eval_run` (unpublished without a trace), `sqlite_import` / `supabase_import`, `knowledge_bootstrap` / `knowledge_put` / `knowledge_search` / `knowledge_get` / `knowledge_link` / `knowledge_backlinks` (project-DB knowledge; never a second vendor), `hermes_bootstrap` / `hermes_gap_list` / `hermes_gap_upsert` / `hermes_sync_linear`.
This hosted server does **not** expose `migration_apply` / `sql_execute` / `table_list` / `project_delete` — those stay on the stdio MCP. `CREATE EXTENSION` stays fail-closed. Hermes findings, competitor rows, files, function source, and vectors stay on the project instance, never the SaaS DB. Linear API keys are never returned.

## Local stdio MCP (repo clone only)
Local stdio MCP (clone of mcp/, python3 -m librebase_mcp): call auth_status, then auth_start. auth_start returns a user code + /mcp/authorize URL and polls until Approve. The token is stored in the OS keychain (xyz.librebase.mcp), never returned to the model. If the poll times out, call auth_start again. Do not set LIBREBASE_MCP_KEY except in CI.

```json
{
  "mcpServers": {
    "librebase": {
      "command": "python3",
      "args": ["-m", "librebase_mcp"],
      "env": {
        "LIBREBASE_ADMIN_URL": "https://app-stage.librebase.xyz/api/admin-proxy",
        "LIBREBASE_CONSOLE_URL": "https://app-stage.librebase.xyz"
      }
    }
  }
}
```

Stdio extras: `oauth_setup`, `run_sql`, `describe_table`, `list_tables`, `insert_row`, `update_rows`, `delete_rows`, `schema_migrate`, `migration_apply`, `migration_list`, `sql_execute`, `table_list`, `project_delete`. Stdio also has the same storage / function / embedding tools as hosted.

## Security
- Never set `LIBREBASE_MCP_KEY` for interactive use (CI override only).
- Secrets are KMS-sealed. Agent tokens are user-bound and revocable.
- Project end-user GitHub/Google sign-in is `auth_provider_upsert`, not MCP login.