@bastani/atomic 0.9.25-alpha.2 → 0.9.25-alpha.4

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 ## [Unreleased]
 
+## [0.9.25-alpha.4] - 2026-09-30
+
+### Breaking Changes
+
+- Replaced the old MCP adapter with the native client. Only `~/.atomic/agent/mcp.json` and trusted `.atomic/mcp.json` are read, using the native configuration shape. Shared config layers, client imports, and old-field translations are no longer supported; old OAuth credentials are not imported.
+- MCP tools now use `mcp__<server>__<tool>` names and default to `codemode` exposure. The old gateway, configurable prefixes, lazy/idle lifecycle settings, metadata cache, SSE transport, MCP Apps rendering, and setup command are removed. Enabled servers connect in the background; `/mcp reconnect` without a name selects one server rather than reconnecting every server.
+
+### Added
+
+- MCP servers can set `oauth.authServerMetadataUrl` to a trusted authorization server metadata document when discovery advertises the wrong server or none. See [MCP authentication](docs/mcp-servers.md#override-oauth-authorization-server-discovery) ([#10172](https://github.com/earendil-works/pi/issues/10172)).
+- Added `/mcp login [server]`, command completion, and server selection for login, logout, and reconnect. The manager offers per-server action menus for enabled state and tool exposure, and OAuth sign-in accepts a pasted redirect URL when the browser is on another machine.
+- MCP servers support `codemode`, `deferred`, `direct`, and `hidden` exposure with per-tool pattern overrides, standard resource list/read tools, and per-server OAuth callback ports and URLs. See [MCP servers](docs/mcp-servers.md).
+- Added shell commands `atomic mcp add`, `remove`, `list`, `login`, and `logout` to configure, check, and authenticate file-configured servers without starting a session.
+
+### Changed
+
+- MCP now uses pi's native client, tool exposure, resources, and server manager. Calls, including codemode calls, pass through Atomic's tool permission pipeline. Native OAuth credentials are stored in `mcp-auth.json`.
+
+### Fixed
+
+- MCP OAuth rejects authorization responses from another issuer, including a missing `iss` when the server promises it under RFC 9207.
+- MCP OAuth sign-in and refresh now tolerate empty or null optional token and registration fields, and empty requested scopes use the next scope source ([#10266](https://github.com/earendil-works/pi/issues/10266)).
+- MCP sign-out no longer lets an in-progress OAuth refresh restore deleted credentials.
+- Session shutdown now closes MCP connections that are still opening instead of leaving them running after the session ends.
+- Replacing an extension-contributed MCP server now retires pending connections, and reloading with active servers no longer fails during connection cleanup.
+- Malformed MCP configuration errors no longer quote file contents that may contain credentials.
+- MCP OAuth refreshes authorization-server discovery when a server advertises a changed metadata URL.
+
+## [0.9.25-alpha.3] - 2026-09-30
+
+### Added
+
+- SDK hosts can now manage the workflow runs their session owns through `session.workflows`: `listRuns()`, `getRun()`, `getStages()`, `pause()`, `quit()` and `resume()` return the workflow tool's structured results, and failures reject with typed `WorkflowRunControlError` subclasses (`WorkflowRunNotFoundError`, `WorkflowRunOwnershipError`, `WorkflowRunNotResumableError`, `WorkflowRunDatabaseError`, `WorkflowStageNotFoundError`, `WorkflowStageAmbiguousError`, `WorkflowStageResumeUnsupportedError`) instead of strings. A batch `pause({ all: true })` or `quit({ all: true })` returns a `partial` outcome whose `failedRuns` names the runs still active only when that call stopped at least one run, and rejects with `WorkflowRunControlError` carrying `failedRuns` when active runs could not be stopped and the call stopped none, even if other runs were already paused. Already-paused and already-ended runs are not failures. A database outage while checking who owns a run rejects `pause()` and `quit()` with `WorkflowRunDatabaseError`. It uses the same ownership and durable-resume rules as the `workflow` tool, so runs owned by another session or live process stay read-only ([#3377](https://github.com/bastani-inc/atomic/issues/3377)).
+- Codemode scripts can retrieve namespace summaries, instructions, and callable tool names with `describeNamespace(name)`. Tool search indexes namespace instructions without including them in inline tool listings, and codemode listings no longer include tool counts ([#10212](https://github.com/earendil-works/pi/issues/10212)).
+- `/reload` enables tools newly added to `defaultTools`, while preserving session-disabled tools, tools removed from the setting, and explicit CLI tool restrictions ([#10245](https://github.com/earendil-works/pi/issues/10245)).
+- Added Anthropic workload identity federation from the `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, and `ANTHROPIC_IDENTITY_TOKEN_FILE` environment variables, with optional `ANTHROPIC_SERVICE_ACCOUNT_ID` and `ANTHROPIC_WORKSPACE_ID`. See [Providers](docs/providers.md#anthropic-workload-identity-federation) ([#10177](https://github.com/earendil-works/pi/issues/10177), [#10242](https://github.com/earendil-works/pi/pull/10242) by [@philfreo](https://github.com/philfreo)).
+- MCP servers can set `oauth.clientName` for dynamic OAuth registration, or use `"auth": { "provider": "<provider>" }` to send the current provider login token. Provider-token authentication is restricted to global configuration and extension registrations, with HTTPS required except on loopback hosts. See [MCP authentication](docs/mcp-servers.md#authentication) ([#10226](https://github.com/earendil-works/pi/issues/10226)).
+- `/login anthropic` now offers **Copy code login (headless)** when the browser is on another machine and cannot reach Atomic's local callback ([#10194](https://github.com/earendil-works/pi/pull/10194) by [@lucasmeijer](https://github.com/lucasmeijer)).
+
+### Fixed
+
+- On a heavily loaded machine, a workflow run could fail with a bare `Query read timeout` while Atomic verified its managed PostgreSQL connection, even though the database was healthy. Health queries now get more time (3 s) on every path, and both the check of a borrowed connection and Atomic's periodic background health check repeat once after a timeout. If the timeout persists, the run fails with a resumable database-unavailable error instead of `Query read timeout`, and other running workflows' database connections are not closed and PostgreSQL is not restarted. A refused or terminated connection, a server shutdown, or a changed database identity is still treated as an outage.
+- Renderer examples now retain the built-in tools' prompt guidance and execution behavior when customizing their display ([#10072](https://github.com/earendil-works/pi/issues/10072)).
+- Reduced model lookup overhead when merging large remote provider catalogs.
+- Invalid extension commands now fail registration with a clear error instead of crashing slash-command completion ([#10054](https://github.com/earendil-works/pi/issues/10054)).
+- Codemode and tool-search descriptions now remain unchanged when deferred tools register, preserving prompt stability while discovery continues to find those tools ([#10212](https://github.com/earendil-works/pi/issues/10212)).
+- Collapsed codemode scripts and results now limit wrapped screen lines, so long single-line JSON no longer fills the transcript. Bash previews use the same cached visual-line component.
+- In `codemode.mode: "only"`, the system prompt's tool list no longer advertises tools whose direct declarations are hidden ([#10192](https://github.com/earendil-works/pi/issues/10192)).
+- Fixed context overflow detection for Z.AI CN endpoint `Prompt exceeds max length` errors ([#10208](https://github.com/earendil-works/pi/issues/10208)).
+- Anthropic tools with strict-schema constraints the provider rejects now fall back to non-strict mode when strict sampling is preferred ([#9953](https://github.com/earendil-works/pi/issues/9953)).
+- Provider retries now use exponential backoff when `Retry-After` contains an unparseable date ([#9571](https://github.com/earendil-works/pi/issues/9571)).
+- MCP sign-in URLs remain clickable when they wrap, including inside the `/mcp` panel ([#10186](https://github.com/earendil-works/pi/issues/10186)).
+- MCP tool names now use JavaScript-safe identifiers with deterministic suffixes for collisions and long names, consistently across direct tools, gateway discovery, and codemode ([#10239](https://github.com/earendil-works/pi/issues/10239)).
+- Codemode `image()` now rejects malformed base64 and unsupported image types before saving a tool result, and detects the MIME type from the image data instead of trusting the supplied type ([#10215](https://github.com/earendil-works/pi/issues/10215)).
+
 ## [0.9.25-alpha.2] - 2026-09-30
 
 ### Fixed

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.25-alpha.2",
+  "version": "0.9.25-alpha.4",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.99.1",
+    "@earendil-works/pi-tui": "^0.99.2",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.25-alpha.4] - 2026-09-30
+
+### Breaking Changes
+
+- Replaced the old adapter with the native client. Only `~/.atomic/agent/mcp.json` and trusted `.atomic/mcp.json` are read, using the native configuration shape. Shared config layers, client imports, and old-field translations are no longer supported; old OAuth credentials are not imported.
+- Tools now use `mcp__<server>__<tool>` names and default to `codemode` exposure. The old gateway, configurable prefixes, lazy/idle lifecycle settings, metadata cache, SSE transport, MCP Apps rendering, and setup command are removed. Enabled servers connect in the background; `/mcp reconnect` without a name selects one server rather than reconnecting all servers.
+
+### Added
+
+- Set `oauth.authServerMetadataUrl` to use a trusted authorization server metadata document instead of discovery when an MCP server advertises the wrong authorization server or none ([#10172](https://github.com/earendil-works/pi/issues/10172)).
+- Added `/mcp login [server]`, completion and optional server selection for login/logout/reconnect, and a server manager with enabled-state and exposure menus. Sign-in accepts pasted remote-browser redirect URLs.
+- Added native tool exposure modes and per-tool patterns, standard resource list/read tools, and per-server OAuth `callbackPort` and `callbackUrl`.
+- Added shell commands `atomic mcp add`, `remove`, `list`, `login`, and `logout` to configure, check, and authenticate file-configured servers without starting a session.
+
+### Changed
+
+- Adopted pi's native MCP client, tool exposure, resources, and server manager. Calls, including codemode calls, use Atomic's permission pipeline. Native OAuth credentials are stored in `mcp-auth.json`.
+
+### Fixed
+
+- OAuth authorization codes are rejected before exchange when the response's `iss` names another issuer, or is missing when the authorization server promises it under RFC 9207.
+- Empty or null optional OAuth token and client registration fields now count as absent. Refresh responses retain the previous refresh token when the new one is empty, and `expires_in: null` no longer immediately expires a token ([#10266](https://github.com/earendil-works/pi/issues/10266)).
+- Empty OAuth scopes fall through to the configured scope instead of overriding it.
+- Tool and resource listing now accepts an empty or null final pagination cursor ([#10266](https://github.com/earendil-works/pi/issues/10266)).
+- Sign-out no longer lets an in-progress OAuth refresh restore deleted credentials.
+- Session shutdown now closes MCP connections that are still opening instead of leaving them running after the session ends.
+- Replacing or unregistering an extension-contributed server now retires its pending connection without leaving a detached transport running.
+- Reloading a session with active MCP servers no longer fails during cleanup of the old connections.
+- OAuth refreshes discovery when a server advertises a changed metadata URL instead of retaining the previous authorization server.
+
+## [0.9.25-alpha.3] - 2026-09-30
+
+### Added
+
+- Set `oauth.clientName` to choose the client name sent during dynamic OAuth registration. The default is `atomic` ([#10226](https://github.com/earendil-works/pi/issues/10226)).
+- HTTP MCP servers can set `"auth": { "provider": "<provider>" }` to send the current `/login` token of a provider as the bearer token instead of using MCP OAuth. The token is read for every request and is never stored by MCP. It is accepted only from the global `mcp.json` and extension registrations, requires `https` except on `localhost`, `127.0.0.1`, and `[::1]`, and is sent only to the server's origin.
+
+### Fixed
+
+- MCP sign-in now displays a clickable terminal hyperlink and a Cmd/Ctrl+click hint, including when the authorization URL wraps across lines ([#10186](https://github.com/earendil-works/pi/issues/10186)).
+- MCP tool names now use JavaScript-safe identifiers. Tools whose names sanitize to the same identifier all receive deterministic hash suffixes, preventing codemode calls from reaching the wrong tool. Server names that differ only in `-` and `_` conflict ([#10239](https://github.com/earendil-works/pi/issues/10239)).
+- Cached MCP tools now reconnect after `/login <provider>` when a provider-authenticated server needs sign-in, without requiring `/mcp reconnect`.
+
 ## [0.9.25-alpha.1] - 2026-09-29
 
 ### Changed

package/dist/builtin/mcp/OAUTH.md

@@ -1,61 +1,36 @@
-# OAuth 2.1 Authentication for MCP
+# MCP OAuth authentication
 
-This document describes the OAuth 2.1 + PKCE authentication implementation for the Pi MCP Adapter using the official MCP SDK.
+Atomic supports OAuth authorization-code login with PKCE, authorization server discovery, dynamic client registration, and token refresh for HTTP MCP servers. Most servers need only a URL:
 
-## Overview
-
-The Pi MCP Adapter uses the official MCP SDK's built-in OAuth implementation, which provides:
-
-- **Automatic OAuth endpoint discovery** (RFC 9728) - No manual configuration needed
-- **Dynamic client registration** (RFC 7591) - No clientId needed for most servers
-- **Automatic callback handling** - Built-in HTTP server handles callbacks automatically
-- **Automatic token refresh** - SDK handles token refresh transparently
-
-## Features
+```json
+{ "mcpServers": { "sentry": { "url": "https://mcp.sentry.dev/mcp" } } }
+```
 
-- ✅ **PKCE (S256)** - Mandatory code challenge method for OAuth 2.1
-- ✅ **Automatic Callback Server** - No URL copying needed, browser redirects automatically
-- ✅ **Dynamic Client Registration** - Automatically registers with OAuth servers
-- ✅ **Auto-Discovery** - Discovers OAuth endpoints from server metadata
-- ✅ **Automatic Token Refresh** - SDK handles expired tokens automatically
-- ✅ **State Parameter Validation** - CSRF protection
-- ✅ **Secure Token Storage** - Stored in `~/.pi/agent/mcp-oauth/<server>/tokens.json`
+OAuth applies when the server has no static `Authorization` header or provider-token configuration. Keep personal credentials in user-global configuration, not shared project files.
 
-## Configuration
+## Sign in and out
 
-### Minimal Configuration (Recommended)
+Run `/mcp login sentry`, select the server in `/mcp` and choose **Sign in**, or run `atomic mcp login sentry` from a shell. Session commands without a name choose an eligible server when unambiguous or ask you to select one; shell commands require a server name.
 
-For most MCP servers, you only need the URL:
+Atomic opens the browser and displays a clickable authorization URL. Approve access in the browser. If it runs on another machine, such as an SSH client, paste the complete URL it was redirected to into Atomic's waiting sign-in prompt. Atomic validates the state and issuer before exchanging the code. Treat both authorization and redirect URLs as sensitive.
 
-```json
-{
-  "mcpServers": {
-    "my-oauth-server": {
-      "url": "https://api.example.com/mcp"
-    }
-  }
-}
-```
+Successful login reconnects the server. Session login requires an interactive UI; shell login opens the browser without starting a session. Sign in before unattended work. Shell login waits up to 300 seconds by default; use `--timeout <seconds>` to change that budget. A running session uses new credentials on its next turn. If a server requests additional scope later, sign in again.
 
-OAuth is automatically enabled for HTTP servers. The SDK will:
-- Auto-detect if the server requires OAuth
-- Discover OAuth endpoints from the server
-- Register a dynamic client (if supported by the server)
-- Handle the entire OAuth flow including callback
+Run `/mcp logout sentry` or `atomic mcp logout sentry` to delete its stored credentials. Signing out is also available in the manager.
 
-### Optional Configuration
+## Pre-registered clients
 
-You can optionally provide a pre-registered client:
+For servers without dynamic client registration:
 
 ```json
 {
   "mcpServers": {
-    "my-oauth-server": {
-      "url": "https://api.example.com/mcp",
-      "auth": "oauth",
+    "example": {
+      "url": "https://mcp.example.com/mcp",
       "oauth": {
-        "clientId": "your-client-id",
-        "clientSecret": "your-client-secret",
+        "clientId": "registered-client",
+        "clientSecret": "${EXAMPLE_SECRET}",
+        "callbackPort": 8765,
         "scope": "read write"
       }
     }
@@ -63,263 +38,78 @@ You can optionally provide a pre-registered client:
 }
 ```
 
+`clientSecret` is optional. It can reference an environment variable or use a whole-value `!command` expression. The redirect URI must match the client's registration.
 
+| Option | Meaning |
+| --- | --- |
+| `clientId` | Pre-registered client ID. Omit it for dynamic registration. |
+| `clientSecret` | Optional secret for a confidential client. |
+| `scope` | Space-separated scopes when the server does not advertise them. Later requests are added to this value. |
+| `clientName` | Dynamic registration name, default `atomic`. Sign out before registering under a changed name. |
+| `callbackPort` | Port for `http://127.0.0.1:<port>/callback`. |
+| `callbackUrl` | Another registered loopback redirect URI. |
+| `authServerMetadataUrl` | Trusted authorization server metadata document to use instead of discovery. |
 
-### Configuration Options
-
-- `url` - The MCP server URL (required)
-- `auth` - Set to `"oauth"` to force OAuth, `false` to disable, or omit to auto-detect
-- `oauth.grantType` - `"authorization_code"` (default, browser flow) or `"client_credentials"` (non-interactive)
-- `oauth.clientId` - Pre-registered client ID (optional, SDK tries dynamic registration if not provided)
-- `oauth.clientSecret` - Client secret for confidential clients (optional)
-- `oauth.scope` - Requested OAuth scopes (optional)
+`callbackUrl` must use HTTP on `localhost`, `127.0.0.1`, or `[::1]`, without query or fragment. Atomic sends it as written. If it omits a port, Atomic adds `callbackPort` or a free port, as allowed for loopback redirects by RFC 8252. Use a fixed port when the client registration requires an exact URI.
 
-### Non-Interactive `client_credentials`
+## Override authorization server discovery
 
-For machine-to-machine OAuth, configure `grantType: "client_credentials"`.
+Atomic normally finds the authorization server through protected resource metadata and checks its metadata issuer. If a server advertises the wrong authorization server or none, configure the correct metadata document:
 
 ```json
 {
   "mcpServers": {
-    "my-service": {
-      "url": "https://api.example.com/mcp",
-      "auth": "oauth",
+    "example": {
+      "url": "https://mcp.example.com/mcp",
       "oauth": {
-        "grantType": "client_credentials",
-        "clientId": "service-client-id",
-        "clientSecret": "service-client-secret",
-        "scope": "read write"
+        "authServerMetadataUrl": "https://example.okta.com/.well-known/openid-configuration"
       }
     }
   }
 }
 ```
 
-This flow does not open a browser or use callback handling.
+The document may use RFC 8414 or OpenID Connect discovery. Atomic trusts it as configured, including its issuer, so only point it at a document you trust. The URL must use HTTPS except for HTTP on `localhost`, `127.0.0.1`, or `[::1]`.
 
-## Usage
+An authorization response's `iss` must name the flow's authorization server. If the metadata promises `authorization_response_iss_parameter_supported`, the response must include `iss`. Mismatched or required-but-missing issuers are rejected before code exchange under RFC 9207. Pasted redirect URLs have the same checks as browser callbacks.
 
-### Step 1: Authenticate
+## Tokens and refresh
 
-Run the `/mcp-auth` command with the server name:
-
-```
-/mcp-auth my-oauth-server
-```
+Credentials are stored in `~/.atomic/agent/mcp-auth.json`, keyed by server URL. `ATOMIC_CODING_AGENT_DIR` relocates the agent directory. Tokens refresh when expired or rejected, and signing out removes the stored credentials.
 
-Manual `/mcp-auth` is the default flow. If you set `settings.autoAuth: true`, proxy/direct tool execution will trigger OAuth automatically when a server returns `needs-auth`, then retry the original operation once.
+Optional OAuth response fields that are empty or null count as absent, including `scope`, `refresh_token`, `id_token`, and `client_secret`. A refresh response with no new refresh token keeps the previous one. `expires_in: null` does not immediately expire an access token. Empty scope values fall through to the next scope source.
 
-This will:
-1. Start the callback server (configured port, default `19876`)
-2. Discover OAuth endpoints automatically
-3. Register a dynamic client (if no clientId provided)
-4. Open your browser for authentication
-5. Wait for the automatic callback
-6. Complete the OAuth flow
-7. Store tokens securely
-
-### Step 2: Use the Server
-
-Once authenticated, use the server normally:
-
-```
-mcp({ server: "my-oauth-server" })
-mcp({ tool: "my-tool", args: '{"key": "value"}' })
-```
+Old adapter credential files are not imported. Sign in through `/mcp login <server>` or `atomic mcp login <server>` to authorize the native client.
 
-The SDK automatically:
-- Adds the access token to requests
-- Refreshes expired tokens automatically
-- Re-authenticates if tokens are invalid
+## Use a provider login instead
 
-To clear stored OAuth credentials and force a fresh authorization:
-
-```
-/mcp logout my-oauth-server
-```
-
-## How It Works
-
-### Authentication Flow
-
-```
-┌─────────┐     ┌──────────────┐     ┌─────────────────┐
-│   Pi    │────▶│  MCP Server  │────▶│  OAuth Server   │
-│         │     │              │     │                 │
-│ 1. Init │     │ 2. Discovery │     │ 3. Register     │
-│         │     │              │     │                 │
-│         │◀────│              │◀────│ 4. Auth URL     │
-│         │     │              │     │                 │
-│         │────▶│  Callback    │◀────│ 5. Browser      │
-│         │     │  Server      │     │    Redirect     │
-│         │     │              │     │                 │
-│         │◀────│              │◀────│ 6. Code         │
-│         │     │              │     │                 │
-│         │────▶│              │────▶│ 7. Exchange     │
-│         │     │              │     │                 │
-│         │◀────│              │◀────│ 8. Tokens       │
-└─────────┘     └──────────────┘     └─────────────────┘
-```
-
-### Auto-Discovery
-
-The SDK attempts to discover OAuth endpoints using:
-
-1. **RFC 9728 Metadata** - Fetches `/.well-known/oauth-protected-resource`
-2. **WWW-Authenticate Header** - Parses `resource_metadata` from 401 responses
-
-### Dynamic Client Registration
-
-If no `clientId` is provided, the SDK:
-
-1. Discovers the registration endpoint from OAuth metadata
-2. Registers a new client with:
-   - `client_name`: "Pi Coding Agent"
-   - `redirect_uris`: `["http://localhost:<active-callback-port>/callback"]`
-   - `grant_types`: `["authorization_code", "refresh_token"]`
-3. Stores the registered client credentials
-
-### Callback Server
-
-A Node.js HTTP server runs on `localhost` at path `/callback`:
-
-- Preferred callback port is `19876` (or `MCP_OAUTH_CALLBACK_PORT` if set)
-- For dynamic registration, if the preferred port is busy, the adapter scans forward for a free local port
-- For pre-registered clients (`oauth.clientId`), the adapter requires the exact configured callback port
-
-- Handles `code`, `state`, and `error` parameters
-- Displays success/error HTML pages
-- Validates state parameter for CSRF protection
-- Has a 5-minute timeout for pending authorizations
-- Rejects and removes pending authorization waiters during session restart/shutdown before replacement-session startup continues
-
-## Token Storage
-
-Tokens are stored per-server in `~/.pi/agent/mcp-oauth/<server>/tokens.json`:
+A server can use a provider token instead of MCP OAuth:
 
 ```json
-{
-  "tokens": {
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
-    "expiresAt": 1709769600,
-    "scope": "read write"
-  },
-  "clientInfo": {
-    "clientId": "auto-registered-client-id",
-    "clientSecret": "auto-generated-secret"
-  },
-  "serverUrl": "https://api.example.com/mcp"
-}
-```
-
-Example directory structure:
+{ "mcpServers": { "radius": { "url": "https://radius.example/mcp", "auth": { "provider": "radius" } } } }
 ```
-~/.pi/agent/mcp-oauth/
-├── linear/
-│   └── tokens.json
-├── github/
-│   └── tokens.json
-└── ...
-```
-
-The `serverUrl` field ensures credentials are invalidated if the server URL changes.
-
-## Security Considerations
-
-### PKCE
-
-All OAuth flows use PKCE with the S256 method, preventing authorization code interception attacks.
-
-### State Parameter
-
-A cryptographically secure random state parameter is generated for each flow and validated on callback.
-
-### File Permissions
 
-Token files (`tokens.json`) are created with `0o600` permissions and stored in per-server directories with `0o700` permissions (readable only by owner).
+Run `/login radius`, then retry the MCP call. Atomic reads the current token for every request and does not copy it into MCP credential storage.
 
-### URL Validation
-
-Credentials are tied to a specific server URL. If the URL changes, the credentials are invalidated and re-authentication is required.
+This setting is accepted only in global configuration and extension registrations, not project files or package manifests. HTTPS is required except on exact loopback hosts. Tokens go only to the server's configured origin; only same-origin `307` and `308` redirects are followed.
 
 ## Troubleshooting
 
-### "No OAuth tokens found"
-
-Run `/mcp-auth <server>` to authenticate.
-
-### "Failed to discover OAuth endpoints"
-
-The SDK automatically discovers OAuth endpoints from the MCP server. If discovery fails, the server may require a pre-registered client ID:
-
-```json
-{
-  "mcpServers": {
-    "server": {
-      "url": "https://api.example.com/mcp",
-      "auth": "oauth",
-      "oauth": {
-        "clientId": "your-client-id",
-        "scope": "read"
-      }
-    }
-  }
-}
-```
-
-### "Dynamic client registration not supported"
-
-Some servers require pre-registered clients. Obtain a client ID from your OAuth provider and add it to the config.
-
-### Callback server already in use
-
-For dynamic registration, if the preferred callback port is busy, the adapter scans for the next available local port.
-
-For pre-registered OAuth clients (`oauth.clientId`), the callback redirect URI must match exactly. In that case, free the configured port or set `MCP_OAUTH_CALLBACK_PORT` to the registered port. For clients registered like Slack MCP's Claude-compatible `http://localhost:3118/callback`, set `MCP_OAUTH_CALLBACK_PORT=3118`.
-
-### Browser doesn't open
-
-If the browser fails to open (e.g., in SSH sessions), Atomic displays the exact complete authorization URL for manual login, including all paths and parameters (state, callback, PKCE, resource, and any credentials). These intentional login instructions are not diagnostic logs; transport and RPC error diagnostics remain redacted. Treat the displayed URL as sensitive and do not share it. Browser-launch failure still cancels the pending attempt, so its callback cannot complete authentication; configure a working browser opener and retry `/mcp-auth <server-name>`.
+- **Sign-in required:** run `/mcp login <server>` before unattended calls.
+- **Dynamic registration unavailable:** obtain a client ID from the provider and configure `oauth.clientId`.
+- **Redirect mismatch or callback port busy:** compare `callbackPort` and `callbackUrl` with the registered URI. Free its port or update the registration.
+- **Browser cannot reach Atomic:** paste the complete redirected URL into the waiting sign-in prompt.
+- **Wrong authorization page:** check server metadata, then use `authServerMetadataUrl` only if you know the correct trusted document.
+- **Issuer mismatch:** check the authorization server's metadata and callback behavior. Do not accept an unexpected issuer to bypass the failure.
+- **Provider token missing or rejected:** run `/login <provider>` and retry.
 
-## Architecture
-
-The OAuth implementation uses the following modules:
-
-- `mcp-auth.ts` - Auth storage and retrieval (per-server `tokens.json` files)
-- `mcp-oauth-provider.ts` - SDK OAuthClientProvider implementation
-- `mcp-callback-server.ts` - Node.js HTTP callback server
-- `mcp-auth-flow.ts` - High-level auth flow using SDK transport
-
-## SDK Integration
-
-The implementation uses these SDK exports:
-
-```typescript
-import {
-  auth,
-  UnauthorizedError,
-  OAuthClientProvider,
-} from "@modelcontextprotocol/sdk/client/auth.js"
-
-import {
-  StreamableHTTPClientTransport,
-} from "@modelcontextprotocol/sdk/client/streamableHttp.js"
-```
-
-The `McpOAuthProvider` class implements `OAuthClientProvider` and is passed to `StreamableHTTPClientTransport`:
-
-```typescript
-const transport = new StreamableHTTPClientTransport(url, {
-  authProvider: new McpOAuthProvider(serverName, serverUrl, config, callbacks),
-})
-```
+For configuration, tool exposure, and connection diagnostics, see [MCP servers](../coding-agent/docs/mcp-servers.md).
 
 ## References
 
-- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
-- [MCP Authorization Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
-- [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11)
-- [PKCE (RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636)
-- [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591)
-- [OAuth Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728)
+- [MCP authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
+- [PKCE, RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
+- [Dynamic client registration, RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)
+- [Authorization server metadata, RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)
+- [Authorization response issuer, RFC 9207](https://datatracker.ietf.org/doc/html/rfc9207)
+- [Protected resource metadata, RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)