MCP overview

The Model Context Protocol (MCP) is how AI agents talk to systems other than the one they live in. CoreX sits on both sides of it — and only one direction is live today.

CoreX as an MCP server — available now

CoreX exposes your app's own metrics to any MCP client (Cursor, Claude Code, or your own agent) at POST /mcp, authenticated with a CoreX API key.

  • Support replies, status changes, and message edits write. Every other tool is read-only.
  • A tool is scoped to the single app the API key was issued for. There is no way to name another app or another workspace from inside a tool call.
  • Requests are rate-limited per IP and per token.
  • App Store tools answer only while the workspace has the matching add-on on (Keywords, Competitors, Listing Optimizer, or the Shopify feature for review candidates). Otherwise the tool returns an error starting addon_disabled — the same rule the REST API and the panel apply.

Ask it things like "what's this app's MRR trend?" or "how did my tracked keywords move this week?" without leaving your editor.

The customers tool lists the app's customers with the same two fields as the REST API: lifecycle (paying, trial, churned, free, left_unpaid — where the customer stands) and status (the raw relationship state). Ask churn questions with lifecycle: a customer who never paid is never churned, even when their status says the relationship ended.

Connect your AI assistant

  1. Generate a key. An app key (on the app's Connect page) reads that one app. A workspace key (Workspace settings, API keys, "All apps (workspace key)") reads and replies across every app; each tool then takes an app argument (handle or id), and list_apps lists them.
  2. Copy the config for your client. The AI assistants (MCP) card on the same page shows your workspace's exact endpoint and fills in the key you just generated. The snippets below use the hosted endpoint https://corex.xco.agency/mcp and YOUR_APP_SCOPED_KEY as placeholders.

Claude Code — run in a terminal:

claude mcp add --transport http corex https://corex.xco.agency/mcp --header "Authorization: Bearer YOUR_APP_SCOPED_KEY"

Cursor — add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "corex": {
      "url": "https://corex.xco.agency/mcp",
      "headers": { "Authorization": "Bearer YOUR_APP_SCOPED_KEY" }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json (Settings → Developer → Edit config) and restart. Desktop reaches a remote server through the mcp-remote bridge, which needs Node.js; the header lives in env because Desktop splits arguments on spaces:

{
  "mcpServers": {
    "corex": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://corex.xco.agency/mcp", "--header", "Authorization:${COREX_AUTH}"],
      "env": { "COREX_AUTH": "Bearer YOUR_APP_SCOPED_KEY" }
    }
  }
}

Any other client that can send a custom Authorization header over streamable HTTP works the same way. One key reads one app; add one server entry per app (corex-returns, corex-reviews, …) to query several.

Discovery

The same server is described at /.well-known/mcp.json and /.well-known/mcp/server-card.json (SEP-2127). The card names POST /mcp and the Authorization: Bearer header. It does not list tools — a client gets those from tools/list after it connects. How to create the key is /auth.md.

Limitation: no OAuth sign-in yet

The server authenticates with a static bearer key only. Clients that connect to remote MCP servers exclusively through OAuth — claude.ai custom connectors and ChatGPT connectors — cannot add CoreX today. laravel/mcp ships the OAuth discovery routes (Mcp::oauthRoutes()), but they sit on Laravel Passport as the authorization server, and CoreX does not run Passport. Until it does, use a header-capable client above (Claude Desktop via mcp-remote included).

CoreX as an MCP client — 🔜 not yet

The reverse — letting an AI Workforce employee reach out to your external MCP servers — is modeled but not wired: connections and credentials are stored (encrypted), and there is no in-app connect/registration flow yet. See Connecting the MCP.

Why it matters

The server side lets your existing agent read CoreX without any bespoke integration. The client side, when it lands, will let CoreX's own employees act beyond CoreX the same way.