# Connect your agent

Nobody pastes a secret key into the agent's chat. Pick one:

- **Browser sign-in (MCP OAuth).** Clients that support MCP authorization
  (Claude Code, Cursor, VS Code) open the Scribase consent page the first time
  they connect; add the server without a header.
- **`scribase login`.** The agent runs it, shows you a link and a code, and you
  approve in the browser; it receives its own scoped, expiring token and keeps
  it in the keychain. See [Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md).
- **An agent token in `SCRIBASE_ACCESS_TOKEN`**, for clients that need a
  header. See [Tokens and safety](https://docs.scribase.com/docs/agents/safety.md) for which token to give
  an agent. Keep it in your shell environment or secret manager, never in a
  committed file.

## Remote MCP server

The hosted MCP endpoint is `https://api.scribase.com/mcp` (streamable HTTP,
bearer token). There is nothing to install. Each session gets its own scratch
database for the schema tools, destroyed when the session ends, so one
agent's experiments never reach another's.

### Claude Code

```sh
claude mcp add --transport http scribase https://api.scribase.com/mcp
```

Claude Code opens the Scribase consent page in your browser the first time it
connects. With a token instead:

```sh
claude mcp add --transport http scribase https://api.scribase.com/mcp \
  --header "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN"
```

Or install the Scribase plugin, which bundles the MCP server with the
`scribase` and `scribase-safe-change` skills. From a checkout of the Scribase
repository:

```sh
claude plugin marketplace add ./agents/plugin
claude plugin install scribase@scribase
```

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "scribase": {
      "url": "https://api.scribase.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SCRIBASE_ACCESS_TOKEN}" }
    }
  }
}
```

Add the project rule: copy `agents/templates/.cursor/rules/scribase.mdc` to
`.cursor/rules/`.

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.scribase]
url = "https://api.scribase.com/mcp"
bearer_token_env_var = "SCRIBASE_ACCESS_TOKEN"
```

Append `agents/templates/AGENTS.md` to your project's `AGENTS.md`.

### Windsurf

`~/.codeium/windsurf/mcp_config.json`, the same as Cursor with `serverUrl`
instead of `url`. Copy `agents/templates/.windsurf/rules/scribase.md` to
`.windsurf/rules/`.

## Local stdio server

Build it once from the repository (Rust 1.85+):

```sh
cargo install --locked --path crates/mcp
```

Your editor starts `scribase-mcp` itself. Schema tools (`schema.propose`,
`policy.simulate`, `policy.test`, `schema.apply`, `sql.explain`) run on a
scratch Postgres the server starts (it needs `initdb`, `pg_ctl` and `psql` on
`PATH`), or on the cluster in `PGHOST`. Control tools use `SCRIBASE_API_URL`
and `SCRIBASE_ACCESS_TOKEN`.

```json
{
  "mcpServers": {
    "scribase": {
      "command": "scribase-mcp",
      "env": {
        "SCRIBASE_API_URL": "https://api.scribase.com",
        "SCRIBASE_ACCESS_TOKEN": "${env:SCRIBASE_ACCESS_TOKEN}"
      }
    }
  }
}
```

## The CLI, for agents that prefer a shell

```sh
cargo install --locked --path crates/scribase-cli
scribase login --json   # device sign-in: prints a link + code, waits for your approval
scribase doctor         # checks the URL and the token
scribase help           # the exact command list
```

The CLI reads the same `SCRIBASE_API_URL` and `SCRIBASE_ACCESS_TOKEN`, so an
agent can mix MCP tools and CLI commands in one session.