Sign in

Each product signs in separately, through the browser or with environment settings. Browser sign-in is the default and the recommended way.

Browser sign-in

1. The client calls bud_auth_login or bloom_auth_login. If BUD_URL or BLOOM_URL is set, sign-in always goes to that URL; otherwise the tool takes the instance URL as url. HTTPS is required, except for loopback addresses.
2. The tool returns session_id, authorize_url and a request_code such as BUUZ-WHVV, derived from the sign-in’s PKCE challenge.
3. Open authorize_url, sign in to the instance, check that the page shows the same request code, and approve. The client gets the permissions of your account.
4. The client calls bud_auth_complete or bloom_auth_complete with the session_id.

Callback mode is the default: the server listens on a random loopback port and the browser is sent back there after approval, so the browser and the server run on the same machine. Deny on the approval page ends the request.

Code mode (mode: "code", or --code on the terminal) is for a server the browser cannot reach: the approval page shows a one-time code that you give to auth_complete. It works only on an instance whose operator enabled it.

Both modes use PKCE. A pending sign-in expires after ten minutes or when the process exits.

Where credentials are kept

• ~/.config/embedlabs-mcp/credentials.json (mode 0600): each profile’s name and instance URL.
• The system credential store (macOS Keychain, Windows Credential Manager, Secret Service on Linux), service embedlabs-mcp, account bud/<profile> or bloom/<profile>: the access and refresh tokens. Where no credential store exists, the tokens stay in the file.

The MCP server and the bud and bloom commands share these profiles.

Profiles

A profile keeps one instance, so you can work with several side by side. Names are 1 to 32 lowercase letters, digits and hyphens. The server uses the profile named by BUD_PROFILE or BLOOM_PROFILE, otherwise the default one, so two MCP client entries can point at two instances.

Token renewal

On a 401 the server first re-reads the credentials file, in case another process refreshed the tokens, then refreshes once itself and retries. A lock file next to the credentials file makes sure one process at a time rotates the single-use refresh token.

Environment settings instead

A token, or an email and password, take precedence over browser sign-in; see Configuration. Bud and Bloom do not issue personal access tokens yet, so a BUD_TOKEN or BLOOM_TOKEN works only for the instance’s access-token lifetime, 30 minutes by default, and is not renewed.