From 36467652154c3ea2aabc1d367888e8b6abd159f7 Mon Sep 17 00:00:00 2001 From: Amp Date: Wed, 2 Sep 2026 03:56:21 +0000 Subject: [PATCH 1/2] Document OAuth organization hints Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-01a06015-04b9-70ab-aaba-bc0e8736680f Co-authored-by: Samuel Cochran --- pages/apis/mcp_server/_buildkite_oauth_token.md | 2 +- .../apis/mcp_server/remote/configuring_ai_tools.md | 14 +++++++++++++- pages/apis/oauth_device_authorization.md | 7 ++++++- pages/platform/cli/configuration.md | 8 ++++++++ 4 files changed, 28 insertions(+), 3 deletions(-) diff --git a/pages/apis/mcp_server/_buildkite_oauth_token.md b/pages/apis/mcp_server/_buildkite_oauth_token.md index c6b53a4e471..ab6e81302f8 100644 --- a/pages/apis/mcp_server/_buildkite_oauth_token.md +++ b/pages/apis/mcp_server/_buildkite_oauth_token.md @@ -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. diff --git a/pages/apis/mcp_server/remote/configuring_ai_tools.md b/pages/apis/mcp_server/remote/configuring_ai_tools.md index af01d1808f7..c8970cae12e 100644 --- a/pages/apis/mcp_server/remote/configuring_ai_tools.md +++ b/pages/apis/mcp_server/remote/configuring_ai_tools.md @@ -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" ] } } diff --git a/pages/apis/oauth_device_authorization.md b/pages/apis/oauth_device_authorization.md index 0b6d5ea2809..3d0d8bd8d9a 100644 --- a/pages/apis/oauth_device_authorization.md +++ b/pages/apis/oauth_device_authorization.md @@ -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 diff --git a/pages/platform/cli/configuration.md b/pages/platform/cli/configuration.md index ef6d96335fe..3032c44527d 100644 --- a/pages/platform/cli/configuration.md +++ b/pages/platform/cli/configuration.md @@ -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: From aabef5849e6cb18b3000eca3d22c1b273a2d581f Mon Sep 17 00:00:00 2001 From: Amp Date: Wed, 2 Sep 2026 04:59:39 +0000 Subject: [PATCH 2/2] Fix OAuth hint heading hierarchy Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-01a06015-04b9-70ab-aaba-bc0e8736680f Co-authored-by: Samuel Cochran --- pages/apis/mcp_server/remote/configuring_ai_tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/mcp_server/remote/configuring_ai_tools.md b/pages/apis/mcp_server/remote/configuring_ai_tools.md index c8970cae12e..4e133edae0f 100644 --- a/pages/apis/mcp_server/remote/configuring_ai_tools.md +++ b/pages/apis/mcp_server/remote/configuring_ai_tools.md @@ -55,7 +55,7 @@ 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 +## Preselect an organization for OAuth To preselect an organization on the OAuth authorization page, add its slug to the remote MCP server URL: