Auth and scopes

Outcome

Authenticate with browser OAuth or a Workspace API Key, select the intended Workspace, and stay within server-side operation and entitlement gates.

Endpoint and auth

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: Browser OAuth (recommended) or a Workspace API Key for headless/CI use. Tools: 20 job-oriented tools — get_context, select_workspace, get_agent, configure_agent, manage_agent, list_conversations, list_conversation_messages, manage_handoff, send_message, ask_agent, list_posts, manage_post, list_connections, list_routines, manage_routine, list_intents, manage_brand, list_knowledge, add_knowledge, replace_knowledge. Verify: list tools (exactly the 20 above) and call get_context → data.selection.status plus meta.requestId (prefix mcp-).

get_context is globally available and is the only call needed to orient: it returns identity, Workspaces, the selected Workspace with its Agents, Entitlements and labeled Platform Connections (the destinations a Post can publish to), and ready-to-run select_workspace calls when none is selected. ask_agent needs the public_chat:write scope and an agent with mcpAllowed. Never ask a human for a Workspace or Agent id — omit it and Andy resolves it.

Browser OAuth

Paste https://app.andypartner.com/api/mcp into a browser-OAuth-capable MCP client, leave client ID and client secret fields empty, and sign in to Andy. One Workspace auto-selects. With multiple Workspaces, call get_context and replay one of the select_workspace calls it hands back; reuse the same signed session for later calls.

Workspace API Key blast radius

A Workspace API Key unlocks every API-key-capable tool on this surface for that workspace, including destructive operations such as:

• manage_agent (action: "create" / "delete")
• manage_post (action: "create" / "edit" / "approve" / "reject" / "cancel")
• manage_routine (action: "create" / "clone" / "update" / "pause" / "resume" / "run_now" — run_now enqueues a Recipe run that performs external research and spends workspace credits)
• manage_brand (action: "set_voice" / "create_intent" / "update_intent")
• replace_knowledge and configure_agent
• send_message and manage_handoff
• ask_agent with actionMode: "allow_actions"

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

---

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: get_context (no special scope beyond a valid key).
• ask_agent requires public_chat:write and an agent with mcpAllowed.
• Mutating tools require the matching write scopes of the granular operations they compose (see Tool catalog and CLI Reference).

OAuth

Paste https://app.andypartner.com/api/mcp into a browser-OAuth-capable client and complete Andy sign-in. Leave client ID and client secret fields empty: Andy authenticates tokens verified by its own Clerk instance, while authorization remains server-side per operation and entitlement.

One Workspace auto-selects. With multiple Workspaces, initialize and get_context work before selection; get_context returns the candidates as ready-to-run select_workspace calls, so no human ever supplies a Workspace ID. The x-andy-workspace-id header remains available for clients that can send it.

Next step

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