diff --git a/docs/admin/service-accounts.mdx b/docs/admin/service-accounts.mdx
index afce86190..8232c58d3 100644
--- a/docs/admin/service-accounts.mdx
+++ b/docs/admin/service-accounts.mdx
@@ -2,6 +2,18 @@
Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password, cannot access the Sourcegraph UI, don't count towards a license's user limit and won't be part of any billing cycles.
+## Choosing an authentication method
+
+Use this quick guide if you're deciding between a service account, an OAuth App, and an access token:
+
+| Option | Best for | Identity used for requests | Notes |
+| ------ | -------- | -------------------------- | ----- |
+| Service account | Automation, CI/CD, server-to-server integrations | A dedicated machine identity | Supports traditional access tokens and M2M credentials for `grant_type=client_credentials` |
+| OAuth App | Applications acting on behalf of signed-in users | Each end user | Best when repository access should follow the permissions of the person using the app |
+| Access token | Quick tests, CLI usage, or one-off scripts tied to a single user | The user or service account that created the token | Simpler to set up, but not ideal for multi-user integrations |
+
+If your integration should act as one non-human identity, use a service account. If it should act on behalf of each signed-in user, use an [OAuth App](/admin/oauth-apps). If you just need a simple token for a single user or service account, use an [access token](/cli/how-tos/creating-an-access-token).
+
## Creating Service Accounts
Service accounts are created like regular user accounts, but with a few key differences.
diff --git a/docs/api/mcp/index.mdx b/docs/api/mcp/index.mdx
index 407b6b561..112d306ea 100644
--- a/docs/api/mcp/index.mdx
+++ b/docs/api/mcp/index.mdx
@@ -173,11 +173,24 @@ To restrict MCP to a subset of users:
See [Access control](/admin/access-control) for more about managing roles and permissions.
- MCP access control is separate from [repository permissions](/admin/permissions/).
- Users can only read data from repositories they are already allowed to access
- in Sourcegraph.
+ MCP access control is separate from [repository
+ permissions](/admin/permissions/). Users can only read data from
+ repositories they are already allowed to access in Sourcegraph.
+## Troubleshooting
+
+Most MCP connection issues come from OAuth or access-control configuration rather than the MCP endpoint itself.
+
+| If you see | Likely cause | What to check |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid_scope` during OAuth sign-in | The client requested the wrong scope for MCP | MCP-only connections should use the `mcp` scope. If the integration also needs GraphQL or other APIs, create a separate [OAuth App](/admin/oauth-apps) with the broader scopes you need instead of reusing an MCP-only registration. |
+| `redirect_uri_mismatch` or a token exchange failure after browser auth | The OAuth client is missing the callback URL expected by the MCP client | Register the exact redirect URI your client uses. For the `mcp-remote` fallback shown above, add `http://localhost:3334/oauth/callback` to the OAuth app. |
+| `/.auth/idp/oauth/register` returns `404 not found` | Dynamic Client Registration is disabled | Confirm `mcp.enabled` is `true` and `auth.idpDynamicClientRegistrationEnabled` is `true`. If you want MCP available without DCR, use the manual OAuth setup instead. |
+| The browser opens for sign-in, but the connection never completes or loops back to login | Your Sourcegraph browser session expired before the OAuth flow completed | Sign in to Sourcegraph in the same browser profile first, then retry the MCP connection. This is especially common when the OAuth window opens in a browser profile that is not already signed in. |
+| Users must sign in again frequently even though the integration previously worked | The client is not refreshing tokens correctly | OAuth access tokens are short-lived. Make sure the client stores the newest `refresh_token` returned on each refresh, because refresh tokens are one-time use. For service-account M2M flows, request a new access token when the current one expires because no refresh token is returned. |
+| `403 forbidden` from `/.api/mcp` | The user authenticated successfully but does not have MCP access | Check that MCP is enabled, the user has the `MCP#ACCESS` permission, and the user already has access to the repositories they are trying to read. |
+
## Available Tools
diff --git a/docs/cli/how-tos/managing-access-tokens.mdx b/docs/cli/how-tos/managing-access-tokens.mdx
index acd0bc648..ef8284572 100644
--- a/docs/cli/how-tos/managing-access-tokens.mdx
+++ b/docs/cli/how-tos/managing-access-tokens.mdx
@@ -14,6 +14,12 @@ The `auth.accessTokens` setting in Sourcegraph's site configuration allows admin
}
```
+
+ `auth.accessTokens` only controls Sourcegraph access tokens. It does not disable
+ [OAuth Apps](/admin/oauth-apps), service-account M2M credentials, or MCP
+ Dynamic Client Registration.
+
+
## Access token creation
The `allow` property permits or restricts the use of access tokens. It can be assigned one of three values: