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

# Hosted MCP (Pro)

> Configure Cursor, Claude Code, Codex, or another client for Xerg's hosted MCP server after your first pushed audit.

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](/docs/auth-and-push) and send your first audit summary from the CLI.

## Fastest setup path

Use the guided MCP setup command:

```bash theme={null}
npx @xerg/cli@latest 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:

```text theme={null}
https://mcp.xerg.ai/mcp
```

Send your workspace API key as a Bearer token on every request:

```text theme={null}
Authorization: Bearer <XERG_API_KEY>
```

Client config shapes differ. Use the shape your MCP client expects.

Cursor and Claude Code project config:

```json theme={null}
{
  "mcpServers": {
    "xerg": {
      "type": "http",
      "url": "https://mcp.xerg.ai/mcp",
      "headers": {
        "Authorization": "Bearer <XERG_API_KEY>"
      }
    }
  }
}
```

Codex config in `~/.codex/config.toml`:

```toml theme={null}
[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:

```json theme={null}
{
  "type": "http",
  "url": "https://mcp.xerg.ai/mcp",
  "headers": {
    "Authorization": "Bearer <XERG_API_KEY>"
  }
}
```

Metadata endpoint:

```text theme={null}
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.

For client-specific setup notes, see [agent clients](/docs/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.

## Recommended flow

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](/docs/auth-and-push).

### Browser client cannot complete setup

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