--- title: "Sign-in, permissions, and limits" description: "How MCP clients sign in to Bucky, the permissions (scopes) they can ask for, rate limits, plan usage, and the errors they can return." last_updated: "2026-10-05" --- ## How sign-in works MCP clients sign in with OAuth 2.1 in your browser. You never paste a password or a token into the assistant. 1. The client calls a tool that needs an account. 2. Bucky answers `401` with a `WWW-Authenticate` header, which starts sign-in. 3. Your browser opens a Bucky page that names the app and lists the permissions it is asking for. Sign in and approve. 4. The client receives tokens and refreshes them itself. For client developers, Bucky supports: - PKCE with `S256`; - dynamic client registration and client ID metadata documents; - refresh tokens and token revocation. Metadata lives at: - `https://buckybuild.com/.well-known/oauth-protected-resource/api/mcp` - `https://buckybuild.com/.well-known/oauth-authorization-server` Don't hide signed-in tools until a token exists. `tools/list` always returns every tool; calling a signed-in tool is what starts sign-in. ## Permissions (scopes) | Scope | What it allows (as shown on the approval page) | | ------------ | ---------------------------------------------------------------- | | `mcp:read` | Read your projects, site analyses, and zoning results | | `mcp:write` | Create and update projects, attach parcels, and run new analyses | | `mcp:export` | Export report PDFs, which spends your export credits | | `mcp` | All three | A client that asks for no scope gets `mcp`. Unknown scopes are ignored rather than rejected. Export is separate because it is the only permission that uses a plan allowance. Each tool's scope is listed in [MCP tools](/docs/mcp/tools). ## Manage and revoke access Connected apps are listed under **Settings → Connections** with their permissions and when each was last used. Revoking takes effect on the app's next request. From a terminal, `bucky mcp connections list` and `bucky mcp connections revoke` do the same ([CLI](/docs/cli/agents)). ## Bearer tokens MCP clients get their tokens through OAuth, including scripts. Send the RFC 8707 `resource` parameter, `https://buckybuild.com/api/mcp`, on the authorize and token requests. If the authorize request leaves it out, Bucky binds the MCP resource. Any other value returns `invalid_target`. - **Access tokens** start with `bmcp_at_` and last 1 hour. - **Refresh tokens** start with `bmcp_rt_`. Each refresh returns a new one, so keep only the newest. They stop working after 7 days unused, or 30 days after sign-in. - **A used refresh token is a replay.** Sending one again revokes every token for that connection, and the client must sign in again. - **They work only at `/api/mcp`.** Bucky's HTTP API refuses them. Treat tokens as opaque; the prefixes are for recognition, not parsing. Connected clients move to these tokens at their next refresh, without reconnecting. **Don't paste a Bucky user access token as a bearer.** `/api/mcp` still accepts one during the transition, but that is deprecated and will end: Bucky will answer `401 invalid_token` with the `resource_metadata` challenge. `bucky auth login --copy-mcp` prints a URL-only configuration, and the MCP client signs in with OAuth itself. Agents using [`/auth.md`](https://buckybuild.com/auth.md) send the same `resource`. Keep tokens out of shell history (for example, read them with `read -s`). **Developer API keys don't work on MCP.** Keys starting with `bk_live_` or `bk_test_` are for the [HTTP API](/docs/api) only. Sent to `/api/mcp`, they are rejected like an invalid token. ## Plans and usage - The MCP connector is included on every plan, including Free. - Looking up a site (`getFeasibilitySnapshot`) over MCP does not use site lookups. - Creating a project with `saveToProject` counts toward your plan's project limit. - Exporting a report with `produceProjectReport` uses one of your plan's exports. - Screening (`screenLots`) and saved buy boxes don't use a plan allowance. See [Plans](/docs/resources/plans). ## Rate limits The tools that work without signing in are limited per IP address: | Tool | Limit | | --------------------- | ---------------------- | | `previewSiteCoverage` | 20 requests per hour | | `cityInventory` | 30 requests per minute | Over the limit, the call returns error `-32011`. Sign in for the full tools. ## Errors | Error | HTTP | Meaning | | -------- | ----- | ---------------------------------------------------------------------------- | | `-32010` | `401` | No token, or the token is invalid or expired. Sign in or refresh. | | `-32011` | | Rate limit reached on a tool that works without signing in. | | `-32012` | `402` | Your plan doesn't include this. | | `-32602` | | Invalid arguments. The message names the field. | | `-32602` | `403` | Signed in but not permitted, for example a suspended account. | | `-32603` | | Unexpected server error. Details are logged, not returned. | | `-32600` | `413` | Request body over 64 KiB. | | `-32000` | `403` | The request's `Origin` isn't allowed. | | | `405` | `GET` or `DELETE` on the endpoint. Use `POST`. | | | `406` | The `Accept` header must include `application/json` and `text/event-stream`. | A tool that fails on its own terms (for example, an address it can't find) returns a normal result with `isError: true` and an explanation, not a protocol error. ## Origin Requests with an `Origin` header must come from an allowed origin, which prevents DNS rebinding. Requests with no `Origin` — the normal case for desktop and server MCP clients — are allowed. To call Bucky's MCP server from a web page, contact us to allow your origin. ## Sitemap See the full [sitemap](/sitemap.md) for all pages.