Sign-in, permissions, and limits

How sign-in worksCopy Anchor Link

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)Copy Anchor Link

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.

Manage and revoke accessCopy Anchor Link

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).

Bearer tokensCopy Anchor Link

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 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 only. Sent to /api/mcp, they are rejected like an invalid token.

Plans and usageCopy Anchor Link

• 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.

Rate limitsCopy Anchor Link

The tools that work without signing in are limited per IP address:

Over the limit, the call returns error -32011. Sign in for the full tools.

ErrorsCopy Anchor Link

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.

OriginCopy Anchor Link

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.