Auth and scopes

Workspace API Key auth, scopes, blast radius, Pro Max gate, and MCP entitlement for Andy MCP.

Outcome

Authenticate an MCP client with a Workspace API Key, understand blast radius, and stay within plan and entitlement gates.

Canonical install steps for connecting an MCP client to the Andy MCP server (docs.andypartner.com + landing). The in-app API Integration settings page currently ships its own snippets; that fork is tracked in Andesphere/andyChat#929 and will be retargeted at this file. Until then, prefer this file for external docs and landing copy.

Endpoint: https://app.andypartner.com/api/mcp
Auth: Workspace API Key as Authorization: Bearer YOUR_ANDY_API_KEY
Tools: 91 tools total — 90 andy_* tenant operations plus andy_ask.
Verify: list tools (andy_*) and call andy_identity_status → data.status: ready + meta.requestId (prefix mcp-).
andy_identity_status is globally available. andy_ask needs the public_chat:write scope and an agent with mcpAllowed.

Key blast radius

A Workspace API Key unlocks all 91 tools for that workspace, including destructive and credential-minting operations such as:

andy_api_key_create / andy_api_key_rotate / andy_api_key_revoke
andy_agent_create / andy_agent_delete
andy_knowledge_source_delete
andy_workspace_create
andy_marketing_post_create

Treat the key as workspace admin access. Prefer a scoped key when the client only needs read probes. Never commit the key. Never put a live key in a URL, shell history, chat log, or public gist.

Where to get a key

App → workspace → API Integration. Create a Workspace API Key, copy it once, store it in your secret manager or OS keyring.

Plan gate: API keys require Pro Max. Free / lower plans see "API Access requires Pro Max".
MCP entitlement: the Workspace must include MCP access. Without it, non-global tools fail with "The selected Workspace does not currently include MCP access".

Replace YOUR_ANDY_API_KEY with your key (or load it from the environment as shown). Do not leave angle brackets around the value — they become shell redirects when unquoted.

Minimum client versions

Client	Floor	Notes
Claude Code	≥ 2.1.x	Verified on `claude 2.1.226`
Codex CLI	≥ 0.147	Verified on `codex-cli 0.147.0`. Older builds need `[features].rmcp_client = true` (or `experimental_use_rmcp_client = true`) for streamable HTTP; that flag is gone in 0.147.
Cursor	not yet live-verified	Config reference only — tracked in #929

Scopes and least privilege

Workspace API Keys can call only operations allowed by their scopes and owning Workspace. Prefer a scoped key when the client only needs read probes.

Global probe: andy_identity_status (no special scope beyond a valid key).
andy_ask requires public_chat:write and an agent with mcpAllowed.
Mutating tenant tools require the matching write scopes from the operation catalog (see Tool catalog and CLI Reference).

OAuth

User-session OAuth for MCP is coming (tracked for a later ticket). Until then, use Workspace API Keys only.

Next step

Install a client (Claude Code, Codex, Cursor, or Generic), then call andy_identity_status.