Connecting an MCP client

Connect your AI agent to your Epox workspace by signing in: add the server to your client, then approve the connection in your browser. There is no key to create, copy, or store, and with most clients it takes one command or one setting.

You need to be an owner of the workspace, because only owners can approve a connection. Any client that supports remote MCP servers works: Claude, Claude Code, ChatGPT, Cursor, Codex, VS Code, Antigravity, and others.

Epox is listed in the Official MCP Registry as `ai.epox/mcp`. Clients that search the Registry can select that name; all clients can connect directly to https://app.epox.ai/api/mcp below. The registry record points to the same public Streamable HTTP endpoint and OAuth discovery flow.

Connect with OAuth

ClaudeClaude CodeChatGPTCursorCodexVS CodeAntigravity

1. Open Claude → Settings → Connectors → Add custom connector
2. Name it Epox and paste the URL below
3. Click Connect and approve the sign-in

shellCopy

https://app.epox.ai/api/mcp

Open Claude connectors

OAuth needs no API key: you add the server, then a workspace owner approves the connection in the browser. The tabs above are the same panel you see in Epox under Settings → MCP: a tab per client, a copy button for each command, and one-click install links for Cursor and VS Code.

Custom connectors in ChatGPT need Developer mode, which is on paid plans. Antigravity reads a remote server from serverUrl, not url.

When the client opens the Epox sign-in:

1. Sign in as a workspace owner.
2. Check the website named on the screen. It is where the access code is sent, and apps choose their own display names, so this is the detail to verify.
3. Click Allow generation access (or Allow read-only access if the app asked only to read). Click Deny to refuse.

One approval covers generating: Epox asks clients for read and generation access together. If a connection was approved read-only, its first generation call asks the client to sign in again for generation access. A client that doesn't support that stays read-only; connect it with an API key that has Allow generation checked to generate.

An OAuth connection lasts up to 90 days, then an owner must approve it again. It ends immediately when it is revoked or when the approving owner leaves the workspace or is no longer an owner.

Every owner is emailed when a connection is approved. Review and revoke connections under Settings → MCP, in the Approved connections section.

Connect with an API key

Use a key only where a browser sign-in isn't possible: scripts, CI, and clients without OAuth support. Only owners can create one.

Create an API key

1. In Epox, open Settings and select API Keys in the Developer group.
2. Click Create key. The Create workspace API key dialog opens.
3. Type a name for the agent or integration, for example "Codex development". Teammates will use this name to recognize the key, because keys belong to the workspace and not to you personally.
4. Optionally set Expiry. Leave it empty for a key that does not expire.
5. Leave Allow generation unchecked for a read-only key. Check it only if this agent may add source photos, start queued generations and consume workspace credits. You can create a second key later rather than widening this one.
6. Click Create key. The Copy your API key now dialog shows the secret, which starts with epox_wsk_live_.
7. Click Copy key and store the secret in your agent's secret manager. It is shown once and cannot be displayed again. If you lose it, revoke it and create a new one.

Add the server to your client

Most clients can sign in with OAuth instead, with no key to create: see Connect with OAuth. With a key, every client needs the same two values: the server URL and an Authorization: Bearer header carrying your key.

Server URL:     https://app.epox.ai/api/mcp
Authorization:  Bearer epox_wsk_live_…

Pick your client and add the server as shown below, pasting your real key in place of epox_wsk_live_….

Claude Code (CLI)

claude mcp add --transport http epox https://app.epox.ai/api/mcp \
  --header "Authorization: Bearer epox_wsk_live_…"

Claude Desktop — add to claude_desktop_config.json, or to .mcp.json for a project:

{
  "mcpServers": {
    "epox": {
      "url": "https://app.epox.ai/api/mcp",
      "headers": { "Authorization": "Bearer epox_wsk_live_…" }
    }
  }
}

Codex — keep the key in an environment variable and point Codex at it:

export EPOX_API_KEY=epox_wsk_live_…
codex mcp add epox --url https://app.epox.ai/api/mcp --bearer-token-env-var EPOX_API_KEY

Antigravity — in Settings → MCP Servers, add to mcp_config.json (Antigravity reads serverUrl, not url):

{
  "mcpServers": {
    "epox": {
      "serverUrl": "https://app.epox.ai/api/mcp",
      "headers": { "Authorization": "Bearer epox_wsk_live_…" }
    }
  }
}

VS Code (GitHub Copilot) — add to .vscode/mcp.json:

{
  "servers": {
    "epox": {
      "type": "http",
      "url": "https://app.epox.ai/api/mcp",
      "headers": { "Authorization": "Bearer epox_wsk_live_…" }
    }
  }
}

Any other MCP client works the same way: an HTTP server at the URL above with the bearer header set.

Restart or reload the client if it only reads its config at startup.

Check your result

Ask your agent: "Call epox_workspace_summary and show me the result." A working connection returns your workspace name and totals:

{
  "workspace": { "id": "clnt_9f2a1c", "name": "Northwind Home Goods" },
  "productCount": 128,
  "hasGeneratedAssets": true,
  "automationCount": 3
}

To test an API key without an agent, run the same call from a terminal:

curl -s https://app.epox.ai/api/mcp \
  -H "Authorization: Bearer epox_wsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"epox_workspace_summary","arguments":{}}}'

The reply wraps the same data as text inside result.content[0].text; see Requests, responses & errors.

If something is wrong:

• HTTP 401 means the client isn't signed in, or the key is missing, mistyped, revoked, or expired. Sign in again, or create a new key and update your config.
• "This API key does not have access to this tool" means the tool needs Allow generation and your key was created without it. Create a new key with generation allowed.
• "This connection does not have generation access" means an OAuth connection was approved read-only. Sign in again and click Allow generation access.
• "The workspace owner must accept the upload terms in Epox" (UPLOAD_ATTESTATION_REQUIRED) means the owner behind this connection or key has not accepted the upload terms, so it cannot add images yet. Have them open the link in the message (Settings → API Keys) and accept. See Adding images.
• HTTP 429 means too many requests. See Rate limits.

Next steps

• Developer overview for what the server offers and the scopes it needs.
• Requests, responses & errors for the request format, rate limits, and error codes.
• Workspace & try-on tools, Catalogue tools, and Generation & automations tools for every tool.