# Use with AI assistants (MCP) Source: https://help.ruuster.com/api/mcp > Step by step, connect Ruuster to Claude, ChatGPT or any assistant that supports remote MCP servers, sign in once with your owner or admin email and API key, and ask about your listings, leads, traffic and CMAs in plain language. The Ruuster API is also available as an **MCP server** (Model Context Protocol, the open standard AI assistants use to connect to tools). Connect it once, sign in with your Ruuster credentials, and your assistant can answer questions like "which of my leads looked at 31 Chaparral Valley Way this week", "seller report for MLS A2351541, last 4 weeks", "make me a market map of where my leads are looking" or "who are my hottest leads right now". ## Before you start You need three things: 1. **API access turned on for your brokerage.** If you haven't used the Ruuster API before, have an owner or admin email **support@ruuster.com** with your brokerage name. See [Overview](https://help.ruuster.com/api/overview). 2. **Your Ruuster login email and API key**, as an owner or admin. Sign in to the Ruuster web app and copy the key from the Zapier integration settings. Each person uses their own key. Agent logins can't connect. 3. **The server URL:** `https://mcp.ruuster.com/mcp` > **Most important step: use one Claude account everywhere.** When you connect, a Ruuster sign-in > page opens in your web browser. That browser must be signed in to Claude with **the same Claude > account** as the Claude app or tab you're chatting in. If the browser is signed in to a different > Claude account, the sign-in succeeds but is saved to that other account. Claude then keeps showing > "Authorization required" with another **Connect** button, no matter how many times you sign in. > Before step 1, open claude.ai in your default browser and check the account shown at the bottom > left. ## Claude on a Team or Enterprise plan An owner adds Ruuster once for the whole organization (part A). Then each person connects with their own Ruuster key (part B). The owner who added it does part B too. **A. Add Ruuster to the organization (an owner, once)** 1. In Claude, go to **Organization settings › Connectors**. 2. Choose **Add**, then **Custom**, then **Web**. Web means a server reached over the internet, which is what Ruuster is. Desktop is only for a connector that runs on your own computer. 3. Enter the name **Ruuster** and the URL `https://mcp.ruuster.com/mcp`, then continue. 4. Under **Authentication**, choose **Sign in now**. Claude may have pre-selected **No sign-in** with a "Detected" label; change it to **Sign in now**. 5. Under **OAuth client**, choose **Use Claude's published identity**. 6. Leave **Request headers** empty and **Advanced** unchanged. 7. Choose **Add**. You won't be asked to sign in here; that happens in part B. 8. So Claude can put your logo and listing photos into the decks and documents it builds, go to **Organization settings › Capabilities**, choose **Allow network egress to package managers and specific domains**, and add `api.ruuster.com`. See [Logos and photos in decks and documents](#logos-and-photos-in-decks-and-documents). The connector settings can't be edited later. To change them, remove the connector and add it again, and everyone then connects again. **B. Connect your own account (every person, including the owner)** 1. Go to **Customize › Connectors** (your own settings, not Organization settings). 2. Find **Ruuster**, marked **Custom**, and choose **Connect**. 3. A Ruuster page opens in your browser. Enter your Ruuster **login email** and **API key**, then choose **Approve**. 4. The page says you're connected and sends you back to Claude. Ruuster now shows as **Connected**. This is once per person, not once per chat. ## Claude on a Free, Pro or Max plan 1. Go to **Customize › Connectors** and choose **Add custom connector**. 2. Enter the name **Ruuster** and the URL `https://mcp.ruuster.com/mcp`. 3. If the dialog shows **Authentication**, choose **Sign in now** and **Use Claude's published identity**, as in part A above. 4. Choose **Add**, then **Connect** on the new Ruuster entry. 5. Sign in on the Ruuster page with your login email and API key, and choose **Approve**. The Free plan allows one custom connector. ## Use it in a chat (Claude) 1. Start a new chat. 2. Choose **+** in the message box, then **Connectors**, and make sure **Ruuster** is switched on. Claude remembers this for new chats. 3. Ask: **"Which brokerage am I connected as?"** Claude should answer with your brokerage name and data dates. If it does, you're set up. Claude also checks whether it can put your logo and listing photos into decks and documents, and tells you if a setting is still needed. 4. Then ask anything, for example **"What can Ruuster do?"** for a tour of what it can pull. The Claude desktop app and claude.ai share the same connection, so connecting in one connects both. ## Logos and photos in decks and documents When Claude builds a deck, document or file for you, it downloads your logo, agent photos and listing photos in its own sandbox, which can reach only the websites your Claude plan allows. Every image Ruuster gives Claude comes from one address, `api.ruuster.com`, so that's the only one to allow: - **Team or Enterprise:** an owner opens **Organization settings › Capabilities**, chooses **Allow network egress to package managers and specific domains**, and adds `api.ruuster.com`. Then start a new chat. - **Free, Pro or Max:** the setting is a single switch, without a list of your own websites. Attach the image to the chat instead. Until then, Claude tells you when it can't download an image, and the data and your brand colors still come through. ## Claude Code 1. In a terminal, run: ```bash claude mcp add --scope user --transport http ruuster https://mcp.ruuster.com/mcp ``` 2. Start Claude Code, type `/mcp`, choose **ruuster**, then **Authenticate**. 3. Sign in on the Ruuster page that opens, and choose **Approve**. Claude Code keeps its own sign-in, separate from claude.ai. If your Claude account already has Ruuster connected, Claude Code may also list that connection on its own. ## ChatGPT 1. Go to **Settings › Connectors**. On plans that gate custom connectors, turn on **Developer mode** there first. 2. Add a custom connector with the URL `https://mcp.ruuster.com/mcp` and OAuth sign-in. 3. Sign in on the Ruuster page that opens, then enable the connector in a chat. ## Other assistants Cursor, VS Code, Windsurf, Gemini CLI and any other client that supports remote MCP servers with OAuth: add a remote (HTTP) server with the URL `https://mcp.ruuster.com/mcp` and sign in when it opens the Ruuster page. Meta's Muse signs in the same way; see [Muse](#muse). Assistants that connect with an API key instead use `https://mcp.ruuster.com/key` and your key on its own; see [Assistants that take one API key](#assistants-that-take-one-api-key). Assistants that can't finish that sign-in, such as Grok Bot, can send your key in headers instead; see [Grok Bot and other assistants that take headers](#grok-bot-and-other-assistants-that-take-headers). Integrations that don't use an assistant, such as server-to-server jobs, should call the REST API with your key directly. ## Muse Muse connects with the Ruuster sign-in, like Claude and ChatGPT, and stays connected until you remove the connector or Ruuster revokes it. You add a connector by asking for it in a chat; there's no setting for it. 1. In a Muse chat, type: *Add a custom connector called Ruuster at https://mcp.ruuster.com/mcp and sign in.* If you tried before, start with *Delete every Ruuster connector I have* in a new chat. 2. Muse gives you a link to the Ruuster sign-in page. Open it and enter your Ruuster login email and your API key from **Account Settings** in the Ruuster web app (owner or admin login). The key is 60 characters long and starts with `$2b$10$`; copy all of it. 3. On the same page you can add your CRM's API key (Follow Up Boss, Sierra Interactive or Sure Send) so Muse can read your CRM too, and tick the box if you want it to make changes. 4. Back in Muse, ask something like *Summarize my Ruuster account* to try it. Muse has an **API key** option as well. It isn't needed, and Muse's key box has failed to save the key for some people, so use the sign-in. ## Assistants that take one API key Some assistants connect with a single API key, which they send in the `Authorization` header, and have no sign-in. Use the key-only address, `https://mcp.ruuster.com/key`: it offers no sign-in, so the assistant asks for your key straight away. 1. Sign in to the Ruuster web app as an owner or admin and copy your API key from **Account Settings**. It's 60 characters long and starts with `$2b$10$`. That whole string is your key, even though it looks scrambled. Copy all of it. 2. Add Ruuster as a custom server at `https://mcp.ruuster.com/key` with API-key authentication. 3. In the API key field, type your Ruuster login email, a colon, then paste your key right after it, with no spaces. For example, if your login is `jane@yourbrokerage.com`: ``` jane@yourbrokerage.com:$2b$10$Xy7... ``` The email in front works whichever key you have, your own or your brokerage's **integration key** (the one Ruuster set up for your brokerage's app connections, which needs your email to know who you are). Your own key also works on its own, without the email. Under the hood, both `Authorization: Bearer ` (or `Bearer :`) and HTTP Basic (`Authorization: Basic `, or of the key alone) are accepted. A wrong value gets a message that says what to fix. The CRM tools need the CRM headers from the next section, so an assistant that can't set extra headers connects without your CRM. ## Grok Bot and other assistants that take headers Some assistants open the Ruuster page but never finish connecting, or ask for an API key instead of a sign-in. Grok Bot is one. For these, add Ruuster as a custom remote server with the URL `https://mcp.ruuster.com/mcp` and these headers: | Header | Value | |---|---| | `x-email` | Your Ruuster login email (owner or admin) | | `x-api-key` | Your API key from Account Settings, for that same login. `Authorization: Bearer ` also works when `x-email` is sent | | `x-crm-vendor` | Optional: `fub`, `sierra` or `suresend`, for the CRM tools | | `x-crm-key` | Optional: that CRM's API key | | `x-crm-write` | Optional: `allow` lets the assistant change your CRM (Follow Up Boss), always as a preview you confirm first | Don't use the assistant's sign-in or Authorize button for this server; the headers are the sign-in. In Grok Bot, ask it to "add a custom server called Ruuster at https://mcp.ruuster.com/mcp" and give it the headers, or add them under **Settings › Plugins › Yours**. If an earlier attempt left a Ruuster server behind, remove it first. The key is checked on every connection, with the same rules as the sign-in page. A wrong header gets a message that says which one. To disconnect, remove the server or its headers; rotating your API key also ends the connection. ## If something goes wrong | What you see | What to do | |---|---| | "Authorization required" and a **Connect** button after you already signed in, again and again | The browser that opens the Ruuster page is signed in to a different Claude account. Sign that browser in to the same Claude account as your app, then choose **Connect** once more | | "Connected at the account level, but not enabled in this chat" | In the chat, choose **+ › Connectors** and switch Ruuster on | | The Ruuster page says the email and key don't match | Copy both again from the Ruuster web app; the key must belong to that email | | The Ruuster page says your role or brokerage isn't allowed | Only owner and admin logins of a brokerage with API access can connect. See [Authentication](https://help.ruuster.com/api/authentication) | | You can't find **Add** under Organization settings › Connectors | Only an owner of your Claude organization can add it. Ask them to do part A | | "What can Ruuster do?" isn't in Claude's menu | Claude doesn't currently show ready-made asks from custom connectors in its menu. Type the question instead; the answer is the same | | Grok Bot (or another assistant) opened the Ruuster page, you signed in, and it still says it needs a login | That assistant doesn't finish the sign-in. Remove the Ruuster server, add it again with the headers in [Grok Bot and other assistants that take headers](#grok-bot-and-other-assistants-that-take-headers), and skip the sign-in | | Muse worked for about an hour and then stopped | That was an older Muse sign-in, which Ruuster ended after an hour. In a new chat ask Muse to delete every Ruuster connector, then connect again as in [Muse](#muse); the new sign-in doesn't expire | | Muse's API key box says "Failed to connect" as soon as you choose Add | Muse didn't save the key, so nothing reached Ruuster. Use Muse's sign-in instead, as in [Muse](#muse) | | An assistant that takes an API key says "connecting" and never finishes | Remove the Ruuster connector and add it again at `https://mcp.ruuster.com/key`, pasting your whole API key (60 characters, starting with `$2b$10$`) | | "This Ruuster address connects with an API key only" | The assistant reached `https://mcp.ruuster.com/key` without a key. Add the connector again and choose API key | | "Ruuster doesn't recognize this API key" | Copy the key again from Account Settings in the Ruuster web app, signed in as an owner or admin | | "This key is your brokerage's integration key" | That key works for every owner and admin, so it needs to know who you are. Enter your login email, a colon, then the key, with no spaces, for example `jane@yourbrokerage.com:$2b$10$Xy7...`, in place of the key alone, or send `x-email` with it | | "Send your Ruuster login email in an x-email header" | The API key was sent without `x-email`. Add it | | "Ruuster couldn't verify the x-email and API key headers" | Copy both again from the Ruuster web app; the key must belong to that email | | A CRM tool says this connection has no CRM key | Add `x-crm-vendor` and `x-crm-key`. For changes, also `x-crm-write: allow` | | Photos or your logo are missing from a document Claude builds | Claude's file-building sandbox can download only from websites your Claude plan allows. Allow `api.ruuster.com` as in [Logos and photos in decks and documents](#logos-and-photos-in-decks-and-documents), or attach the image. The data and your brand colors still come through | Still stuck? Email **support@ruuster.com** with the time you tried and the assistant you used. ## What you get | | | |---|---| | Server URL | `https://mcp.ruuster.com/mcp` (`https://mcp.ruuster.com` and `https://api.ruuster.com/mcp` also work) | | API-key-only URL | `https://mcp.ruuster.com/key`: no sign-in offered; send `Authorization: Bearer ` (or `Bearer :` for an integration key) | | Transport | Streamable HTTP with OAuth 2.1 (PKCE, client ID metadata documents and dynamic client registration, standard discovery documents) | | Sign-in | A Ruuster page asks once for your owner or admin login email and API key. Assistants that can't sign in send them as `x-email` and `x-api-key` headers instead, or the key alone (or `email:key`) in the `Authorization` header | | Who can connect | Owners and admins of an enabled brokerage, the same as the API | | What it can do | Every read call in this reference, plus Run a CMA. It can't create, change or delete anything else | **What the assistant sees** - One tool per read call, named after the path (`properties_engagement`, `leads_lookup`, `leads_map`, `cma_create`…), with the same parameters as the API, plus composed tools: `seller_report`, `lead_story`, `hot_leads`, `find_listing` (by address, MLS number or id) and `listing_prospects` (reverse prospecting: your leads whose saved searches fit a listing, in one call), and `area_prospects` (your leads looking in a city, zip, county or neighborhood at a price, from CRM and Ruuster activity and saved searches). The `brand` tool returns your logo, name, phone, colors and fonts, so documents it writes can carry your brand. `mortgage_rates` returns today's national rate averages and a trend. `leads_map` returns where your leads are looking, ready to plot. - Ready-made asks: **What can Ruuster do?** (a tour of what it can pull, for the brokerage you're connected as), hottest leads, a lead's story, how a listing is doing, a CMA, a weekly summary, mortgage rates and a seller report. Claude Code lists them as slash commands. In claude.ai, ask in your own words. - These docs as reference material, so it knows the conventions (days are America/Chicago, `from` is included and `to` excluded, one listing per call). - Lists default to 50 rows. The assistant follows `nextCursor` only when you ask for more. **Where your key goes.** Only `mcp.ruuster.com` (or `api.ruuster.com`) ever asks for it. Ruuster keeps it encrypted, tied to that one connection, and uses it to make the same API calls you could make yourself: same brokerage, same lead-contact setting, same limits (`/me` shows them). Every call shows in your usage like any other API call. To disconnect, remove the connector in your assistant; rotating or blocking your API key also ends every connection. **Limits apply as usual.** 120 calls a minute, 20 lookup calls a minute, 200 CMAs a day for your brokerage. If the assistant hits one, it is told how long to wait. A long exploratory conversation can use the lookup allowance quickly; the composed tools are the economical way to answer the common questions. **Not a place for other people's data.** The assistant only sees what your key can see. Lead names, emails and phone numbers that appear in answers carry the same obligations as your CRM data.