# notebin.ca — full documentation


---

---
title: "Developer docs — notebin.ca"
source: "https://notebin.ca/docs"
---
Documentation

# Build with notebin.ca

REST API, the pbca CLI, and an MCP server for AI agents — all on your pastebin.ca account.

[Quick start](#quickstart) [REST API](#rest) [pbca CLI](#cli) [MCP for AI agents](#mcp) [OAuth & DPoP](#oauth) [Discovery](#discovery)

## Quick start

notebin.ca shares your pastebin.ca account. There is nothing new to sign up for — install the CLI, mint an API key bound to this site, and you can drive everything from the terminal, your scripts, or an AI agent.

Audience-boundKeys are scoped to one site. A `note:*` key only works on `notebin.ca`; it is rejected everywhere else.

**1.** Install the `pbca` CLI — a self-contained Rust binary:

```
curl -fsSL https://pastebin.ca/cli/install.sh | sh
```

Installs `pbca` to `/usr/local/bin` (override with `PBCA_INSTALL_PREFIX`). Prefer a direct download? Grab a platform binary — macOS, Linux, or Windows — from [pastebin.ca/cli](https://pastebin.ca/cli).

**2.** Mint a key bound to `notebin.ca` on pastebin.ca:

```
pbca account api-key create \
  --scopes note:read,note:create,note:delete \
  --audience https://notebin.ca
```

**3.** Give the key to the CLI via `PBCA_API_KEY` or `pbca account login`, then upload your first note:

```
pbca note upload ./your-note
```

## REST API

A small JSON surface. Send your key as `Authorization: Bearer <api-key>`. Anonymous browser uploads (with Turnstile) and signed-in cookie sessions also work; API-key callers must hold the matching scope.

### Scopes

note:read note:create note:delete

| Action | Method & path | Scope |
| --- | --- | --- |
| Upload a note | `POST /api/v1/notes` | `note:create` |
| Read metadata | `GET /api/v1/items/:id` | `note:read` * |
| List your notes | `GET /api/v1/account/items` | `note:read` |
| Delete a note | `DELETE /api/v1/items/:id` | `note:delete` |

* Reading a public note needs no key; a key, when sent, is scope-checked.

Uploads need a key (or a browser)Anonymous uploads are **browser-only** — they require a Turnstile challenge. From a script, the CLI, or an agent, send an API key with `note:create`; a keyless upload returns `403 {"error":"turnstile_failed"}`.

```
curl -sS https://notebin.ca/api/v1/account/items \
  -H 'Authorization: Bearer pbca_live_…'
```

Upload capsREST accepts up to **256 KB** per note on the API-key tier.

## pbca CLI

One CLI for the whole family. `pbca note` commands default to `notebin.ca`.

| Command | What it does |
| --- | --- |
| `pbca note upload <path>` | Upload a note (returns its id + URLs) |
| `pbca note get <id-or-url>` | Print metadata as JSON |
| `pbca note list` | List your notes (cursor-paginated) |
| `pbca note delete <id>` | Delete one of your notes |

## MCP for AI agents

notebin.ca runs a Model Context Protocol server at `https://notebin.ca/mcp`, so Claude Desktop, Cursor, the MCP Inspector, and other agents can manage your notes directly.

### Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads `https://notebin.ca/.well-known/oauth-protected-resource/mcp`, registers with pastebin.ca (the authorization server), and runs the standard OAuth 2.1 + PKCE flow. Add to your Claude Desktop config:

```
{
  "mcpServers": {
    "notebin": {
      "url": "https://notebin.ca/mcp"
    }
  }
}
```

Config path: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux). Cursor and Windsurf use the same `mcpServers` shape in `~/.cursor/mcp.json`. Try it live with `npx @modelcontextprotocol/inspector`.

### Option B — API-key bearer (automation)

For headless/server-side use, send a minted key directly:

```
{
  "mcpServers": {
    "notebin": {
      "url": "https://notebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}
```

### Tools

| Tool | Scope | Purpose |
| --- | --- | --- |
| `whoami` | — | Echo account id, scopes, audience, and token kind. |
| `get_note` | `note:read` | Fetch a note: metadata + Markdown source. |
| `list_my_notes` | `note:read` | List the caller's notes; cursor-paginated. |
| `create_note` | `note:create` | Publish a Markdown note; returns id + URLs. |
| `delete_note` | `note:delete` | Delete one of the caller's notes. |

MCP upload capMCP uploads are capped at **256 KB** (base64 inflates inside the JSON-RPC envelope). Use the REST endpoint for larger notes.

## OAuth & DPoP

pastebin.ca is the OAuth authorization server; notebin.ca is a protected resource and never mints tokens.

- OAuth tokens are **audience-bound** to `https://notebin.ca/mcp` (RFC 8707) and honored only on the MCP route.
- If a key is **DPoP-bound** (RFC 9449), every MCP request must carry a matching ES256 proof; replays are rejected. Plain bearer keys work without DPoP.
- Revoke a key or connected app anytime from your pastebin.ca account.

## Discovery

Machine-readable metadata for clients and agents:

[Protected-resource metadata ↗](https://notebin.ca/.well-known/oauth-protected-resource/mcp) [Authorization-server metadata ↗](https://pastebin.ca/.well-known/oauth-authorization-server) [Agent discovery (agent.json) ↗](https://notebin.ca/.well-known/agent.json) [OpenAPI 3.1 document ↗](https://notebin.ca/api/v1/openapi.json) [MCP endpoint (POST) ↗](https://notebin.ca/mcp)


---

---
title: "Developer docs — notebin.ca"
source: "https://notebin.ca/docs/mcp"
---
Documentation

# Build with notebin.ca

REST API, the pbca CLI, and an MCP server for AI agents — all on your pastebin.ca account.

[Quick start](#quickstart) [REST API](#rest) [pbca CLI](#cli) [MCP for AI agents](#mcp) [OAuth & DPoP](#oauth) [Discovery](#discovery)

## Quick start

notebin.ca shares your pastebin.ca account. There is nothing new to sign up for — install the CLI, mint an API key bound to this site, and you can drive everything from the terminal, your scripts, or an AI agent.

Audience-boundKeys are scoped to one site. A `note:*` key only works on `notebin.ca`; it is rejected everywhere else.

**1.** Install the `pbca` CLI — a self-contained Rust binary:

```
curl -fsSL https://pastebin.ca/cli/install.sh | sh
```

Installs `pbca` to `/usr/local/bin` (override with `PBCA_INSTALL_PREFIX`). Prefer a direct download? Grab a platform binary — macOS, Linux, or Windows — from [pastebin.ca/cli](https://pastebin.ca/cli).

**2.** Mint a key bound to `notebin.ca` on pastebin.ca:

```
pbca account api-key create \
  --scopes note:read,note:create,note:delete \
  --audience https://notebin.ca
```

**3.** Give the key to the CLI via `PBCA_API_KEY` or `pbca account login`, then upload your first note:

```
pbca note upload ./your-note
```

## REST API

A small JSON surface. Send your key as `Authorization: Bearer <api-key>`. Anonymous browser uploads (with Turnstile) and signed-in cookie sessions also work; API-key callers must hold the matching scope.

### Scopes

note:read note:create note:delete

| Action | Method & path | Scope |
| --- | --- | --- |
| Upload a note | `POST /api/v1/notes` | `note:create` |
| Read metadata | `GET /api/v1/items/:id` | `note:read` * |
| List your notes | `GET /api/v1/account/items` | `note:read` |
| Delete a note | `DELETE /api/v1/items/:id` | `note:delete` |

* Reading a public note needs no key; a key, when sent, is scope-checked.

Uploads need a key (or a browser)Anonymous uploads are **browser-only** — they require a Turnstile challenge. From a script, the CLI, or an agent, send an API key with `note:create`; a keyless upload returns `403 {"error":"turnstile_failed"}`.

```
curl -sS https://notebin.ca/api/v1/account/items \
  -H 'Authorization: Bearer pbca_live_…'
```

Upload capsREST accepts up to **256 KB** per note on the API-key tier.

## pbca CLI

One CLI for the whole family. `pbca note` commands default to `notebin.ca`.

| Command | What it does |
| --- | --- |
| `pbca note upload <path>` | Upload a note (returns its id + URLs) |
| `pbca note get <id-or-url>` | Print metadata as JSON |
| `pbca note list` | List your notes (cursor-paginated) |
| `pbca note delete <id>` | Delete one of your notes |

## MCP for AI agents

notebin.ca runs a Model Context Protocol server at `https://notebin.ca/mcp`, so Claude Desktop, Cursor, the MCP Inspector, and other agents can manage your notes directly.

### Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads `https://notebin.ca/.well-known/oauth-protected-resource/mcp`, registers with pastebin.ca (the authorization server), and runs the standard OAuth 2.1 + PKCE flow. Add to your Claude Desktop config:

```
{
  "mcpServers": {
    "notebin": {
      "url": "https://notebin.ca/mcp"
    }
  }
}
```

Config path: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux). Cursor and Windsurf use the same `mcpServers` shape in `~/.cursor/mcp.json`. Try it live with `npx @modelcontextprotocol/inspector`.

### Option B — API-key bearer (automation)

For headless/server-side use, send a minted key directly:

```
{
  "mcpServers": {
    "notebin": {
      "url": "https://notebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}
```

### Tools

| Tool | Scope | Purpose |
| --- | --- | --- |
| `whoami` | — | Echo account id, scopes, audience, and token kind. |
| `get_note` | `note:read` | Fetch a note: metadata + Markdown source. |
| `list_my_notes` | `note:read` | List the caller's notes; cursor-paginated. |
| `create_note` | `note:create` | Publish a Markdown note; returns id + URLs. |
| `delete_note` | `note:delete` | Delete one of the caller's notes. |

MCP upload capMCP uploads are capped at **256 KB** (base64 inflates inside the JSON-RPC envelope). Use the REST endpoint for larger notes.

## OAuth & DPoP

pastebin.ca is the OAuth authorization server; notebin.ca is a protected resource and never mints tokens.

- OAuth tokens are **audience-bound** to `https://notebin.ca/mcp` (RFC 8707) and honored only on the MCP route.
- If a key is **DPoP-bound** (RFC 9449), every MCP request must carry a matching ES256 proof; replays are rejected. Plain bearer keys work without DPoP.
- Revoke a key or connected app anytime from your pastebin.ca account.

## Discovery

Machine-readable metadata for clients and agents:

[Protected-resource metadata ↗](https://notebin.ca/.well-known/oauth-protected-resource/mcp) [Authorization-server metadata ↗](https://pastebin.ca/.well-known/oauth-authorization-server) [Agent discovery (agent.json) ↗](https://notebin.ca/.well-known/agent.json) [OpenAPI 3.1 document ↗](https://notebin.ca/api/v1/openapi.json) [MCP endpoint (POST) ↗](https://notebin.ca/mcp)