buildkite · sj26 · Sep 2, 2026 · Sep 2, 2026
@@ -1 +1 @@
-Once connected to the remote MCP server, if you need a new OAuth token, the **Connect with Buildkite MCP Server** page appears. If so, select your Buildkite organization from **Select organization**, then select **Authorize**. If your organization requires SSO, select **Log in with SSO** first to authenticate, then return to this page and select **Authorize** to complete the authorization.
+Once connected to the remote MCP server, if you need a new OAuth token, the **Connect with Buildkite MCP Server** page appears. If so, review the preselected Buildkite organization or select one from **Select organization**, then select **Authorize**. If your organization requires SSO, select **Log in with SSO** first to authenticate, then return to this page and select **Authorize** to complete the authorization.
@@ -55,6 +55,18 @@ You can also use the `X-Buildkite-Readonly: true` header with `/direct` to enfor
 
 For interactive AI tools that can complete OAuth, use the OAuth-based remote MCP server at `https://mcp.buildkite.com/mcp`.
 
+## Preselect an organization for OAuth
+
+To preselect an organization on the OAuth authorization page, add its slug to the remote MCP server URL:
+
+```url
+https://mcp.buildkite.com/mcp?organization=your-organization
+```
+
+You can use `organization_uuid` instead when you have the organization's UUID. The organization parameter works with toolset and read-only URLs too—for example, `https://mcp.buildkite.com/mcp/x/pipelines/readonly?organization=your-organization`.
+
+The organization is a hint, not an access control. It is preselected only when you can authorize it, and you can select another available organization before approving the request.
+
 ## Amp
 
 You can configure [Amp](https://ampcode.com/) with the remote Buildkite MCP server by adding the following JSON configuration to your [Amp `settings.json` file](https://ampcode.com/manual#configuration). This configuration uses the `mcp-remote` command argument to allow OAuth authorization. For more about this configuration type, see [Custom Tools (MCP)](https://ampcode.com/manual#mcp) in the Amp documentation.
@@ -66,7 +78,7 @@ You can configure [Amp](https://ampcode.com/) with the remote Buildkite MCP serv
       "command": "npx",
       "args": [
         "mcp-remote",
-        "https://mcp.buildkite.com/mcp"
+        "https://mcp.buildkite.com/mcp?organization=your-organization"
       ]
     }
   }

@@ -38,6 +38,7 @@ Content-Type: application/x-www-form-urlencoded
 
 client_id=your-client-id
 &scope=read_user read_organizations
+&organization=your-organization
 ```
 
 ### Request parameters
@@ -47,6 +48,10 @@ client_id=your-client-id
 | `client_id` | Yes | The client ID of your OAuth application |
 | `scope` | Yes | Space-delimited list of [scopes](/docs/apis/managing-api-tokens#token-scopes). At least one valid scope is required |
 | `client_secret` | Conditional | Required for confidential clients. Not required for public clients |
+| `organization` | No | Organization slug to preselect on the authorization page |
+| `organization_uuid` | No | Organization UUID to preselect on the authorization page. If both organization parameters identify an organization, `organization_uuid` takes precedence |
+
+The organization parameters are hints, not access controls. The hinted organization is preselected only when the user can authorize it, and the user can select another available organization before approving the request.
 
 ### Response
 
@@ -80,7 +85,7 @@ The user:
 
 1. Enters the code (when using `verification_uri`).
 1. Reviews the application name and requested scopes.
-1. Selects a Buildkite organization to authorize.
+1. Reviews the preselected Buildkite organization, when one was requested, or selects an organization to authorize.
 1. Approves or denies the request.
 
 ## Token request

@@ -13,6 +13,14 @@ To restrict the scopes requested during OAuth login, use the `--scopes` flag. Fo
 > 📘 Restricting CLI token scopes
 > For organizations that enforce the principle of least privilege, use `--scopes` to issue CLI tokens with only the minimum scopes required. Without `--scopes`, the token is issued with all scopes that your account has permission for.
 
+To preselect an organization during OAuth login, use the `--org` flag. This also works with device authorization on a headless machine or remote shell:
+
+```bash
+bk auth login --device --org my-org
+```
+
+The organization is a hint. You can select another available organization on the authorization page before approving the request.
+
 ## Create an API access token for the Buildkite CLI
 
 To create a new API access token:
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		Once connected to the remote MCP server, if you need a new OAuth token, the Connect with Buildkite MCP Server page appears. If so, select your Buildkite organization from Select organization, then select Authorize. If your organization requires SSO, select Log in with SSO first to authenticate, then return to this page and select Authorize to complete the authorization.
		Once connected to the remote MCP server, if you need a new OAuth token, the Connect with Buildkite MCP Server page appears. If so, review the preselected Buildkite organization or select one from Select organization, then select Authorize. If your organization requires SSO, select Log in with SSO first to authenticate, then return to this page and select Authorize to complete the authorization.