Skip to main content

Documentation Index

Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Xerg offers a hosted MCP server for paid workspaces. It lets remote MCP clients query the 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
  • manage hosted policy drafts with explicit write safety
Use the local CLI when you need to read raw OpenClaw or Hermes logs, 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: 
npx @xerg/cli mcp-setup
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: 
https://mcp.xerg.ai/mcp
Send your workspace API key as a Bearer token on every request: 
Authorization: Bearer <XERG_API_KEY>
Client config shapes differ. Use the shape your MCP client expects. Cursor and Claude Code project config: 
{
  "mcpServers": {
    "xerg": {
      "type": "http",
      "url": "https://mcp.xerg.ai/mcp",
      "headers": {
        "Authorization": "Bearer <XERG_API_KEY>"
      }
    }
  }
}
Codex config in ~/.codex/config.toml: 
[mcp_servers.xerg]
enabled = true
url = "https://mcp.xerg.ai/mcp"

[mcp_servers.xerg.http_headers]
Authorization = "Bearer <XERG_API_KEY>"
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: 
{
  "type": "http",
  "url": "https://mcp.xerg.ai/mcp",
  "headers": {
    "Authorization": "Bearer <XERG_API_KEY>"
  }
}
Metadata endpoint: 
https://mcp.xerg.ai/server.json

​
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.

​
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 the hosted Action Center, including priorityBucket, implementationSurface, scopeLabel, whereToChange, validationPlan, and actions.

​
Permissions and write safety

Hosted MCP is workspace-scoped.
  • workspace members can read hosted data and push or ingest audits
  • policy creation, update, and deletion are restricted to workspace admins
  • risky writes use preview and confirmation 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, or the next policy to create
If you prefer a first-party hosted experience before connecting a third-party MCP client, use Ask Xerg in 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.