These are the transport shapes a saved MCP server definition can use, and the OAuth workflow that HTTP transports can authenticate with.

When Codex owns the MCP connection, explicit connectionTimeoutMs values control startup, including initialization and initial tool discovery, and requestTimeoutMs values control tool calls. Apus preserves millisecond precision when converting these values to Codex's seconds-based settings; unset values keep Codex's defaults. The supportsParallelToolCalls hint is also forwarded. Codex can additionally run tools with a readOnlyHint annotation in parallel.

Stdio transport

Launches a local child process and communicates over stdin/stdout.

Shutdown can force a slow anchor and relay to exit after their control, output, and lineage pipes close. A still-live anchor is killed and reaped through its relay. If the anchor group is already gone, the host can kill an unresponsive relay directly. The host then confirms actual exit and group disappearance. Confirmed cleanup completes normally; a later connection starts a fresh server. Unconfirmed cleanup still reports an error with the missing closure facts, elapsed time, and any failed signal delivery. The cleanup deadline does not change when shutdown escalates.

SSE / HTTP transport

Connects to a remote MCP server over HTTP Server-Sent Events.

Example:

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "auth": "oauth",
        "requestTimeoutMs": 20000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Sensitive values in url (userinfo) and headers are redacted in logs and status output. apus mcp doctor warns when sensitive-looking headers or env entries contain literal values, so operators can move those values out of committed config.

If a legacy SSE message endpoint returns HTTP 404, or a stateful Streamable HTTP session expires, Apus retires that connection and reconnects on the next discovery. The failed call is reported without replaying it, because a tool may have already changed state before the connection failed.

OAuth workflow

OAuth is for HTTP MCP servers that advertise the MCP OAuth flow. Static Authorization headers are ignored for a server while auth: "oauth" is enabled. By default, OAuth credentials are shared and operator-managed. Credentials saved by apus mcp login work with embedded MCP, CLI runners, and the local Codex app-server.

Native MCP OAuth sessions live in the owner-only shared SQLite database at <state-dir>/state/apus.sqlite (mcp_oauth_stores). The row can contain access and refresh tokens, dynamic client registration secrets, discovery metadata, and the temporary PKCE verifier. Refresh, login, and logout use the same SQLite lease, so parallel Apus processes cannot consume one refresh token or resurrect a logged-out session.

Upgrades from the retired <state-dir>/mcp-oauth/*.json store are handled only by apus doctor --fix. Runtime code never reads, writes, or falls back to those files.

Until shared credentials are available, Apus omits only that MCP server from the agent runtime instead of failing the agent turn. The operator, or an agent with shell access, can then run apus mcp login <name> and use the server on a later turn.

If a server rejects a token with insufficient_scope, Apus preserves the requested scope and asks for apus mcp login <name> instead of repeating a refresh that cannot grant new scope. That login starts a new authorization request while keeping the previous token until replacement credentials are saved.

When a remote MCP service is already backed by a separate Apus refresh-capable auth profile, you can optionally set oauth.authProfileId. Apus refreshes either credential source before runtime projection and passes only the current access token to the downstream MCP client.

Set oauth.identity: "per-requester" when every authenticated sender should connect a separate account. Per-requester OAuth requires an HTTP server URL and cannot use oauth.authProfileId. Configure gateway.publicOrigin as the externally reachable HTTPS origin of the Gateway; HTTP is accepted only for literal loopback hosts (localhost, 127.0.0.1, or [::1]) during local development. The provider redirects to <gateway.publicOrigin>/oauth/mcp/callback after authorization.

{
  gateway: {
    publicOrigin: "https://gateway.example.com",
  },
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        auth: "oauth",
        oauth: {
          identity: "per-requester",
          scope: "docs.read",
        },
      },
    },
  },
}

The per-requester flow is sender-driven:

1. The sender calls a tool from the server before connecting an account.
2. Apus returns a sign-in link for that sender instead of exposing another sender's credentials.
3. The provider redirects through the Gateway callback. After the callback succeeds, the sender retries the tool call with their connected account.

If gateway.publicOrigin is missing, the sign-in result names that setting and apus doctor reports the same operator fix. apus mcp login and apus mcp logout remain operator-only commands for shared credentials; they do not manage per-requester accounts.

Sign-in links are single-use bearer links: any chat participant who opens one connects their own account to the sender the link was issued for. Use per-requester OAuth in channels where every trusted sender is mutually trusted; a requester-private sign-in handoff is tracked as follow-up work.

The shared operator flow uses the following commands:

Add or update the server with `auth: "oauth"` and any optional OAuth metadata.

```bash
apus mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'
```

For an auth-profile-backed bearer, save the profile binding:

```bash
apus mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'
```

Run login to create the authorization request.

```bash
apus mcp login docs
```

Apus starts the registered loopback callback, prints the authorization URL, and stores temporary OAuth verifier state in shared SQLite. Approve the request in the browser and return to the terminal; token exchange completes automatically after the callback arrives.

Providers may register an HTTP loopback callback without a port, as allowed by RFC 8252. Apus retains that registration for the same `127.0.0.1`, `[::1]`, or `localhost` callback while sending the listener's port in authorization and token requests. Other callback components must match; non-loopback callbacks still require an exact match.

If the browser runs on another machine or cannot reach the printed loopback address, copy the returned code and pass it back to Apus.

```bash
apus mcp login docs --code abc123
```

Use status or doctor to confirm that tokens are present and do not require additional authorization. If status reports `authorization-required` or doctor asks for additional authorization, run `apus mcp login <name>` again.

```bash
apus mcp status --verbose
apus mcp doctor docs --probe
```

Logout removes stored OAuth credentials but keeps the saved server definition.

```bash
apus mcp logout docs
```

If the provider rotates tokens or the authorization state gets stuck, run apus mcp logout <name>, then repeat login. logout can clear credentials for a saved HTTP server even after auth: "oauth" has been removed from config, as long as the server name and URL still identify the credential store entry.

Streamable HTTP transport

streamable-http is an additional transport option alongside sse and stdio. It uses HTTP streaming for bidirectional communication with remote MCP servers.

Apus config uses transport: "streamable-http" as the canonical spelling. CLI-native MCP type: "http" values are accepted when saved through apus mcp set and repaired by apus doctor --fix in existing config, but transport is what embedded Apus consumes directly.

Example:

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 30000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}