Skip to main content
Xerg offers a hosted MCP server for paid workspaces. It lets remote MCP clients query hosted data already pushed into your workspace instead of reading local audit data directly from disk.
Hosted MCP requires a Pro or Enterprise workspace plus a workspace API key.

​
When to use hosted MCP

Use hosted MCP when you want a remote client such as Cursor, Claude Code, or Codex to:
  • inspect the latest hosted audit
  • compare recent spend and waste trends
  • read ranked recommendations, where-to-change guidance, and source summaries
  • push new hosted audit payloads or ingestion jobs
  • preview and commit selected hosted policy workflows with explicit write safety
Use the local CLI when you need to read OpenClaw files or Hermes state.db, analyze Cursor usage CSV exports, run fresh audits from local files or OpenClaw SSH and Railway sources, or generate export files directly on your machine.

​
Requirements

You need:
  • an active Pro or Enterprise workspace
  • a workspace API key from the Xerg dashboard
  • at least one pushed audit if you want real hosted audit data in the workspace
If the workspace is empty, start with authentication and push and send your first audit summary from the CLI.

​
Fastest setup path

Use the guided MCP setup command:
mcp-setup:
  • checks existing auth first
  • offers browser login inline when auth is missing
  • asks whether you want Cursor, Claude Code, Codex, or another client
  • prints the hosted config snippet, or writes .cursor/mcp.json when a project-scoped Cursor directory already exists
If you authenticated only with a stored browser login token, mcp-setup warns that some hosted MCP clients may still require a workspace API key. In that case, create one in the dashboard and set XERG_API_KEY.

​
Endpoint and auth

Production endpoint:
Send your workspace API key as a Bearer token on every request:
Client config shapes differ. Use the shape your MCP client expects. Cursor and Claude Code project config:
Codex config in ~/.codex/config.toml:
Restart Codex after editing ~/.codex/config.toml; MCP tools are loaded when a session starts. Generic single-server object for clients that ask for one remote server entry:
Metadata endpoint:

​
Supported clients

Hosted MCP works best in desktop or server MCP clients that can attach custom Bearer headers. Common examples:
  • Cursor remote MCP
  • Claude Code
  • Codex
  • Claude Desktop via mcp-remote
  • other desktop or server MCP clients that support remote HTTP MCP
Some browser-native MCP clients may require OAuth-based setup flows that are not part of the current hosted MCP path. For client-specific setup notes, see agent clients.

​
Available tools

Read tools:
  • xerg_latest_audit
  • xerg_history
  • xerg_trends
  • xerg_sources
  • xerg_recommendations
  • xerg_list_policies
Write tools:
  • xerg_push_audit
  • xerg_ingest_raw_openclaw
  • xerg_upsert_policy
  • xerg_delete_policy
  • xerg_create_policy_from_recommendation
xerg_recommendations returns the richer v2 recommendation shape used by hosted Optimizations, including priorityBucket, implementationSurface, scopeLabel, whereToChange, validationPlan, and actions.

​
Permissions and write safety

Hosted MCP is workspace-scoped.
  • workspace API keys can read hosted data and push or ingest audits
  • signed-in workspace admins can create, update, and delete policies
  • workspace API keys can create recommendation-backed draft policies through the recommendation flow
  • risky writes use preview and commit semantics instead of silently committing changes
This keeps the MCP server useful for automation while still making destructive or policy-shaping actions explicit.
  1. run a local audit with xerg init or xerg audit
  2. push it with xerg connect or xerg audit --push
  3. confirm the hosted workspace has data
  4. run xerg mcp-setup or connect your MCP client to https://mcp.xerg.ai/mcp
  5. ask about waste, changes, Optimizations, or the next policy draft to review
If you prefer a first-party hosted experience before connecting a third-party MCP client, use the dashboard after your first push.

​
Troubleshooting

​
401 or Missing or malformed Authorization

Your client is not sending a valid workspace API key as a Bearer token.

​
Empty audit results

The workspace likely has no hosted audits yet. Push one first with authentication and push.

​
Browser client cannot complete setup

Use a desktop or server MCP client that supports remote HTTP MCP with custom Bearer headers.