@thinkingai/ae-cli 6.0.24 → 6.0.28

package/skills/ae-agent/references/list-skill-assets.md

@@ -0,0 +1,35 @@
+# agent +list-skill-assets (List Skill Assets)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List all files in a Skill's `assets` directory.
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/assets`.
+- Returns `{ items: [...] }` with file metadata (name, size, etc.).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+
+## Command
+```bash
+ae-cli agent +list-skill-assets --id <skill-cuid>
+ae-cli agent +list-skill-assets --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+
+## Decision Rules
+- Use `+list-skills` to confirm the Skill ID before listing assets.
+- Read operation: no confirmation prompt needed.
+- Assets include images, documents, and other supporting files for the Skill.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+list-skill-assets` → `+read-skill-asset` or `+upload-skill-asset`

package/skills/ae-agent/references/list-skill-market.md

@@ -0,0 +1,59 @@
+# agent +list-skill-market (List Skill Market)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Market (browse) / read**
+
+## Use Cases
+- List Skills from the market (only approved items; system / company / personal scopes).
+- Endpoint: `GET /api/sandbox/agent/skills/market`.
+- Supports filtering by scope, category, search, and sort, with pagination.
+- Use this to discover Skills before copying one with `+copy-skill`.
+
+## Mandatory Rules (MUST)
+- `--scope` must be one of the market scopes when provided (see below).
+- `--category` must be one of the market category keys when provided (see below).
+- `--sort` must be one of the sort options when provided (see below).
+- Only approved Skills appear in the market; pending/rejected submissions are not listed.
+
+## Market Scope
+`all | system | company | custom` (`custom` = personal; `all` = system + company + personal)
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Sort Options
+`newest | calls | likes` (`calls` sorts Skills by download count)
+
+## Command
+```bash
+ae-cli agent +list-skill-market
+ae-cli agent +list-skill-market --search "code review" --sort newest --format table
+ae-cli agent +list-skill-market --scope company --category dev_tool --sort calls
+ae-cli agent +list-skill-market --limit 20 --offset 0
+ae-cli agent +list-skill-market --dry-run --scope system
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Market scope (see above; default `all`) |
+| `--category` | No | Category key (see above) |
+| `--search` | No | Fuzzy search on name/displayName/description |
+| `--sort` | No | Sort option (see above; default `newest`) |
+| `--limit` | No | Page size (1–100, default 50) |
+| `--offset` | No | Page offset (>=0, default 0) |
+
+## Decision Rules
+- When the user wants to browse available Skills, call this first.
+- `--sort calls` finds the most-downloaded Skills; `--sort newest` finds the latest.
+- Use `--format table` for a scannable overview.
+- To bring a system/company Skill into your personal workspace, use `+copy-skill` (not `+add-skill`).
+
+## Next Steps on Failure
+- `--scope must be one of...`: use one of the market scope values.
+- `--category must be one of...`: use one of the category keys.
+- Empty result: widen filters (remove `--category` / `--scope`).
+
+## Recommended Chaining
+- `+list-skill-market` (browse) → `+copy-skill` (copy to personal) → `+list-skills` (verify)

package/skills/ae-agent/references/list-skill-references.md

@@ -0,0 +1,36 @@
+# agent +list-skill-references (List Skill References)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List all `.md` files in a Skill's `references` directory.
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/references`.
+- Returns `{ items: [...] }` with file metadata (name, size, etc.).
+- Only `.md` files are listed (references directory is markdown-only).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+
+## Command
+```bash
+ae-cli agent +list-skill-references --id <skill-cuid>
+ae-cli agent +list-skill-references --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+
+## Decision Rules
+- Use `+list-skills` to confirm the Skill ID before listing references.
+- Read operation: no confirmation prompt needed.
+- References are `.md` files that provide additional context for the Skill.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+list-skill-references` → `+read-skill-reference` or `+upload-skill-reference`

package/skills/ae-agent/references/list-skill-scripts.md

@@ -0,0 +1,35 @@
+# agent +list-skill-scripts (List Skill Scripts)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List all files in a Skill's `scripts` directory.
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/scripts`.
+- Returns `{ items: [...] }` with file metadata (name, size, etc.).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+
+## Command
+```bash
+ae-cli agent +list-skill-scripts --id <skill-cuid>
+ae-cli agent +list-skill-scripts --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+
+## Decision Rules
+- Use `+list-skills` to confirm the Skill ID before listing scripts.
+- Read operation: no confirmation prompt needed.
+- Scripts are executable files that support the Skill's functionality.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+list-skill-scripts` → `+read-skill-script` or `+upload-skill-script`

