# Bezalel developer docs

Connect any MCP-speaking agent to the Bezalel capability plane. Two
values are all a consumer needs: the MCP URL and a bearer token.

## Endpoint and auth

- MCP endpoint (Streamable HTTP): `https://bezalel.sh/api/mcp`
- Auth: `Authorization: Bearer <token>` — tokens look like `bzl_…` and are
  minted per agent by the plane's owner in the dashboard at https://bezalel.sh/dashboard.
- `https://bezalel.sh/api/*` proxies same-origin to the plane server; the setup
  instructions below always carry the plane's current direct URL as well.

## The one-paste setup

Paste one prompt into your agent (the dashboard's Connect page shows it
pre-filled with your token):

> Connect yourself to my Bezalel capability plane: fetch https://bezalel.sh/api/setup
> and follow the instructions. Your token is <TOKEN>.

The setup instructions are a markdown document, kept current by the
plane itself, with exact registration commands for every harness:

- **Claude Code** — `claude mcp add --scope user --transport http bezalel <MCP_URL> --header "Authorization: Bearer <TOKEN>"`
- **Codex CLI** — an `[mcp_servers.bezalel]` block in `~/.codex/config.toml`
- **Cursor** — an entry in `.cursor/mcp.json` with the URL and auth header
- **OpenClaw** — `openclaw mcp add bezalel --transport streamable-http --url <MCP_URL> --header "Authorization: Bearer <TOKEN>"`
- **eve** — mount the `@goshen/bezalel` extension with the plane URL and token

## Verify a connection

Reconnect first — MCP clients cache tool lists per session. Then call
the `health__check` tool: it reports the agent identity and the scopes
the token grants. `tools/list` shows only the tools those scopes can
call, and every call is re-checked server-side.

## Scopes

Tokens carry capability-domain scopes. A denied call returns a
descriptive error naming the missing scope.

- `health` — Connectivity check; reports the agent identity and granted scopes.
- `memory` — Long-term memory shared across every agent: search, add, profile, forget.
- `email` — Real inboxes the plane owns: send, reply, read messages and threads.
- `imessage` — Texting on the owner's paired line: messages, attachments, polls, reactions.
- `finance` — The spend ledger plus linked bank accounts and transaction sync.
- `cards` — Hard-capped virtual cards for agent purchases — coming soon; calls answer "not configured" until launch.
- `computer` — The cloud desktop: shell, screenshots, vision-driven tasks.
- `sandbox` — Disposable code-execution microVMs: exec, files, lifecycle.
- `connectors` — Hundreds of third-party apps behind managed OAuth: discover and execute.

## Skill playbooks

Per-domain usage playbooks (Agent Skills, SKILL.md convention) are served
by the plane:

- `GET https://bezalel.sh/api/skills` — one skill name per line
- `GET https://bezalel.sh/api/skills/<name>` — that skill's SKILL.md

## Service status

`GET https://bezalel.sh/api` returns live JSON: plane version, uptime, and which
capability domains are configured on this deployment.

## Self-hosting

The plane is a single long-lived Node process, deployable from the
repository Dockerfile to any container host. Each deployment serves one
owner, with their own database and provider credentials.

## For agents

- Overview and link index: https://bezalel.sh/llms.txt
- Every page on this site serves markdown via `Accept: text/markdown`
  or by appending `.md` to the path (this page: https://bezalel.sh/docs.md).