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.

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", "mcp-server"],
      "env": {
        "APEX_URL": "https://app.apex.inc",
        "APEX_WORKSPACE_KEY": "your-workspace-key"
      }
    }
  }
}

Those npx arguments are required. A bare npx @apex-inc/mcp-server can hang on first run.

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 a shop key scoped to one workspace).

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", "mcp-server"],
      "env": {
        "APEX_URL": "https://app.apex.inc",
        "APEX_API_KEY": "apex_uk_your_key_here",
        "APEX_WORKSPACE_KEY": "your-workspace-key"
      }
    }
  }
}

Key	Prefix	Use
User key	`apex_uk_`	You, across organizations. Needed for `list_orgs` and `switch_org`.
Shop key	`apex_sk_`	One organization. Fine for one shop. 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`required	`string`	https://app.apex.inc in production. http://localhost:3000 when you run Apex locally.
`APEX_WORKSPACE_KEY`	`string`	Shop this session starts on. You can still call switch_workspace. APEX_PROJECT_KEY is the old name and still works.
`APEX_API_KEY`	`string`	User or shop 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 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	Shop 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.