# Setting Up Arcade Scope

> Handle the one-time mandatory pause where Arcade asks the user to pick their org, project, and (if curated gateways exist) gateway, and the explicit `Arcade_Project` flow for changing that choice later. Use the first time any hub tool call for an account returns a `select_gateway` or `no_gateways` status, or when the user explicitly asks to change their org, project, or gateway. Not for running tasks — scope is otherwise automatic and invisible.

- Skill: `arcadeai-labs/setting-up-arcade-scope` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arcadeai-labs/setting-up-arcade-scope`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arcadeai-labs/setting-up-arcade-scope/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: arcadeai-labs (https://skillmd.com/u/arcadeai-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arcadeai-labs/setting-up-arcade-scope

---


# Setting up Arcade scope

**Scope** is the org, project, and (where curated gateways exist outside an
all-apps-only deployment) gateway a hub call runs against. Every account
picks this exactly once: the very first hub tool call it ever makes returns
a blocking setup prompt instead of running, and that prompt must be answered
before anything else can proceed. After that one prompt, the choice is
persisted and invisible — never surface it again unless the user explicitly
asks to change org, project, or gateway.

`Arcade_Project` lives on the `arcade` MCP server.

## Quick start

```text
Arcade_Project(action: "list")                        # current + available org/project/gateway choices
Arcade_Project(action: "set", target: "...", scope?)  # change org/project/gateway (id from list)
```

## Recognizing the setup prompt

Any hub tool call (`Arcade_SelectTools`, `Arcade_UseTool`, `Arcade_Apps`,
`Arcade_Project`) can return one of these **instead of** doing what you
asked:

- **`"status": "select_gateway"`** — scope isn't set yet. The response's
  `message` field already says exactly what to do (ask the user, then call
  `Arcade_Project` with their pick) — follow it. `projects[]` lists the
  choices grouped by project, each with a `gateway` id and display `name`.
- **`"status": "no_gateways"`** — nothing can be resolved at all (no apps
  available to the account). `message` says this is an account-setup gap
  that only the Arcade dashboard (or whoever manages the account) can fix —
  no `Arcade_Project` call will help. Relay that plainly and stop.

Both are ordinary (non-error) tool results, not a special pause type — treat
them as "the tool needs one more piece of information before it can run."

## Presenting the choices

1. Show the choices by name — project names and gateway/app-bundle names —
   never raw ids (`gateway` values are ids, `name` values are what to show).
2. Get the user's actual pick. Never guess or auto-select on their behalf,
   even if there's an obvious single choice — a one-item list is still a
   choice for the user to confirm, not one to skip past.
3. Call `Arcade_Project(action: "set", target: "<id from the choices>")`.
4. Retry the original call you were making (the same `Arcade_SelectTools` /
   `Arcade_UseTool` / etc. call, unchanged) — it now resolves normally.
   Don't mention scope again unless the user brings it up.

### Example

```text
Arcade_SelectTools(tasks: ["Send a message to #eng saying the deploy is done"])
  → {status: "select_gateway",
     message: "Before running anything, ask the user which set of apps to
               use. List the options below grouped by org/project and wait
               for their choice, then call Arcade_Project with the chosen
               target. Do not guess.",
     projects: [{project: "Engineering",
                 gateways: [{gateway: "full-suite", name: "Full Suite", apps: [...]}]}]}
Present the choice → user picks "Full Suite" →
Arcade_Project(action: "set", target: "full-suite")
  → {target: "full-suite", name: "Full Suite", message: "Connected to Full Suite: ..."}
Retry the original call:
Arcade_SelectTools(tasks: ["Send a message to #eng saying the deploy is done"])
  → normal results
```

## Changing org, project, or gateway later

Only when the user explicitly asks ("switch my project", "use the other
org", "change my gateway") — never speculatively.

1. If the target is ambiguous, call `Arcade_Project(action: "list")` first
   and match the user's words against the names it returns — **never guess
   an id.** `list` groups choices by org, then project, each with an
   "all apps in this project" target plus any curated gateways.
2. Call `Arcade_Project(action: "set", target: "...")` with the id from
   `list`. Add `scope: "everywhere"` only if the user wants the change to
   apply account-wide instead of just this app (default `this_app`).
3. Relay the confirmation (`message` in the response) so the user knows the
   new scope took effect.

The change takes effect on the next tool call — no restart or reconnect.

## Errors

- Unknown org/project/gateway name → `list` and match by name; never guess.
- `action: "set"` refused as "pinned" → this deployment fixed the scope
  itself; tell the user it can't be changed here.
- Gateway not offered by `list` → that account's deployment may not have
  curated gateways configured (e.g. an all-apps-only deployment) — org and
  project selection still apply, gateway just isn't part of this account's
  choice.

## When NOT to use

- **Never call `Arcade_Project` speculatively during normal task
  execution.** Scope is automatic and persists after the one mandatory
  prompt — don't call `list` or `set` before ordinary tasks "just in case."
- Only act on this flow when a tool call actually returns `select_gateway` /
  `no_gateways`, or when the user explicitly asks to change their org,
  project, or gateway.
- Performing tasks inside an app — that's `using-arcade-tools`.
- Managing app connections/sign-ins — that's `managing-arcade-apps`.

## Style

- Scope language: org, project, gateway, "set up", "change" / "switch".
  Show names prominently; ids only as the value passed to `target`.
- Don't dump the raw list output — summarize with names, and mark whichever
  choice is currently active.