Installing the MCP Server

Set up the Apex MCP server so your AI coding agent can interact with experiments, beliefs, and intelligence data directly from your editor.

One-Click Install

The fastest way to get started:

Open Settings → Profile in the Apex dashboard
Click Generate Key in the "Your MCP Keys" section
Click the Install in Cursor or Install in VS Code button

This generates a personal MCP key (apex_uk_...) that identifies you across all your organizations and configures your editor automatically.

Manual Setup

Install the Package

npm install -g @apex-inc/mcp-server

Configure Your Editor

Add the server to your editor's MCP configuration. For Cursor, create or update .cursor/mcp.json in your project root:

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

Info

You can also run the server via npx without a global install. The -y flag auto-confirms the package download.

Environment Variables

Parameter	Type	Description
`APEX_URL`required	`string`	Base URL of your Apex instance (e.g. https://your-apex-instance.com or http://localhost:3000 for local dev).
`APEX_API_KEY`required	`string`	Your personal MCP key (apex_uk_...). Generate one in Settings → Profile → Your MCP Keys.
`APEX_PROJECT_KEY`	`string`	Optional. Pre-select a project. If omitted, the server auto-selects based on your active org.

API Key Types

Apex uses two types of API keys:

Key Type	Prefix	Use For
User key	`apex_uk_`	MCP server, personal use. Identifies you across all orgs.
Org key	`apex_sk_`	CI/CD, webhooks, server-to-server. Scoped to one org.

The MCP server works best with user keys — they enable multi-org switching and personal MCP status tracking. Org keys still work but don't support list_orgs or switch_org.

Multi-Organization Support

If you belong to multiple organizations, the MCP server discovers them on startup:

[apex] Connected as chris@apex.inc — active org: Apex Inc (3 projects).
You have access to 2 orgs — use switch_org to change.

Use list_orgs to see all your organizations and switch_org to change the active context.

Find Your Key

Open the Apex dashboard

Navigate to your Apex instance and sign in.

Go to Settings → Profile

Click Settings in the sidebar, then select Profile.

Generate or copy your key

In the Your MCP Keys section, click Generate Key. Name it something like "MacBook Pro" or "Work Desktop". Copy the key immediately — it's only shown once.

Verify the Connection

After configuring, ask your agent to run a simple command:

List my active experiments

The agent should call list_experiments and return results from your Apex instance. If you see an authentication error, double-check your APEX_URL and APEX_API_KEY.

Tip

For local development, set APEX_URL to http://localhost:3000. The MCP server connects to the same API your dashboard uses.

Troubleshooting

Symptom	Cause	Fix
"Unknown tool: plan_experiment"	MCP server not loaded	Restart your editor and check `mcp.json` syntax
"Unauthorized" or 401 errors	Invalid API key	Regenerate a user key in Settings → Profile
"Connection refused"	Wrong APEX_URL or server not running	Verify the URL is reachable with `curl $APEX_URL/api/mcp-ping`
Tools work but resources don't	Older server version	Run `npm update -g @apex-inc/mcp-server`
`list_orgs` returns empty	Using an org key (`apex_sk_`)	Switch to a user key (`apex_uk_`) — generate in Settings → Profile

Next Steps

Browse all available tools with parameters and descriptions
Learn common workflows for experiment-driven development