package/skills/ae-agent/references/list-skill-shares.md

@@ -0,0 +1,49 @@
+# agent +list-skill-shares (List Skill Shares)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Share (peer-to-peer) / read**
+
+## Use Cases
+- List Skill shares (received by default; use `--direction sent` for outgoing).
+- Endpoint: `GET /api/sandbox/agent/skills/shares`.
+- Sharing is Skill-only — MCP has no share flow.
+- Use this to find a share ID before `+accept-skill-share` / `+reject-skill-share`.
+
+## Mandatory Rules (MUST)
+- `--direction` must be one of the share directions (see below) when provided.
+- `--status` must be one of the share statuses (see below) when provided.
+- Do not guess share IDs. Always call `+list-skill-shares` first when a share ID is needed.
+
+## Share Directions
+`received | sent`
+
+## Share Statuses
+`pending | accepted | rejected`
+
+## Command
+```bash
+ae-cli agent +list-skill-shares
+ae-cli agent +list-skill-shares --direction received --status pending --format table
+ae-cli agent +list-skill-shares --direction sent
+ae-cli agent +list-skill-shares --dry-run --direction received
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--direction` | No | `received` (default) \| `sent` |
+| `--status` | No | Filter by status (see above) |
+
+## Decision Rules
+- By default, lists shares the current user has **received**; use `--direction sent` to list outgoing shares.
+- `--status pending` filters to shares awaiting action.
+- Capture the share `id` for `+accept-skill-share` / `+reject-skill-share`.
+
+## Next Steps on Failure
+- `--direction must be one of...`: use `received` or `sent`.
+- `--status must be one of...`: use one of the share statuses.
+- Empty result: no shares match the filter.
+
+## Recommended Chaining
+- `+list-skill-shares --direction received --status pending` → confirm share `id` → `+accept-skill-share` / `+reject-skill-share`

package/skills/ae-agent/references/list-skill-submissions.md

@@ -0,0 +1,45 @@
+# agent +list-skill-submissions (List Skill Submissions)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Approval (company-scope publish) / read**
+
+## Use Cases
+- List Skill submissions (approvals).
+- Endpoint: `GET /api/sandbox/agent/skills/submissions`.
+- Root sees all company submissions; non-root users see only their own.
+- Use this to find a submission ID before `+cancel-skill-submission` / `+approve-skill` / `+reject-skill`.
+
+## Mandatory Rules (MUST)
+- `--status` must be one of the submission statuses (see below) when provided.
+- Do not guess submission IDs. Always call `+list-skill-submissions` first when a submission ID is needed.
+
+## Submission Statuses
+`pending | approved | rejected | cancelled`
+
+## Command
+```bash
+ae-cli agent +list-skill-submissions
+ae-cli agent +list-skill-submissions --status pending --format table
+ae-cli agent +list-skill-submissions --mine
+ae-cli agent +list-skill-submissions --dry-run --status pending
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--status` | No | Filter by status (see above) |
+| `--mine` | No | Only show submissions created by the current user (root only) |
+
+## Decision Rules
+- When the user wants to review pending submissions, use `--status pending`.
+- Root users can see all company submissions; non-root users only see their own.
+- `--mine` (root only) filters to the current user's own submissions.
+- Capture the submission `id` for `+cancel-skill-submission` / `+approve-skill` / `+reject-skill`.
+
+## Next Steps on Failure
+- `--status must be one of...`: use one of the submission statuses.
+- Empty result: no submissions match the filter.
+
+## Recommended Chaining
+- `+list-skill-submissions` → confirm submission `id` → `+cancel-skill-submission` (submitter/root) or `+approve-skill` / `+reject-skill` (root)

package/skills/ae-agent/references/list-skills.md

