# Wheelhouse MCP Server

> Web version: https://docs.usewheelhouse.com/rm/mcp

The Wheelhouse MCP server exposes the Revenue Management API as
[Model Context Protocol](https://modelcontextprotocol.io/) tools so AI assistants
can read and update your Wheelhouse account on your behalf.

> **Beta:**
>
> MCP access is a free beta for now. The Revenue Management API will become a paid
> product once it is released.

## Enable access

Before connecting a client:

1. Open your Wheelhouse account settings and go to
   [**API & MCP → MCP**](https://app.usewheelhouse.com/u/account/mcp).
2. Under **MCP Access**, click **Enable MCP Access**.

Wheelhouse creates dedicated API keys for MCP on your behalf. Usage is tracked
and rate-limited like your other RM API keys, and you can review activity in the
API logs. Disabling MCP access revokes those keys immediately.

The MCP page has a **Read-only** switch. It uses the same limits as a
[read-only RM API key](https://docs.usewheelhouse.com/rm/authentication.md#read-only-api-keys): assistants can
look up the account and run previews, and changes are rejected.

## Server URL

```
https://mcp.usewheelhouse.com/mcp
```

## Authentication

MCP clients authenticate with **OAuth** (WorkOS AuthKit). Sign in with your
Wheelhouse account through your client's OAuth flow — the same credentials you
use in the Wheelhouse app.

Do **not** paste an RM API key into the MCP client. The server validates your
OAuth token, resolves your user-specific RM API key, and attaches it as
`X-Integration-Api-Key` on every upstream request. Your OAuth token is never
forwarded to the RM API.

See [Authentication](https://docs.usewheelhouse.com/rm/authentication.md) for how direct HTTP integrations
differ.

To install the MCP server together with Wheelhouse portfolio skills, see
[Agent plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md). The steps below connect the MCP server
on its own.

## Client setup

Enable MCP access first, then follow the steps for your client.

### Claude Desktop

**Custom connector (recommended)**

1. Open **Settings → Connectors → Add custom connector**.
2. Paste the Wheelhouse MCP URL: `https://mcp.usewheelhouse.com/mcp`
3. Complete the OAuth sign-in flow with your Wheelhouse account.

**Manual config**

If your organization does not allow custom connectors, add this to
`claude_desktop_config.json` and restart Claude Desktop:

```json
{
  "mcpServers": {
    "wheelhouse": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.usewheelhouse.com/mcp"]
    }
  }
}
```

### Claude Code (CLI)

Run this command in your terminal:

```bash
claude mcp add --transport http wheelhouse https://mcp.usewheelhouse.com/mcp
```

### Cursor

1. Open **Cursor Settings → Tools & MCP**, or create `.cursor/mcp.json` in your
   project (or global MCP settings).
2. Add the Wheelhouse server configuration below.
3. Click **Connect** next to Wheelhouse and sign in with your Wheelhouse account
   when prompted.

```json
{
  "mcpServers": {
    "wheelhouse": {
      "url": "https://mcp.usewheelhouse.com/mcp"
    }
  }
}
```

### VS Code

1. Open the Command Palette and run **MCP: Add Server**.
2. Choose **HTTP** and use the configuration below (or add it to your MCP
   settings file).
3. Complete the OAuth sign-in flow with your Wheelhouse account when prompted.

```json
{
  "servers": {
    "wheelhouse": {
      "type": "http",
      "url": "https://mcp.usewheelhouse.com/mcp"
    }
  }
}
```

### Other clients

Clients that support stdio MCP servers can connect through the `mcp-remote`
bridge:

```bash
npx -y mcp-remote https://mcp.usewheelhouse.com/mcp
```

Remote server URL: `https://mcp.usewheelhouse.com/mcp`

## Usage notes

- **Tools use Code Mode.** Discover RM API operations with `search`, inspect
  parameters with `get_schema`, and call them from `execute`. Use the
  [API Reference](https://docs.usewheelhouse.com/rm/reference/wheelhouse-revenue-management-api.md)
  for request parameters, response shapes, and endpoint behavior.
- **Same rate limits.** MCP traffic uses your RM API key and is subject to the
  same limits described in [Usage & limits](https://docs.usewheelhouse.com/rm/usage.md) (60 requests per minute
  by default). Prefer batch endpoints when working across many listings.
- **Confirm before writes.** Ask your assistant to show proposed changes
  (preference diffs, preview results, or concrete price impact) and approve
  before any PUT/DELETE or mutating POST.
- **Feedback goes straight to us.** When something fails, is missing, or the
  docs were unclear, your assistant can send feedback with `POST /feedback`
  without asking first, and tells you afterwards. You can also ask it to send
  your own feedback. Every item is reviewed by the Wheelhouse team; it is not a
  support channel.
- **Preference arrays replace fully.** When updating preferences, omitting a
  top-level field leaves it unchanged, but any array field you include fully
  replaces that array. Always read current preferences first, merge carefully,
  and confirm before writing. See
  [Listing preferences](https://docs.usewheelhouse.com/rm/concepts/preferences.md).
- **Skills.** Workflow guidance for portfolio analysis, pacing, and preference
  writes lives in the [Wheelhouse Plugin](https://docs.usewheelhouse.com/rm/wheelhouse-plugin.md). Install it
  in your assistant (Cursor, Claude Code, Codex) alongside the MCP connection.
