develop -> master

docs/appcircle-ai/appcircle-mcp-server.md

@@ -158,12 +158,24 @@ You can see the available tools in your MCP client after the Appcircle MCP serve
 
 To use the Appcircle MCP Server, you need an **Appcircle Access Token**. This token authenticates requests to Appcircle's APIs and is required for all running modes (stdio, streamable-http, or when connecting to the remote host at `https://mcp.appcircle.io`).
 
-There are **two ways** to obtain an access token. For step-by-step instructions on creating and exchanging credentials for a token:
+There are **two ways** to obtain a credential:
 
 1. [Personal Access Key](/account/my-organization/security/personal-access-key): Best for individual use; inherits your user permissions in the organization.
 2. [API Keys](/account/my-organization/security/api-keys): Best for automation and CI; scoped by organization and roles.
 
-Both produce an access token that you use as `APPCIRCLE_ACCESS_TOKEN` in your environment or pass via your MCP client (for example, `Authorization: Bearer <token>`).
+Generating a Personal Access Key or API Key does not give you the access token itself; it gives you a credential that you **exchange** for a token by calling Appcircle's Auth API with it. The API responds with a JWT, and it's this JWT, not the raw key or secret, that is the **Appcircle Access Token** you set as `APPCIRCLE_ACCESS_TOKEN` in your environment or pass via your MCP client (for example, `Authorization: Bearer <token>`). This exchange step is required regardless of which running mode or MCP client you use, since the server itself never sees your Personal Access Key or API Key secret, only the resulting token.
+
+### How to obtain an Appcircle Access Token
+
+See the [Appcircle Access Token](https://github.com/appcircleio/appcircle-mcp/blob/main/docs/appcircle_access_token.md) documentation for the full exchange steps.
+
+:::info Token lifetime and renewal
+The access token is valid for **24 hours** from the time it's issued. The MCP server does not refresh it automatically. When it expires, requests start failing with a `401` error; repeat the exchange above to get a new token, update it wherever your client stores it (as `APPCIRCLE_ACCESS_TOKEN` in your environment, or in your client's MCP server configuration), and restart your MCP client so it picks up the new value.
+:::
+
+:::info Sub-organization scope
+An access token only lists profiles, builds, and reports from the organization it was generated or exchanged in. If you work with a sub-organization, generate or exchange your Personal Access Key or API Key in that sub-organization's context (or pass the `subOrganization` parameter during the exchange) rather than reusing a token issued for the parent organization.
+:::
 
 :::warning Restrict write access when possible
 When creating the token (either method), **restrict write access** if you only need read-only MCP usage. For example, listing Build profiles, Distribution profiles, or Reports. Grant write permissions only when you want the AI or your client to trigger builds, notify testers, publish to stores, or change settings. For **API Keys**, use **Viewer** (or read-only) roles for the relevant modules. For **Personal Access Key**, your user role in the organization applies; use an account or role with read-only access if you do not need write operations.
@@ -173,6 +185,15 @@ If you run the server locally, you can also disable write tools at the server le
 
 ## FAQ
 
+### I'm getting a 401 error. What's wrong?
+
+Appcircle's API returns the same generic `401 Unauthorized` response for several distinct causes, so check each of the following:
+
+- **Wrong token type**: The value configured in your client is the raw Personal Access Key or API Key secret, not the access token you get back from [exchanging it](#how-to-obtain-an-appcircle-access-token).
+- **Expired token**: The access token is only valid for 24 hours. See [Authentication](#authentication) to get a new one.
+
+Since both return the identical error, don't assume it's expiry just because that's the most common cause. Check the token type too.
+
 ### Do I need write access to use the Appcircle MCP?
 
 No. Read-only access is enough for listing builds, profiles, and reports. Grant write access only if you want the AI or your client to trigger builds, notify testers, publish to stores, or change settings. When creating an API Key, use Viewer (or read-only) roles for the relevant modules. When using a Personal Access Key, your user role in the organization applies. If you run the server locally, you can also set `AC_MCP_ENABLE_WRITE_TOOLS=false` to stop write tools from being registered, regardless of the token's permissions.

docs/release-notes.md

@@ -38,6 +38,7 @@ import RedisDomainCaution from '@site/docs/self-hosted-appcircle/install-server/
 - Added a status reason field under Profile Details in Webhook Details to help troubleshoot failed webhook events. <BuildBadge/> <CloudBadge/>
 - A new macOS-based build stack (Tahoe `26.3.2`) is released for the self-hosted Appcircle environments, which has the latest GA release of [Xcode 26.6](https://developer.apple.com/documentation/xcode-release-notes/xcode-26_6-release-notes) (`17F113`) installed along with Xcode 26.5 (`17F42`), Xcode 26.4.1 (`17E202`) and Xcode 26.3 (`17C529`), plus up-to-date [build tools](/infrastructure/ios-build-infrastructure#ios-build-environment) for iOS and Android builds. Follow the [setup guide](/self-hosted-appcircle/self-hosted-runner/runner-vm-setup#download-macos-vm) for installation instructions. <InfrastructureBadge/> <SelfHostedBadge/>
 - The [Appcircle Standard macOS Pool (arm64)](/infrastructure/ios-build-infrastructure) now has the stable release of Xcode 26.6 and the latest Beta release of Xcode 27.0 installed on runners. We strongly recommend extensive testing of your workflows to ensure compatibility and stability with this release. <InfrastructureBadge/> <CloudBadge/>
+- The [Appcircle MCP Server](/appcircle-ai/appcircle-mcp-server) toolset has been expanded with new tools to trigger and cancel builds, read build status/logs and variable groups, notify testers and update release notes in Testing Distribution, start and stop publish flows, and pull additional activity log and queue reports. <CloudBadge/>
 
 ### 🐞 Fixes