@@ -0,0 +1,37 @@
+# agent +list-skills (List Skills)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- List Skills visible to the current user (personal / company / system scopes).
+- Returns an array of Skill summaries; key fields include `id`, `name`, `description`, `scope`, `enabled`.
+
+## Mandatory Rules (MUST)
+- Do not guess Skill record IDs. Always call `+list-skills` first when an ID is needed.
+
+## Command
+```bash
+ae-cli agent +list-skills
+ae-cli agent +list-skills --scope personal --format table
+ae-cli agent +list-skills --scope company
+ae-cli agent +list-skills --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--scope` | No | Filter by scope: `personal` \| `company` \| `system` |
+
+## Decision Rules
+- When the user needs a Skill ID for `+del-skill` / `+toggle-skill` / `+copy-skill` / `+submit-skill` / `+share-skill` / `+set-skill-meta`, call this first.
+- Use `--format table` for a scannable overview of many skills.
+
+## Next Steps on Failure
+- Empty result: confirm account permissions and the active AE host.
+- Auth error: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+toggle-skill` / `+del-skill` / `+copy-skill` / `+submit-skill` / `+share-skill`
+- `+list-skill-market` (browse) → `+add-skill` (create) → `+list-skills` (verify)

package/skills/ae-agent/references/mcp-auth-disconnect.md

@@ -0,0 +1,50 @@
+# agent +mcp-auth-disconnect (Disconnect MCP OAuth)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Disconnect the OAuth authorization for an MCP server.
+- Endpoint: `POST /api/sandbox/agent/mcp-servers/[id]/auth/disconnect`.
+- Clears the stored token / credentialJson / identityJson and marks the server `enabled=false`.
+- Use this to revoke a stale credential before re-authorizing, or to fully detach from an OAuth provider.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- After disconnect, the MCP server is disabled (`enabled=false`); re-enable with `+toggle-mcp --enabled true` after re-authorizing.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Disconnect OAuth
+ae-cli agent +mcp-auth-disconnect --id <mcp-cuid> --yes
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-auth-disconnect --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+
+## Decision Rules
+- If the user wants to revoke an MCP's OAuth credential and disable the server, use this command.
+- After disconnecting, to use the MCP again: run `+mcp-auth-start` to re-authorize, then `+toggle-mcp --enabled true` (if not auto-enabled).
+- Disconnect does NOT delete the MCP server record — it only clears the OAuth credential. To delete the record, use `+del-mcp`.
+
+## Response Shape
+```json
+{
+  "ok": true,
+  "status": "disconnected",
+  "server": { "id": "clxxx", "name": "my-mcp", "displayName": "My MCP", "scope": "personal", "providerKey": "github" }
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+mcp-auth-disconnect` → `+mcp-auth-start` (re-authorize) → `+mcp-auth-status` (verify) → `+toggle-mcp --enabled true`

package/skills/ae-agent/references/mcp-auth-start.md

@@ -0,0 +1,61 @@
+# agent +mcp-auth-start (Start MCP OAuth)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Start the OAuth authorization flow for an MCP server (CLI mode).
+- Endpoint: `POST /api/sandbox/agent/mcp-servers/[id]/auth/start`.
+- The sandbox endpoint always uses `cliMode=true`: the server derives the OAuth callback URL itself, so no `origin` is required.
+- Returns an `authorizeUrl` — the user opens it in a browser, authorizes, then polls `+mcp-auth-status` until the status becomes `authenticated`.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- The MCP server must have `authMode=oauth2`; otherwise the server returns `oauth_not_required`.
+- `--redirect-after` (when provided) must be same-origin as the service base URL; otherwise it is rejected.
+- `--cli` defaults to `true` and is always true on the sandbox endpoint — it is for documentation/compat only.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Start OAuth for an MCP server
+ae-cli agent +mcp-auth-start --id <mcp-cuid> --yes
+
+# With a redirect-after URL
+ae-cli agent +mcp-auth-start --id <mcp-cuid> --redirect-after "https://app.example.com/mcp/done" --yes
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-auth-start --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+| `--redirect-after` | No | URL to redirect to after OAuth completes (must be same-origin as the service base URL) |
+| `--cli` | No | CLI mode (always `true` on the sandbox endpoint; server derives the callback URL) |
+
+## Decision Rules
+- If the user needs to authorize an OAuth-based MCP server, use this command.
+- The command prints the `authorizeUrl` to stderr (when a TTY is detected) with guidance to open it in a browser and then poll `+mcp-auth-status`.
+- The response also includes `expiresAt` (the auth session expiry, ~10 minutes) and `redirectUri` (the server-derived callback).
+- After the user completes authorization in the browser, poll `+mcp-auth-status --id <id>` until `status` is `authenticated`.
+
+## Response Shape
+```json
+{
+  "authorizeUrl": "https://provider.com/oauth/authorize?...",
+  "expiresAt": "2026-07-06T12:10:00.000Z",
+  "redirectUri": "https://te-claude.example.com/agent/api/mcp-auth/callback",
+  "server": { "id": "clxxx", "name": "my-mcp", "displayName": "My MCP", "scope": "personal", "providerKey": "github" }
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+- `400` oauth_not_required: the MCP server does not use OAuth; check `--auth-mode`.
+- `400` origin_required / origin_protocol_unsupported / origin_illegal: check the `--redirect-after` URL.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+mcp-auth-start` → (browser authorize) → `+mcp-auth-status` (poll) → `+mcp-tools` (verify)

package/skills/ae-agent/references/mcp-auth-status.md

@@ -0,0 +1,56 @@
+# agent +mcp-auth-status (Query MCP OAuth Status)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- Query the OAuth authorization status of an MCP server.
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/[id]/auth/status`.
+- Used as the polling step after `+mcp-auth-start`: the user authorizes in a browser, then polls this command until `status` becomes `authenticated`.
+- Internally attempts an auto-refresh of soon-to-expire tokens before reporting status.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+
+## Command
+```bash
+# Poll OAuth status
+ae-cli agent +mcp-auth-status --id <mcp-cuid>
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-auth-status --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+
+## Decision Rules
+- Poll this command after `+mcp-auth-start` until `status` is `authenticated`.
+- The `status` field can be:
+  - `not_required` — the MCP does not use OAuth (authMode ≠ oauth2).
+  - `needs_auth` — no credential exists yet; run `+mcp-auth-start`.
+  - `reauth_required` — the credential has expired; run `+mcp-auth-start` to re-authorize.
+  - `disabled` — the MCP server is disabled; run `+toggle-mcp --enabled true`.
+  - `authenticated` — the credential is valid and ready to use.
+- `authenticated` is `true` only when `status` is `authenticated`.
+- `expiresAt` is the credential expiry (ISO string) or `null` if not applicable.
+
+## Response Shape
+```json
+{
+  "status": "authenticated",
+  "authenticated": true,
+  "expiresAt": "2026-07-06T13:00:00.000Z",
+  "updatedAt": "2026-07-06T12:30:00.000Z",
+  "reason": "oauth_not_required"
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+
+## Recommended Chaining
+- `+mcp-auth-start` → (browser authorize) → `+mcp-auth-status` (poll until `authenticated`) → `+mcp-tools` (verify tools are accessible)

package/skills/ae-agent/references/mcp-stats.md

@@ -0,0 +1,68 @@
+# agent +mcp-stats (MCP Call Statistics)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- Show MCP tool call statistics for the current user over the last N days.
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/stats`.
+- Returns aggregations: total calls, by-server, daily, and daily-by-server.
+
+## Mandatory Rules (MUST)
+- `--days` must be an integer between 1 and 365 when provided; defaults to 30.
+- Statistics are scoped to the authenticated user's own MCP usage.
+
+## Command
+```bash
+# Default: last 30 days
+ae-cli agent +mcp-stats
+
+# Last 7 days
+ae-cli agent +mcp-stats --days 7
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-stats --dry-run --days 7
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--days` | No | Lookback window in days (1-365, default 30) |
+
+## Response Shape
+```json
+{
+  "days": 30,
+  "totalCalls": 128,
+  "byServer": { "clxxx-server-a": 80, "clxxx-server-b": 48 },
+  "daily": [
+    { "date": "2026-06-07", "calls": 5 },
+    { "date": "2026-06-08", "calls": 0 }
+  ],
+  "dailyByServer": {
+    "clxxx-server-a": { "2026-06-07": 3, "2026-06-08": 0 }
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `days` | The lookback window used for this query |
+| `totalCalls` | Sum of all MCP tool calls over the window |
+| `byServer` | Map of `mcpServerId` → call count |
+| `daily` | Array of `{ date, calls }` for each day in the window (oldest → newest) |
+| `dailyByServer` | Map of `mcpServerId` → `{ date: calls }` |
+
+## Decision Rules
+- Use `--days 7` for a weekly review, `--days 30` (default) for a monthly review.
+- `daily` always contains one entry per day in the window (zero-filled), so it is safe to chart directly.
+- `byServer` only contains servers with at least one call in the window; cross-reference IDs with `+list-mcps` to resolve names.
+
+## Next Steps on Failure
+- `--days must be an integer between 1 and 365`: pass an integer in range.
+- `500` 获取 MCP 调用统计失败: an internal aggregation error — retry, then contact the platform maintainer if it persists.
+
+## Recommended Chaining
+- `+mcp-stats` (which servers are active) → `+list-mcps` (resolve server IDs to names)
+- `+mcp-stats` (low/no calls) → `+mcp-tools` (verify the server exposes tools) → `+mcp-auth-start` if `needs_auth`

package/skills/ae-agent/references/mcp-token.md

@@ -0,0 +1,63 @@
+# agent +mcp-token (Get MCP Token)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Credentials / read**
+
+## Use Cases
+- Get the plaintext MCP token for `useMcpToken=true` system MCP servers.
+- Endpoint: `GET /api/sandbox/agent/mcp-credentials/mcp-token`.
+- All such servers share one token; the server decrypts and returns it.
+- This is a product behavior (consistent with the web UI) — the token is returned in plaintext so it can be used as a Bearer credential for MCP API calls.
+
+## Mandatory Rules (MUST)
+- No flags required.
+- The returned token is **plaintext** — handle it as a secret:
+  - Do NOT write it to shell history (avoid `export MCP_TOKEN=$(ae-cli agent +mcp-token)` without precautions).
+  - Do NOT log it or commit it to version control.
+  - Prefer piping directly to the consuming process or a secure store.
+- The command prints a security warning to stderr (when a TTY is detected) reminding the user to safeguard the token.
+
+## Command
+```bash
+# Get the MCP token (prints to stdout as JSON)
+ae-cli agent +mcp-token
+
+# Pipe to a file (avoid shell history)
+ae-cli agent +mcp-token --format json > /dev/shm/mcp-token.json 2>/dev/null
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-token --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| (none) | — | — |
+
+## Decision Rules
+- If the user needs the shared MCP token to call MCP-enabled APIs, use this command.
+- The token is shared across all `useMcpToken=true` system MCP servers — a single call returns it.
+- If `token` is `null`, no credential has been provisioned yet — run `+auto-provision-mcp-credentials` first.
+- Prefer `+list-mcp-credentials` to check credential status without exposing the plaintext token.
+
+## Response Shape
+```json
+{
+  "token": "mcp-xxxxxxxxxxxxxxxx"
+}
+```
+
+When no token is provisioned:
+```json
+{
+  "token": null
+}
+```
+
+## Next Steps on Failure
+- `401` / auth expired: run `ae-cli auth login`.
+- `token: null`: run `+auto-provision-mcp-credentials` to provision the token first.
+
+## Recommended Chaining
+- `+auto-provision-mcp-credentials` (provision) → `+mcp-token` (retrieve) → use as `Authorization: bearer <token>` for MCP API calls

package/skills/ae-agent/references/mcp-tools.md

@@ -0,0 +1,55 @@
+# agent +mcp-tools (List MCP Server Tools)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- List the tools exposed by an MCP server (name, description, input schema).
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/[id]/tools`.
+- Includes OAuth auto-refresh: if the credential is about to expire, the server attempts a refresh before listing tools.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- The MCP server must be enabled and properly configured; otherwise the server returns a structured error.
+
+## Command
+```bash
+ae-cli agent +mcp-tools --id <mcp-cuid>
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-tools --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+
+## Decision Rules
+- If the user wants to see what tools an MCP server provides, use this command.
+- The response includes `server` (id, name, transport) and `tools` (array of `{name, description, inputSchema}`).
+- If the server returns `needs_auth` (400), run `+mcp-auth-start` to start OAuth, then retry.
+- If the server returns `reauth_required` (428), the credential has expired — run `+mcp-auth-start` to re-authorize.
+- If the server returns `disabled` (400), enable the MCP first with `+toggle-mcp --enabled true`.
+
+## Response Shape
+```json
+{
+  "server": { "id": "clxxx", "name": "my-mcp", "transport": "http" },
+  "tools": [
+    { "name": "search", "description": "Search the web", "inputSchema": { "type": "object", "properties": {} } }
+  ]
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+- `400` needs_auth: run `+mcp-auth-start --id <id>`, then poll `+mcp-auth-status`.
+- `428` reauth_required: credential expired — run `+mcp-auth-start` to re-authorize.
+- `400` disabled: run `+toggle-mcp --id <id> --enabled true`.
+- `502` connection_failed: verify the MCP server URL is reachable.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+mcp-tools`
+- `+mcp-tools` (fails needs_auth) → `+mcp-auth-start` → `+mcp-auth-status` → `+mcp-tools`