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 a402dd10d87..3cdd3ea3eeb 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/docs/cli/settings). This configuration uses the `mcp-remote` command argument to allow OAuth authorization. For more about this configuration type, see [MCP](https://ampcode.com/docs/customize/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 17346c6de03..22a6fdb4fd5 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 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: