---
updatedAt: 2026-10-27T13:35:02.000Z
agentTools:
  projectIndex: https://docs.getmontecarlo.com/llms.txt
---

# Reference & operations

Toolsets, read-only mode, network access control, security, troubleshooting, and Node/curl setup for the Monte Carlo MCP Server.

## Toolsets

Not all tools are available in every deployment. The server organizes tools into **toolsets** that control what's exposed to the client:

| Toolset               | What it adds                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `default`             | Always active. Alerts, monitors, assets, lineage, data operations, and utility tools.                                          |
| `extended`            | Default tools plus use-case and dashboard-widget tools (`get_use_cases`, `get_use_case_tables`, `get_use_case_table_summary`). |
| `agent_observability` | Default tools plus AI agent inspection tools (`get_agent_metadata`, `get_agent_conversation`, `get_agent_trace`).              |

To enable `extended` or `agent_observability`, pass the `x-mcd-toolset` header when connecting. With the key-based (`mcp-remote`) setup, add an extra header argument:

```json
"--header", "x-mcd-toolset: extended"
```

## Per-request tool restrictions

Two optional headers narrow the available tools on a per-request basis. They only ever remove tools — they can't widen what the toolset exposes — and unlike toolsets they're enforced when a tool is called, not just when tools are listed.

| Header           | Value                                              | Effect                                                                                                                                                                                                                      |
| ---------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-mcp-readonly` | `true` (case-insensitive; `1` and `yes` also work) | Exposes only read-only tools. Write tools such as `update_alert` and the `create_or_update_*` monitors are hidden, and calling one returns a "not available in read-only mode" error.                                       |
| `x-mcp-tools`    | Comma-separated tool names                         | Exposes only the named tools, intersected with the active toolset. Calling any other tool returns a "not in the x-mcp-tools allow-list" error. Unknown names simply match nothing, and a blank header is treated as absent. |

With the key-based (`mcp-remote`) setup, pass them as extra header arguments:

```json
"--header", "x-mcp-readonly: true"
```

```json
"--header", "x-mcp-tools: get_alerts,search,get_table"
```

Whether you can send these headers depends on your client — clients with a fixed header configuration, like the Claude connector, can't set them. Use read-only mode when an agent should observe your Monte Carlo account without being able to change anything, and `x-mcp-tools` when you want to pin an agent to a small set of tools.

## Prompts

The server publishes prompts (curated workflow templates) over the MCP prompts capability. They're surfaced only by clients that support prompts — typically as slash commands like `/mcp__monte-carlo__<prompt_name>`. No configuration is required: supported clients discover them automatically on connect. See [Guided prompts](https://docs.getmontecarlo.com/docs/mcp-server#guided-prompts) on the MCP Server page for the workflow-level view.

## Network access control

You can restrict access to the MCP Server endpoint by IP address using Network Access Control Lists. See [Network Access Control](https://docs.getmontecarlo.com/docs/network-access-control) for setup details.

## Security & governance

For how Monte Carlo secures the MCP Server — tool governance, first-party ownership, scoped credentials, and subprocessor handling — see [AI Security & Governance](https://docs.getmontecarlo.com/docs/ai-security).

## Troubleshooting

**Connection won't start / shows an error**

* Verify the endpoint URL. The key-based (`mcp-remote`) setup expects a trailing slash: `https://mcp.getmontecarlo.com/mcp/`.
* Ensure `npx` is on your PATH; the `-y` flag auto-installs `mcp-remote` if missing.

**401 / Unauthorized**

* Double-check the **Key id** and **Key secret**.
* Confirm headers are passed correctly (`Authorization: Bearer <id>:<secret>` or `x-mcd-id` / `x-mcd-token`).
* Make sure the key type is **MCP server** — standard API keys won't work.

**HTTP 403: Invalid OAuth error response**

* Often caused by an outdated client. Upgrade to the latest version.
* If the console shows empty headers (e.g. `Authorization:""`), the token isn't being passed — some older client versions omit custom headers.

**Connecting from a managed proxy (e.g. Databricks AI Gateway or Genie)**

* Managed MCP proxies are supported, and you don't need to allowlist your workspace URL or redirect URI with Monte Carlo.
* If the proxy asks for a client ID and secret, use its Dynamic Client Registration option instead (see [OAuth setup](https://docs.getmontecarlo.com/docs/mcp-server#option-2-oauth-recommended-for-all-other-agents)).

**Network / proxy issues**

* Confirm your corporate proxy allows requests to `mcp.getmontecarlo.com` (and `registry.npmjs.org` on first `npx` run).
* Try a different network to rule out blocking.

## Install Node.js + npm (for key-based setups)

The `mcp-remote` bridge used by API-key clients requires Node.js. Quick check:

```bash
node -v && npm -v && npx -v
npx -y mcp-remote --version
```

Install tips: macOS `brew install node` or `nvm install --lts`; Linux via `nvm`; Windows `winget install OpenJS.NodeJS.LTS`.

### Verify auth headers with curl

These checks confirm your endpoint accepts the auth headers — you're good if you do **not** get `401` / `403` (a `202` is fine):

```bash
export MCD_URL="https://mcp.getmontecarlo.com/mcp/"
export MCD_ID="<KEY_ID>"
export MCD_SECRET="<KEY_SECRET>"

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$MCD_URL" \
  -H "Authorization: Bearer $MCD_ID:$MCD_SECRET"
```