> For the complete documentation index, see [llms.txt](https://docs.espresso.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.espresso.ai/mcp-server.md).

# Espresso MCP server

The Espresso MCP server lets AI agents such as Claude read and change your Espresso settings. It exposes the same settings as the **Settings** page in the dashboard, with the same rules: a change the dashboard would refuse is refused here too, and every change appears in the settings history.

Endpoint: `https://mcp.espressocomputing.com/mcp` (Streamable HTTP)

## Authentication

The server authenticates with an organization API key. In the Espresso dashboard, select an existing account, open **Tools → API Keys**, choose **Generate organization key**, and copy the complete `ok_` secret. It cannot be displayed again.

Clients send the key on every request as `Authorization: Bearer <key>`.

An organization key acts as an organization admin on every account in your organization, so it can change any setting an organization admin can change in the dashboard. Treat it like a password: keep it out of source control and chat transcripts. If a key leaks, revoke it under **Tools → API Keys**. A revoked key stops working within a minute.

## Claude Code

```bash
claude mcp add --transport http espresso https://mcp.espressocomputing.com/mcp --header "Authorization: Bearer $ESPRESSO_API_KEY"
```

To share the server with a team, add it to the project's `.mcp.json` instead. Each person sets `ESPRESSO_API_KEY` in their own environment, so the key is never committed:

```json
{
  "mcpServers": {
    "espresso": {
      "type": "http",
      "url": "https://mcp.espressocomputing.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ESPRESSO_API_KEY}"
      }
    }
  }
}
```

## Claude.ai and Claude Desktop

Add Espresso as a custom connector:

1. Go to **Customize → Connectors** and click **Add custom connector**. On Team and Enterprise plans, an Owner adds it under **Organization settings → Connectors** instead.
2. Enter `https://mcp.espressocomputing.com/mcp` as the server URL.
3. For **Authentication**, choose **No sign-in**.
4. Under **Request headers**, add an `authorization` header with the value `Bearer` followed by your key, including the space.
5. Click **Add**.

**Request headers** is in beta, and Anthropic is rolling it out to organizations gradually. If you don't see it in the dialog, your organization doesn't have it yet; use Claude Code in the meantime. On Team and Enterprise plans, everyone who uses the connector shares the key's access.

## ChatGPT

ChatGPT isn't supported yet.

## Examples

### Review settings

> Which of my Snowflake warehouses does the Warehouse Agent manage, and what changed in the last week?

Claude calls `list_accounts` to find your account, `get_snowflake_warehouse_agent_settings` to list each warehouse's agent status and cluster bounds, and `get_settings_history` with `since: "-7d"` for recent changes, then summarizes them.

### Change a warehouse

> Raise max clusters on ANALYTICS\_WH to 4 in the acme account. Note: Q4 load.

Claude calls `update_snowflake_warehouses`, which previews the change by default: `max_clusters` from 2 to 4. If the preview passes, Claude calls the tool again to apply it, and the change appears in the settings history labeled **via MCP**.

## Tools

Every tool except `list_accounts` takes a `customer`: the account slug that `list_accounts` returns. You only see the tools for the products your organization uses.

| Tool                                     | Product    | What it does                                                                                          |
| ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `list_accounts`                          | Both       | Lists the accounts the key can manage, with each account's product.                                   |
| `get_settings_history`                   | Both       | Recent settings changes: who made them, old and new values, and notes.                                |
| `get_snowflake_warehouse_agent_settings` | Snowflake  | Warehouse Agent status, new-warehouse opt-in, and each warehouse's settings.                          |
| `get_snowflake_scheduler_settings`       | Snowflake  | Scheduler Agent status, per-warehouse scheduling, routing pools, and the never-route-to list.         |
| `set_snowflake_warehouse_agent`          | Snowflake  | Turns the Warehouse Agent on or off, or sets new-warehouse opt-in.                                    |
| `update_snowflake_warehouses`            | Snowflake  | Changes warehouses' enabled flag, cluster bounds, and scaling policy.                                 |
| `set_snowflake_scheduler`                | Snowflake  | Turns the Scheduler Agent on or off.                                                                  |
| `update_snowflake_scheduler_warehouses`  | Snowflake  | Changes per-warehouse scheduling, routing pool, and maximum extra warehouses.                         |
| `update_snowflake_routing`               | Snowflake  | Replaces the routing pools and the never-route-to list.                                               |
| `get_databricks_settings`                | Databricks | Warehouse Agent status, opt-in, instance cost per DBU, and each SQL warehouse's settings.             |
| `get_databricks_scheduler_settings`      | Databricks | Scheduler Agent status, per-warehouse scheduling, routing pools, and the never-route-to list.         |
| `get_databricks_spark_jobs_settings`     | Databricks | Spark job agent status, default SLA, and each job's settings and status.                              |
| `set_databricks_agent`                   | Databricks | Turns the Warehouse Agent on or off, sets opt-in, or sets instance cost per DBU.                      |
| `update_databricks_warehouses`           | Databricks | Changes SQL warehouses' enabled flag, cluster bounds, size, and type.                                 |
| `update_databricks_scheduler`            | Databricks | Changes Scheduler Agent status, per-warehouse scheduling, routing pools, and the never-route-to list. |
| `update_databricks_spark_jobs_settings`  | Databricks | Changes the Spark job agent's account settings and per-job settings and SLAs.                         |

Clients read the list of tools when they connect. If tools appear to be missing, reconnect the server or start a new session.

## Making changes

Every change takes two calls, both made by the agent. The preview is an automatic check the agent runs before applying; it doesn't wait for your approval.

1. **Preview.** Every change tool previews by default. It checks the change against the same rules as the dashboard and returns the exact fields that would change, any side effects (for example, turning the Warehouse Agent off also puts the Scheduler Agent in dry run), and the current `versions` of the settings involved. Nothing is changed.
2. **Apply.** The agent calls the tool again with `dry_run: false` and the `versions` from the preview. If someone changed those settings in the meantime, in the dashboard or another session, the change is refused instead of overwriting theirs, and the agent reads the settings again and previews again.

To approve each change yourself, have your client ask before running the change tools: in Claude Code, don't choose "don't ask again" for them; in Claude.ai, set them to **Needs approval** under **Customize → Connectors**.

Every change requires `notes`, which are saved with the change. Changes made through the MCP server appear in the dashboard's settings history labeled **via MCP**, with the API key's ID as the user.

Warehouse tools only change warehouses Espresso has already discovered in your account; the read tools list them. New-warehouse opt-in decides whether newly discovered warehouses are managed automatically.

## Rate Limits

* Each API key can make 100 read calls and 25 change calls per minute. Previews count as change calls. Over the limit, a tool returns an error that says how long to wait.
* Repeated requests with invalid keys from one network address are rate limited.