Installing the MCP Server

Connect your editor so the agent uses the same Apex as Settings → AI Agents.

One-click from Apex

Open Settings → AI Agents.
Leave Device flow selected.
Click Install in Cursor or Install in VS Code.

No key goes in the file. The first Apex tool call prints an approval link. Open it, approve, and the connection status on AI Agents turns green.

Claude Desktop uses the same page. Copy the config if your editor has no install button.

The same buttons are on apex.inc/start, before you have an account.

Claude Code

Run this once in a terminal. It installs Apex for every project on this machine:

claude mcp add --scope user --env APEX_URL=https://app.apex.inc apex -- npx -y -p @apex-inc/mcp-server@latest mcp-server

Then set up your workspace

Tell the agent:

Set up Apex in this repo.

In Cursor you can also type /setup-apex. The agent signs you in, works out which workspace this repo is, wires your events, and stops with a link when a step needs you in the browser. See Set up Apex from the editor.

Manual setup (device flow)

Create or update .cursor/mcp.json in the workspace root:

{
  "mcpServers": {
    "apex": {
      "command": "npx",
      "args": ["-y", "-p", "@apex-inc/mcp-server@latest", "mcp-server"],
      "env": {
        "APEX_URL": "https://app.apex.inc"
      }
    }
  }
}

One install covers every workspace you can reach. Each repo names its workspace in a committed .apex/workspace.json, and the agent switches to it:

{
  "workspace_key": "your-workspace-key",
  "workspace_name": "Your workspace",
  "org_name": "Your organization"
}

The workspace key is not a secret. It already ships in your site's snippet. If the file is missing, the agent asks which workspace the repo belongs to and writes it.

Those npx arguments are required. A bare npx @apex-inc/mcp-server can hang on first run. @latest makes each editor restart pick up the newest Apex; without it, npx keeps the first copy it downloaded.

Restart the editor after you save the file.

API key (advanced)

Use a key when you want a static credential (CI, a locked-down laptop, or one organization's key).

Open Settings → AI Agents (or Settings → Profile → Your MCP Keys).
Generate a key. Copy it once.
Add it to the config:

{
  "mcpServers": {
    "apex": {
      "command": "npx",
      "args": ["-y", "-p", "@apex-inc/mcp-server@latest", "mcp-server"],
      "env": {
        "APEX_URL": "https://app.apex.inc",
        "APEX_API_KEY": "apex_uk_your_key_here"
      }
    }
  }
}

Key	Prefix	Use
User key	`apex_uk_`	You, across organizations. Needed for `list_orgs` and `switch_org`.
Organization key	`apex_sk_`	One organization. Made under Organization → API keys. Cannot list orgs.

Cost of goods stays off both kinds of key until you turn cost:read on in AI Agents. A missing cost permission is not a revoked key.

Environment variables

Parameter	Type	Description
`APEX_URL`	`string`	Defaults to https://app.apex.inc from version 0.41.0. Set http://localhost:3000 when you run Apex locally.
`APEX_WORKSPACE_KEY`	`string`	Optional pin for the workspace this session starts on. Most people leave it out and let each repo's .apex/workspace.json decide. Handy with an organization key (apex_sk_). APEX_PROJECT_KEY is the old name and still works.
`APEX_API_KEY`	`string`	User or organization key. Omit this when you use device flow.

Confirm it works

Ask the agent:

List my workspaces, then list experiments in the active one.

It should call list_workspaces and list_experiments. Empty is fine. A 401 means the key or device approval is wrong. A sentence about costs means that list needs cost access, not a new key.

On Settings → AI Agents, Connection status should show the editor reached Apex.

Tip

Local Apex uses APEX_URL http://localhost:3000. The MCP server calls the same API the dashboard uses.

Troubleshooting

What you see	What it usually is	What to do
Unknown tool	Editor did not load the server	Restart the editor. Check `mcp.json` uses `-y -p @apex-inc/mcp-server@latest mcp-server`.
401	Key or device token is wrong	Approve the link again, or generate a new user key on AI Agents and restart.
This key cannot see costs	Cost access is off (by design)	Turn it on for that key, or stop asking for product costs.
Connection refused	Wrong `APEX_URL`	`curl $APEX_URL/api/health` should return 200.
`list_orgs` is empty	Organization key (`apex_sk_`)	Use device flow or a user key (`apex_uk_`).
Update Cursor on Set up Apex	Editor is behind the server	Open AI Agents and click Update Cursor.