# filebin.ca — full documentation


---

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

# Build with filebin.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

filebin.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 `file:*` key only works on `filebin.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 `filebin.ca` on pastebin.ca:

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

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

```
pbca file upload ./your-file
```

## 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

file:read file:create file:delete

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

* Reading a public file 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 `file:create`; a keyless upload returns `403 {"error":"turnstile_failed"}`.

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

Upload capsREST accepts up to **25 MiB** per file on the API-key tier.

## pbca CLI

One CLI for the whole family. `pbca file` commands default to `filebin.ca`.

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

## MCP for AI agents

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

### Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads `https://filebin.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": {
    "filebin": {
      "url": "https://filebin.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": {
    "filebin": {
      "url": "https://filebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}
```

### Tools

| Tool | Scope | Purpose |
| --- | --- | --- |
| `whoami` | — | Echo account id, scopes, audience, and token kind. |
| `get_file` | `file:read` | JSON metadata for a file (visibility-aware). |
| `list_my_files` | `file:read` | List the caller's files; cursor-paginated. |
| `upload_file` | `file:create` | Upload from base64 bytes (capped — see below). |
| `delete_file` | `file:delete` | Delete one of the caller's files. |

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

## OAuth & DPoP

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

- OAuth tokens are **audience-bound** to `https://filebin.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://filebin.ca/.well-known/oauth-protected-resource/mcp) [Authorization-server metadata ↗](https://pastebin.ca/.well-known/oauth-authorization-server) [Agent discovery (agent.json) ↗](https://filebin.ca/.well-known/agent.json) [OpenAPI 3.1 document ↗](https://filebin.ca/api/v1/openapi.json) [MCP endpoint (POST) ↗](https://filebin.ca/mcp)


---

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

# Build with filebin.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

filebin.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 `file:*` key only works on `filebin.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 `filebin.ca` on pastebin.ca:

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

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

```
pbca file upload ./your-file
```

## 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

file:read file:create file:delete

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

* Reading a public file 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 `file:create`; a keyless upload returns `403 {"error":"turnstile_failed"}`.

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

Upload capsREST accepts up to **25 MiB** per file on the API-key tier.

## pbca CLI

One CLI for the whole family. `pbca file` commands default to `filebin.ca`.

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

## MCP for AI agents

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

### Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads `https://filebin.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": {
    "filebin": {
      "url": "https://filebin.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": {
    "filebin": {
      "url": "https://filebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}
```

### Tools

| Tool | Scope | Purpose |
| --- | --- | --- |
| `whoami` | — | Echo account id, scopes, audience, and token kind. |
| `get_file` | `file:read` | JSON metadata for a file (visibility-aware). |
| `list_my_files` | `file:read` | List the caller's files; cursor-paginated. |
| `upload_file` | `file:create` | Upload from base64 bytes (capped — see below). |
| `delete_file` | `file:delete` | Delete one of the caller's files. |

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

## OAuth & DPoP

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

- OAuth tokens are **audience-bound** to `https://filebin.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://filebin.ca/.well-known/oauth-protected-resource/mcp) [Authorization-server metadata ↗](https://pastebin.ca/.well-known/oauth-authorization-server) [Agent discovery (agent.json) ↗](https://filebin.ca/.well-known/agent.json) [OpenAPI 3.1 document ↗](https://filebin.ca/api/v1/openapi.json) [MCP endpoint (POST) ↗](https://filebin.ca/mcp)