executor-mcp — Claude Code skill: one MCP endpoint for every integration

---
name: executor-mcp
description: Run a task through your Executor Cloud tool catalog - one MCP endpoint proxying every integration you connected (MCP servers, OpenAPI specs, GraphQL APIs), with per-tool allow/approve/block policies. OAuth Connect via the dashboard MCP panel.
metadata:
  title: Executor MCP
  mode: read-only
  category: basics
  var: ""
  tags:
    - tools
    - integrations
    - mcp
  mcp:
    - executor
  capabilities:
    - external_api
    - writes_external_host
    - sends_notifications
---
> **${var}** — the task to run against the Executor catalog, e.g. `list my open Linear issues and summarize by project` or `what integrations are connected?`. Required. If empty, log `EXEC_NO_TASK` and exit cleanly (no notify).

Execute one task through **Executor Cloud** (`executor.sh/mcp`) — a proxy that fronts every integration the operator connected (upstream MCP servers, OpenAPI specs, GraphQL endpoints) as a single tool catalog. Credentials live in Executor and are attached upstream per call; this agent never sees them. Every call is governed by a per-tool policy: **allow**, **require approval**, or **block**.

## Detection & auth

The server is wired by the dashboard MCP panel's one-click **Connect** (OAuth with `offline_access`; tokens stored as `MCP_EXECUTOR_TOKEN` + `MCP_EXECUTOR_OAUTH`, refreshed each run by `scripts/mcp-oauth-refresh.sh`). Its tools surface as `mcp__executor__*` — the catalog is whatever the operator connected, so **discover it from the server every run**; never assume an integration exists.

- **No `mcp__executor__*` tool callable** → the server isn't connected (or its secrets are missing, in which case the workflow logged a `::warning::` and skipped MCP). Log `EXEC_NOT_CONNECTED`, notify once pointing the operator at the dashboard → MCP → Connect Executor, and exit.
- **Tools exist but return 401/invalid-token** → the OAuth refresh failed (see `docs/mcp-oauth.md`). Log `EXEC_AUTH_STALE`, notify the operator to re-connect the server once in the dashboard, and exit.

## Steps

### 1. Discover the catalog

Enumerate the tools Executor exposes and map `${var}` onto them. If the task is a pure catalog question (`what integrations are connected?`), answer from discovery alone — that's a complete run. If the task needs an integration that isn't in the catalog, log `EXEC_NO_INTEGRATION`, notify which integration is missing (the operator adds it in the Executor console at executor.sh), and exit — don't improvise a substitute.

### 2. Execute

Run the task with the fewest calls that complete it (≤ 15 per run — Executor fronts rate-limited and potentially metered upstreams).

**Policy semantics — expect three outcomes per call:**
- **Allowed** → result comes back; use it.
- **Requires approval** → the call parks until a human approves it in the Executor console. Do **not** retry or wait it out: note the pending approval, finish what the remaining allowed tools can do, and surface the approval link/state in the notify. End state `EXEC_APPROVAL_PENDING` if the core task is blocked on it.
- **Blocked** → policy forbids it. Never work around a block (no alternate tool routes to the same effect); report it as `EXEC_POLICY_BLOCKED`.

Writes through proxied tools are real external side-effects. Only perform a write the task explicitly asks for, and sequence any irreversible one as the run's **final** action, fail-closed — reads and report prep first, so a failure surfaces in this run.

### 3. Notify

Deliver via `./notify -f` (ordinary Markdown): what the task produced, which integrations/tools were used, and any pending approvals or policy blocks with what the operator should do about them. **Exactly one `./notify` call per run** — each call overwrites `$AEON_PENDING_DIR/.pending-<skill>.md` (last-writer-wins), which becomes the chain artifact `output/.chains/executor-mcp.md` that `consume:` steps and the feed read. Everything goes in the single `-f` file.

### 4. Log

This skill is `read-only`, so the workflow's read-only guard writes its `### executor-mcp` log entry from your captured output; a self-written entry would be a duplicate. Don't append to `memory/logs/` yourself - put this record in your **final output**:

```
### executor-mcp
- Task: <${var}, truncated>
- Result: EXEC_OK | EXEC_NO_TASK | EXEC_NOT_CONNECTED | EXEC_AUTH_STALE | EXEC_NO_INTEGRATION | EXEC_APPROVAL_PENDING | EXEC_POLICY_BLOCKED | EXEC_ERROR
- Calls: N (cap 15) | integrations touched: <names>
```

## Constraints

- Policies are the operator's guardrails: a "requires approval" or "blocked" outcome is a *correct* result to report, never an obstacle to engineer around.
- One task per run — `${var}` describing several unrelated tasks gets the first; note the rest as not attempted.
- Every claim in the notify traces to a tool response.