Mashvisor MCP Server

Connect Claude, Cursor, VS Code, ChatGPT-style agents and your own code to Mashvisor's real-estate data and AI agents through the Model Context Protocol (MCP).

Server namemashvisor-agents
Endpointhttps://chat.mash-gpt.com/api/v1/agent-api/mcp
TransportMCP Streamable HTTP (stateless, POST only)
AuthenticationAPI key in a header: X-API-Key: mvk_… or Authorization: Bearer mvk_…
CapabilitiesTools, Prompts, Resources

Quick setup

One paste

Connect Mashvisor to your AI app

Choose your app, add your API key, copy the prompt, and paste it where shown. The AI sets up the connection, checks your key, and runs a test.

Create a key at chat.mash-gpt.com → Settings → API Keys. It stays on this page and is never saved or sent anywhere.

Paste intothe Code tab in Claude Desktop (or Claude Code in a terminal). The regular Chat tab can’t edit settings files. When it finishes, quit Claude Desktop completely and reopen it.
Setup prompt
Set up the Mashvisor MCP server for me. Follow these steps exactly and tell me briefly what you are doing at each step.

CONFIGURATION
- Server name: mashvisor
- Endpoint URL: https://chat.mash-gpt.com/api/v1/agent-api/mcp
- Transport: Streamable HTTP (remote, POST only, stateless)
- Auth header: X-API-Key
- API key: mvk_PASTE_YOUR_KEY_HERE
- TARGET CLIENTS: Claude Desktop

RULES
- Treat the API key as a secret. Never print it back in full (show at most the first 8 characters), never upload it anywhere except the Mashvisor endpoint above, and never write it into a file inside a git repository or any file that would be committed. Use user-level (global) config locations, not project files.
- If the key above is "use env MASHVISOR_API_KEY", read it from that environment variable instead.
- Before changing any existing config file, make a timestamped backup copy next to it. Merge the "mashvisor" entry into the existing file: keep every other server and setting exactly as it is. If a "mashvisor" entry already exists, replace only that entry. Make sure the result is valid JSON/TOML.
- Create the file and any parent folders if they don't exist.
- Ask me before installing anything.

STEP 1 — Check the key
Run this request (macOS/Linux shown; on Windows use curl.exe in PowerShell with the same headers):
  curl -s -o /dev/null -w "%{http_code}" -X POST https://chat.mash-gpt.com/api/v1/agent-api/mcp \
    -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
- 200 means the key works. Continue.
- 401 means the key is missing or invalid. Stop and tell me to create a new key at chat.mash-gpt.com → Settings → API Keys.
- Anything else: show me the status code and stop.

STEP 2 — Decide which client(s) to configure
- If TARGET CLIENTS is "auto", configure the client you are currently running in.
- Otherwise configure each client listed. Detect my operating system first.

STEP 3 — Configure each target client using the matching recipe

[Claude Desktop]
Requires Node.js 18+: check "node --version". If missing or older, stop and ask me to install Node.js LTS from nodejs.org.
Config file:
  macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
Add under "mcpServers":
  "mashvisor": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://chat.mash-gpt.com/api/v1/agent-api/mcp", "--header", "X-API-Key:${MASHVISOR_API_KEY}"],
    "env": { "MASHVISOR_API_KEY": "<KEY>" }
  }
Keep "X-API-Key:${MASHVISOR_API_KEY}" with no space after the colon and keep the literal ${MASHVISOR_API_KEY} text (mcp-remote substitutes it from "env").
If "npx" is not on the PATH Claude Desktop uses (common with nvm/volta/asdf), set "command" to the absolute path from "which npx" (macOS) or "where npx" (Windows).
Then tell me to fully quit Claude Desktop (Cmd+Q on macOS, or right-click the tray icon → Quit on Windows) and reopen it.

STEP 4 — Test
Newly added servers only load after the client restarts or a new session starts, so the tools are usually not available to you yet. If you are the client you just configured and the mashvisor tools ARE already available to you, call the tool rento_lookup with {"state":"TX","city":"Dallas","resource":"airbnb","beds":3} and show me the median occupancy, nightly rate and monthly rental income.
Otherwise run this check yourself and confirm the response contains "median_rental_income":
  curl -s -X POST https://chat.mash-gpt.com/api/v1/agent-api/mcp \
    -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"rento_lookup","arguments":{"state":"TX","city":"Dallas","resource":"airbnb","beds":3}}}'

STEP 5 — Summary
Finish with a short summary:
- Which client(s) you configured and the exact config file path for each
- Where the backup copies are
- What I need to do now (restart which app, which toggle to check)
- Three example questions to try, for example:
  "What does a 3-bedroom Airbnb in Nashville, TN earn per month?"
  "Compare long-term rent by bedroom count in Phoenix, AZ."
  "Show 12 months of Airbnb seasonality in Myrtle Beach, SC."

Prefer to set it up by hand? Every client’s manual steps are in Connect your client below.

1. What you get

The server exposes two families of tools, plus ready-made prompts and reference docs.

Rento data tools (10) — fast, deterministic market data from the Mashvisor API. They return structured JSON (rental income, occupancy, nightly rate, cap rate, cash flow, comps, trends). Use them when you want numbers.

ToolWhat it answers
rento_lookup"What will a rental here earn?" Income, occupancy, expenses, cash flow, cap rate, cash-on-cash return
rento_bedsPerformance broken down by bedroom count
rento_bathsPerformance broken down by bathroom count
rento_property_typesPerformance by property type (single family, condo, townhouse…)
rento_revenue_statsRevenue, occupancy and ADR distribution (median plus 5th–95th percentiles)
rento_historical_performanceMonth-by-month revenue, occupancy and rate trends, year over year
rento_rental_activityObserved booked-versus-available short-term rental activity
rento_list_compsOne page of rental comparables (up to 20 per page)
rento_export_compsA downloadable comps export link (Excel .xlsx)
rento_nearby_listingsFor-sale MLS listings nearby, with investment analysis

AI agent tools — full Mashvisor GPT agents that research, reason across many data sources and write a narrative answer. Use them when you want analysis and recommendations.

ToolAgentMinimum plan
general_gptGeneral Agent — broad property, market, rental and investment questionsFree
investor_gptInvestorGPT — ROI, cash flow projections, market trendsFree
broker_gptBrokerGPT — market analysis, CMAs, lead strategyPro
appraiser_gptAppraiserGPT — valuations from comps and conditionPro
lender_gptLenderGPT — pre-qualification, loan products, underwritingTeam
developer_gptDeveloperGPT — zoning, construction, feasibilityTeam

Your client only sees the agent tools your plan includes. All Rento data tools are available on every plan.

Prompts (3): property_analysis, market_screening, rental_comparison. Resources (3): mashvisor://docs/overview, mashvisor://docs/general-agent, mashvisor://docs/tool-usage.


2. Before you start

  1. A Mashvisor GPT account at chat.mash-gpt.com.
  2. An API key. In Mashvisor GPT, open Settings → API Keys → Create key. Copy the key (it starts with mvk_). It is shown only once.
    • Keys inherit your plan's permissions and quota.
    • Key limits per plan: Free 1, Pro 3, Team 10, Enterprise unlimited.
    • Revoke a key from the same screen at any time.
  3. Node.js 18 or newer, only if you use Claude Desktop or another client that needs the mcp-remote bridge (section 3.1). Check with node --version.

Keep your key secret. Put it in the client's header or environment configuration only. Never paste it into a chat message, a prompt, tool arguments, or a shared repository.

Quick connectivity check

curl -s https://chat.mash-gpt.com/api/v1/agent-api/mcp \
  -H "X-API-Key: $MASHVISOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A working key returns a list of tools. A missing or invalid key returns HTTP 401.


3. Connect your client

Every client needs the same three things: the endpoint URL, the transport (Streamable HTTP, sometimes labelled "http"), and the X-API-Key header. Pick your client below.

Fastest: let your AI agent set it up

If you use an AI coding agent that can edit files and run commands (Claude Code, Cursor, VS Code Copilot, Windsurf, Gemini CLI, Codex CLI), paste the prompt below into it. The agent checks your key, adds the server to the client(s) you choose, including Claude Desktop, backs up your existing config, and runs a test query.

  1. Replace mvk_PASTE_YOUR_KEY_HERE with your key.
  2. Optional: change TARGET CLIENTS: auto to the clients you want, e.g. Claude Desktop and Cursor.
  3. Paste it into the agent, approve its commands and edits, then restart the client(s) it names.

Your key appears in that agent conversation and is saved in the client's config file on your computer; the prompt tells the agent not to repeat, upload or commit it.

Set up the Mashvisor MCP server for me. Follow these steps exactly and tell me briefly what you are doing at each step.

CONFIGURATION
- Server name: mashvisor
- Endpoint URL: https://chat.mash-gpt.com/api/v1/agent-api/mcp
- Transport: Streamable HTTP (remote, POST only, stateless)
- Auth header: X-API-Key
- API key: mvk_PASTE_YOUR_KEY_HERE
- TARGET CLIENTS: auto

RULES
- Treat the API key as a secret. Never print it back in full (show at most the first 8 characters), never upload it anywhere except the Mashvisor endpoint above, and never write it into a file inside a git repository or any file that would be committed. Use user-level (global) config locations, not project files.
- If the key above is "use env MASHVISOR_API_KEY", read it from that environment variable instead.
- Before changing any existing config file, make a timestamped backup copy next to it. Merge the "mashvisor" entry into the existing file: keep every other server and setting exactly as it is. If a "mashvisor" entry already exists, replace only that entry. Make sure the result is valid JSON/TOML.
- Create the file and any parent folders if they don't exist.
- Ask me before installing anything.

STEP 1 — Check the key
Run this request (macOS/Linux shown; on Windows use curl.exe in PowerShell with the same headers):
  curl -s -o /dev/null -w "%{http_code}" -X POST https://chat.mash-gpt.com/api/v1/agent-api/mcp \
    -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
- 200 means the key works. Continue.
- 401 means the key is missing or invalid. Stop and tell me to create a new key at chat.mash-gpt.com → Settings → API Keys.
- Anything else: show me the status code and stop.

STEP 2 — Decide which client(s) to configure
- If TARGET CLIENTS is "auto", configure the client you are currently running in.
- Otherwise configure each client listed. Detect my operating system first.

STEP 3 — Configure each target client using the matching recipe

[Claude Code]
Run:
  claude mcp add --scope user --transport http mashvisor https://chat.mash-gpt.com/api/v1/agent-api/mcp --header "X-API-Key: <KEY>"
If "mashvisor" already exists, run "claude mcp remove mashvisor --scope user" first. Note: "claude mcp add" and "claude mcp get" echo the header, including the full key, in their output; mask it when you relay that output to me. Verify with "claude mcp list" (it does not show headers) and confirm mashvisor shows "✓ Connected".

[Claude Desktop]
Requires Node.js 18+: check "node --version". If missing or older, stop and ask me to install Node.js LTS from nodejs.org.
Config file:
  macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
Add under "mcpServers":
  "mashvisor": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://chat.mash-gpt.com/api/v1/agent-api/mcp", "--header", "X-API-Key:${MASHVISOR_API_KEY}"],
    "env": { "MASHVISOR_API_KEY": "<KEY>" }
  }
Keep "X-API-Key:${MASHVISOR_API_KEY}" with no space after the colon and keep the literal ${MASHVISOR_API_KEY} text (mcp-remote substitutes it from "env").
If "npx" is not on the PATH Claude Desktop uses (common with nvm/volta/asdf), set "command" to the absolute path from "which npx" (macOS) or "where npx" (Windows).
Then tell me to fully quit Claude Desktop (Cmd+Q on macOS, or right-click the tray icon → Quit on Windows) and reopen it.

[Cursor]
Config file: ~/.cursor/mcp.json  (Windows: %USERPROFILE%\.cursor\mcp.json)
Add under "mcpServers":
  "mashvisor": {
    "url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
    "headers": { "X-API-Key": "<KEY>" }
  }
Tell me to open Cursor Settings → MCP and check that mashvisor has a green dot (toggle it off and on if needed).

[VS Code — GitHub Copilot]
Use the user-level MCP configuration, not .vscode/mcp.json in a repository. Prefer the CLI:
  code --add-mcp '{"name":"mashvisor","type":"http","url":"https://chat.mash-gpt.com/api/v1/agent-api/mcp","headers":{"X-API-Key":"<KEY>"}}'
(On Windows PowerShell, escape the inner quotes accordingly.) If the "code" CLI is not available, open the user mcp.json via the Command Palette command "MCP: Open User Configuration" and add under "servers":
  "mashvisor": {
    "type": "http",
    "url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
    "headers": { "X-API-Key": "<KEY>" }
  }
Tell me to run "MCP: List Servers" → mashvisor → Start, then use Copilot Chat in Agent mode.

[Windsurf]
Config file: ~/.codeium/windsurf/mcp_config.json  (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json)
Add under "mcpServers":
  "mashvisor": {
    "serverUrl": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
    "headers": { "X-API-Key": "<KEY>" }
  }
Tell me to press Refresh in the Cascade MCP panel.

[Gemini CLI]
Config file: ~/.gemini/settings.json  (Windows: %USERPROFILE%\.gemini\settings.json)
Add under "mcpServers":
  "mashvisor": {
    "httpUrl": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
    "headers": { "X-API-Key": "<KEY>" }
  }
Tell me to restart Gemini CLI and run /mcp.

[OpenAI Codex CLI]
Config file: ~/.codex/config.toml  (Windows: %USERPROFILE%\.codex\config.toml)
Add:
  [mcp_servers.mashvisor]
  url = "https://chat.mash-gpt.com/api/v1/agent-api/mcp"
  http_headers = { "X-API-Key" = "<KEY>" }
Tell me to restart Codex and run /mcp.

[Any other client]
If the client supports remote Streamable HTTP servers with custom headers, use the URL and X-API-Key header above. If it only supports local (stdio) servers, use the Claude Desktop "npx mcp-remote" command. If it only supports OAuth sign-in for remote servers (for example claude.ai web or ChatGPT connectors), tell me it isn't supported with an API key yet.

STEP 4 — Test
Newly added servers only load after the client restarts or a new session starts, so the tools are usually not available to you yet. If you are the client you just configured and the mashvisor tools ARE already available to you, call the tool rento_lookup with {"state":"TX","city":"Dallas","resource":"airbnb","beds":3} and show me the median occupancy, nightly rate and monthly rental income.
Otherwise run this check yourself and confirm the response contains "median_rental_income":
  curl -s -X POST https://chat.mash-gpt.com/api/v1/agent-api/mcp \
    -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"rento_lookup","arguments":{"state":"TX","city":"Dallas","resource":"airbnb","beds":3}}}'

STEP 5 — Summary
Finish with a short summary:
- Which client(s) you configured and the exact config file path for each
- Where the backup copies are
- What I need to do now (restart which app, which toggle to check)
- Three example questions to try, for example:
  "What does a 3-bedroom Airbnb in Nashville, TN earn per month?"
  "Compare long-term rent by bedroom count in Phoenix, AZ."
  "Show 12 months of Airbnb seasonality in Myrtle Beach, SC."

Claude Code only? One command does it:

claude mcp add --scope user --transport http mashvisor https://chat.mash-gpt.com/api/v1/agent-api/mcp --header "X-API-Key: mvk_PASTE_YOUR_KEY_HERE"

Prefer to do it by hand? Follow the recipe for your client below.

3.1 Claude Desktop (macOS and Windows)

Claude Desktop's built-in Custom Connectors screen only supports OAuth sign-in, so connect through the open-source mcp-remote bridge, which adds the API key header for you.

  1. Open Claude Desktop → Settings → Developer → Edit Config. This opens claude_desktop_config.json:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add the mashvisor entry (merge it into mcpServers if you already have other servers):
{
  "mcpServers": {
    "mashvisor": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
        "--header",
        "X-API-Key:${MASHVISOR_API_KEY}"
      ],
      "env": {
        "MASHVISOR_API_KEY": "mvk_your_key_here"
      }
    }
  }
}
  1. Save the file and fully quit and reopen Claude Desktop (on macOS use ⌘Q; closing the window is not enough).
  2. In a new chat, click the tools / connectors icon in the message box. You should see mashvisor with its tools listed.
  3. Try: "Using the Mashvisor tools, what does a 3-bedroom Airbnb in Dallas, TX typically earn?"

Notes:

  • Write the header as X-API-Key:${MASHVISOR_API_KEY} with no space after the colon. Some Windows setups split arguments on spaces.
  • If npx is not found, replace "command": "npx" with the full path from which npx (macOS) or where npx (Windows).
  • Prompts appear under the + (attach) menu → mashvisor. Resources can be attached the same way.
  • Logs: macOS ~/Library/Logs/Claude/mcp-server-mashvisor.log; Windows %APPDATA%\Claude\logs\.

3.2 Claude Code (CLI)

claude mcp add --transport http mashvisor \
  https://chat.mash-gpt.com/api/v1/agent-api/mcp \
  --header "X-API-Key: mvk_your_key_here"

Add --scope user to make it available in every project, or --scope project to share it with your team via .mcp.json (then use an environment variable instead of a literal key):

{
  "mcpServers": {
    "mashvisor": {
      "type": "http",
      "url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
      "headers": { "X-API-Key": "${MASHVISOR_API_KEY}" }
    }
  }
}

Verify with claude mcp list, or run /mcp inside a session. Prompts are available as slash commands, for example /mcp__mashvisor__market_screening.

3.3 Cursor

Open Cursor Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "mashvisor": {
      "url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
      "headers": { "X-API-Key": "mvk_your_key_here" }
    }
  }
}

The server should show a green dot and its tool count. Use it from the Agent chat.

3.4 VS Code (GitHub Copilot agent mode)

Create .vscode/mcp.json in your workspace (or run MCP: Add Server from the Command Palette). This version prompts for the key once and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mashvisor-key",
      "description": "Mashvisor MCP API key (mvk_...)",
      "password": true
    }
  ],
  "servers": {
    "mashvisor": {
      "type": "http",
      "url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
      "headers": { "X-API-Key": "${input:mashvisor-key}" }
    }
  }
}

Click Start above the server entry, then open Copilot Chat in Agent mode and pick the Mashvisor tools from the tools menu.

3.5 Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (or Settings → Cascade → MCP Servers → View raw config):

{
  "mcpServers": {
    "mashvisor": {
      "serverUrl": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
      "headers": { "X-API-Key": "mvk_your_key_here" }
    }
  }
}

Press Refresh in the MCP panel.

3.6 Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "mashvisor": {
      "httpUrl": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
      "headers": { "X-API-Key": "mvk_your_key_here" }
    }
  }
}

Run /mcp inside Gemini CLI to confirm the tools loaded.

3.7 Other desktop clients

Any MCP client that supports Streamable HTTP with custom headers works with the same URL and header. If a client only supports local (stdio) servers, use the mcp-remote command from section 3.1 as the server command.

Not currently supported: clients that only accept OAuth sign-in for remote servers, such as claude.ai web Custom Connectors and ChatGPT Connectors. Contact us if you need one of these.


4. Use the server from your own code

4.1 Claude API (MCP connector)

Claude can call the Mashvisor server directly from the Messages API; no MCP client code is needed. The authorization_token is sent as Authorization: Bearer mvk_…, which the server accepts.

import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
        "name": "mashvisor",
        "authorization_token": os.environ["MASHVISOR_API_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "mashvisor"}],
    messages=[{
        "role": "user",
        "content": "Compare Airbnb revenue by bedroom count in Austin, TX and recommend the best unit size for a $450k budget.",
    }],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

4.2 OpenAI Responses API

import os
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "mashvisor",
        "server_url": "https://chat.mash-gpt.com/api/v1/agent-api/mcp",
        "headers": {"X-API-Key": os.environ["MASHVISOR_API_KEY"]},
        "require_approval": "never",
    }],
    input="What is the median Airbnb occupancy and nightly rate in Nashville, TN?",
)
print(response.output_text)

4.3 Python MCP SDK

import asyncio, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = "https://chat.mash-gpt.com/api/v1/agent-api/mcp"

async def main():
    headers = {"X-API-Key": os.environ["MASHVISOR_API_KEY"]}
    async with streamablehttp_client(URL, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool("rento_lookup", {
                "state": "TX", "city": "Dallas", "resource": "airbnb", "beds": 3,
            })
            print(result.structuredContent)

asyncio.run(main())

4.4 TypeScript MCP SDK

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://chat.mash-gpt.com/api/v1/agent-api/mcp"),
  { requestInit: { headers: { "X-API-Key": process.env.MASHVISOR_API_KEY! } } },
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool({
  name: "rento_revenue_stats",
  arguments: { state: "FL", city: "Miami", resource: "airbnb" },
});
console.log(result.structuredContent);

4.5 Raw HTTP (curl / Postman)

Every request is a single JSON-RPC message sent with POST. Include both headers:

Content-Type: application/json
Accept: application/json, text/event-stream
curl -s https://chat.mash-gpt.com/api/v1/agent-api/mcp \
  -H "X-API-Key: $MASHVISOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "rento_beds",
      "arguments": { "state": "TX", "city": "Dallas", "resource": "traditional" }
    }
  }'

The response may arrive as a Server-Sent Events frame; the JSON-RPC result is on the line starting with data:. The server is stateless: no session ID is issued, and GET /mcp returns 405.

4.6 MCP Inspector (interactive testing)

npx @modelcontextprotocol/inspector

In the Inspector, choose Transport: Streamable HTTP, enter the endpoint URL, add the header X-API-Key with your key under Authentication, then Connect. You can browse and run every tool, prompt and resource.


5. Tool reference

5.1 Rento data tools — shared parameters

All ten Rento tools accept the same parameters. Each tool uses the ones relevant to it and ignores the rest.

Location (required — supply one of these):

LevelParametersExample
Citystate + city{"state": "TX", "city": "Dallas"}
ZIP codestate + zipCode{"state": "TX", "zipCode": "75201"}
Neighborhoodstate + neighborhoodId{"state": "TX", "neighborhoodId": 12345}
Addressstate + address + zipCode + lat + lngsee below

Address-level requests need a real, verified address with its ZIP code and matching coordinates. lat and lng must always be sent together.

Rental strategy and filters:

ParameterTypeDefaultDescription
resource"airbnb" | "traditional"airbnbShort-term (Airbnb) or long-term (traditional) rental data
bedsinteger ≥ 0–Filter to a bedroom count (0 = studio)
bathsnumber ≥ 0–Filter to a bathroom count
homeTypestring–Property type filter, e.g. single family, condo, townhouse

Investment inputs (rento_lookup, rento_nearby_listings):

ParameterTypeDefaultDescription
propertyPricenumbermarket medianPurchase price to analyze
paymentType"cash" | "financed"cashCash purchase or mortgage-financed
downPaymentnumber–Down payment amount in dollars (financed only)
propertyIdinteger–A specific Mashvisor property ID

Paging, radius and time range:

ParameterTypeDefaultUsed by
pageinteger ≥ 11rento_list_comps, rento_nearby_listings
limitinteger 1–20–rento_list_comps, rento_nearby_listings
radiusnumber (miles)–rento_nearby_listings, comps
limitRecentMonthsinteger 1–24–rento_historical_performance
startMonth / endMonth"YYYY-MM"–rento_historical_performance

Response format. Each Rento tool returns structuredContent (and the same JSON as text):

{
  "endpoint": "lookup",
  "resource": "airbnb",
  "location": { "state": "TX", "city": "Dallas", "zipCode": null, "address": null },
  "data": { "...": "source data from Mashvisor" }
}

Values that are not available stay null. Occupancy is on a 0–100 scale. Monetary values are in the market's currency (USD for US markets), monthly unless the field name says annual.


5.2 rento_lookup — rental estimate and investment returns

The core "what will it earn" tool. Returns median home value, rental income, nightly rate, occupancy, an itemized monthly expense breakdown, cash flow, cap rate and cash-on-cash return.

Use it for: quick underwriting of a market or a property, cash vs. financed scenarios, checking whether a price works.

Example prompts:

  • "What's the expected Airbnb income and cap rate for a 3-bed in Dallas, TX?"
  • "If I buy a $415,000 home in Dallas with $83,000 down, what's my monthly cash flow as a long-term rental?"
  • "Run the numbers on 1600 Main Street, Dallas TX 75201 as a short-term rental."

Example call:

{ "state": "TX", "city": "Dallas", "resource": "airbnb", "beds": 3 }

Example result (abridged, live data):

{
  "median_home_value": 399000,
  "sample_size": 570,
  "median_occupancy_rate": 30,
  "median_night_rate": 241,
  "median_rental_income": 1938,
  "median_annual_revenue": 23256,
  "expenses": 1725.75,
  "expenses_map": { "propertyTax": 599, "maintenace": 333, "management": 533, "insurance": 91, "utilities": 170, "hoa_dues": 0 },
  "cash_flow": 407.40,
  "cap_rate": 1.23,
  "cash_on_cash": 1.21,
  "tax_rate": 1.8,
  "revpar": 72.3
}

Financed scenario:

{ "state": "TX", "city": "Dallas", "resource": "traditional",
  "paymentType": "financed", "propertyPrice": 415000, "downPayment": 83000 }

5.3 rento_beds — performance by bedroom count

Returns one row per bedroom count with listing count, median rent, adjusted rental income, nightly rate and occupancy.

Use it for: choosing the best unit size, spotting where supply is thin.

Example prompts:

  • "Which bedroom count earns the most on Airbnb in Scottsdale, AZ?"
  • "Show long-term rent by bedroom count in Dallas."

Example call: { "state": "TX", "city": "Dallas", "resource": "traditional" }

Example result (abridged, live data):

[
  { "beds": "1", "count": 1682, "median": 1300, "median_occupancy": 92.3 },
  { "beds": "2", "count": 2580, "median": 2250, "median_occupancy": 92.3 },
  { "beds": "3", "count": 2650, "median": 2750, "median_occupancy": 92.3 },
  { "beds": "4", "count": 1004, "median": 3275, "median_occupancy": 92.3 }
]

5.4 rento_baths — performance by bathroom count

Same shape as rento_beds, grouped by bathrooms.

Example prompt: "Does adding a second bathroom increase Airbnb revenue in Gatlinburg, TN?" Example call: { "state": "TN", "city": "Gatlinburg", "resource": "airbnb" }

5.5 rento_property_types — performance by property type

Breaks results down by category (single family, condo, townhouse, multi-family and others).

Example prompt: "Are condos or single-family homes better short-term rentals in Miami?" Example call: { "state": "FL", "city": "Miami", "resource": "airbnb" }

5.6 rento_revenue_stats — revenue percentiles

Revenue, occupancy and average daily rate (ADR) as min, max, average, median and the 5th, 10th, 20th, 80th, 90th and 95th percentiles, so you can see what a top-10% operator earns versus the median.

Example prompts:

  • "What does a top 10% Airbnb in Destin, FL earn compared to the median?"
  • "Give me the ADR distribution for 2-bedroom rentals in Denver."

Example call: { "state": "CO", "city": "Denver", "resource": "airbnb", "beds": 2 }

5.7 rento_historical_performance — monthly trends

Month-by-month revenue, nightly rate and occupancy, with year-over-year comparison.

Use it for: seasonality, trend direction, peak and off-season planning.

Example prompts:

  • "Show Airbnb seasonality in Myrtle Beach over the last 12 months."
  • "How did occupancy in Austin change from January to June 2026?"

Example calls:

{ "state": "SC", "city": "Myrtle Beach", "resource": "airbnb", "limitRecentMonths": 12 }
{ "state": "TX", "city": "Austin", "resource": "airbnb", "startMonth": "2026-01", "endMonth": "2026-06" }

5.8 rento_rental_activity — booked vs. available activity

Observed short-term-rental calendar activity: how much inventory was booked versus available.

Example prompt: "How busy are Airbnbs in Orlando right now — booked versus available nights?" Example call: { "state": "FL", "city": "Orlando", "resource": "airbnb" }

5.9 rento_list_comps — rental comparables

Returns one page of comparable rentals. Ask for the next page explicitly; the server never downloads a whole market at once. Page size is up to 20.

Example prompts:

  • "List 10 comparable 3-bed Airbnbs in ZIP 37203."
  • "Show me the next page of those comps."

Example call:

{ "state": "TN", "zipCode": "37203", "resource": "airbnb", "beds": 3, "page": 1, "limit": 10 }

5.10 rento_export_comps — downloadable comps file

Generates a comps export and returns a time-limited download link (the server does not download the file itself). Open the link promptly; if it has expired, run the tool again.

Example prompt: "Export the Airbnb comps for Dallas as a spreadsheet I can open in Excel." Example call: { "state": "TX", "city": "Dallas", "resource": "airbnb" }

5.11 rento_nearby_listings — for-sale listings with analysis

Nearby MLS listings with Mashvisor's investment analysis for each, within a radius in miles.

Use it for: deal sourcing, "what can I buy near here that cash-flows".

Example prompts:

  • "Find for-sale homes within 1 mile of downtown Dallas that would work as Airbnbs."
  • "Which nearby listings under $350k have the best cap rate as long-term rentals?"

Example call:

{ "state": "TX", "city": "Dallas", "resource": "airbnb", "radius": 1, "limit": 10 }

5.12 AI agent tools

All agent tools share one input schema:

ParameterRequiredDescription
queryyesYour question in plain language (max 5,000 characters)
contextnoStructured facts, e.g. {"location": {"city": "Austin", "state": "TX"}, "budget": {"min": 200000, "max": 450000}, "investmentType": "short-term"}
conversationIdnoContinue a previous agent conversation
parentMessageIdnoThe messageId of the previous agent reply

The response is the agent's written answer. structuredContent contains conversationId, messageId and tokensUsed; pass the first two back to ask a follow-up in the same thread.

Agent runs take longer than data tools (typically 20–90 seconds) and count against your plan's quota.

general_gpt — General Agent

  • "Analyze Airbnb investment potential in Dallas, Texas. Use current rental data and explain the assumptions."
  • "I have $500k. Should I buy one Airbnb in Nashville or two long-term rentals in Memphis?"

investor_gpt — InvestorGPT

  • "Compare cash flow, cap rate and cash-on-cash return for a $415,000 Airbnb in Dallas, TX with 20% down at 6.5%. State all assumptions."
  • "Build a 5-year projection for a 3-bed long-term rental in Columbus, OH bought at $260k."

broker_gpt — BrokerGPT (Pro)

  • "Prepare a CMA summary for a 4-bed, 2.5-bath home in Plano, TX for a listing presentation."

appraiser_gpt — AppraiserGPT (Pro)

  • "Estimate the market value of a 1,850 sq ft 3-bed in Tampa, FL using recent comps, and explain the adjustments."

lender_gpt — LenderGPT (Team)

  • "What loan products fit an investor buying a $600k short-term rental with 15% down? Include DSCR considerations."

developer_gpt — DeveloperGPT (Team)

  • "Run a rough feasibility check for building four townhomes on a 0.4-acre lot in Boise, ID."

Follow-up example:

{
  "query": "Continue the previous analysis and focus on financing risk.",
  "conversationId": "<conversationId from the previous reply>",
  "parentMessageId": "<messageId from the previous reply>"
}

When to use agents vs. data tools: let your AI assistant call the Rento data tools when it needs specific numbers it can reason over itself. Call an agent tool when you want Mashvisor's specialist to do the full research and write the analysis.


6. Prompts

Prompts are reusable templates your client can insert. In Claude Desktop they appear under + → mashvisor; in Claude Code as /mcp__mashvisor__<name>.

PromptArgumentsProduces
property_analysisproperty (required: address, listing URL or ID), goal (optional: buy, hold, compare…)A disciplined investment analysis: facts, assumptions, income, expenses, financing, cash flow, cap rate, cash-on-cash, comps, sensitivities, next steps
market_screeningcriteria (required: location, budget, strategy, return targets)A screened shortlist of markets or neighborhoods with method, trade-offs and risks
rental_comparisonlocation (required), strategy (optional: long-term or short-term)A ranked comparison of rental options with a downside case

Example (prompts/get):

{ "name": "market_screening",
  "arguments": { "criteria": "Midwest cities under $250k median price, long-term rental, cap rate above 6%" } }

7. Resources

Read-only reference documents your assistant can load for context.

URIContents
mashvisor://docs/overviewService overview, authentication, plans and response conventions
mashvisor://docs/general-agentWhat the General Agent can do and how to give it context
mashvisor://docs/tool-usageHow to call agent tools reliably, including follow-ups

8. Example workflows

These are prompts you can paste into any connected assistant. The assistant chooses and chains the tools.

Underwrite a market in one message

"Using Mashvisor, evaluate Dallas, TX for a 3-bedroom Airbnb. Get the rental estimate, revenue percentiles and 12-month seasonality, then tell me whether a $400k purchase cash-flows with 20% down."

Tools typically used: rento_lookup → rento_revenue_stats → rento_historical_performance.

Pick the best unit size

"Compare bedroom counts and property types for short-term rentals in Scottsdale, AZ and recommend what to buy for a $700k budget."

Tools: rento_beds → rento_property_types → rento_lookup (with propertyPrice).

Short-term vs. long-term

"For a 2-bed condo in Miami, compare Airbnb and long-term rental income, expenses and cap rate side by side."

Tools: rento_lookup twice (resource: airbnb and resource: traditional, beds: 2, homeType: condo).

Deal sourcing

"Find for-sale listings within 2 miles of downtown Nashville that would cash-flow as Airbnbs, then pull comps for the best one."

Tools: rento_nearby_listings → rento_list_comps.

Comps for a spreadsheet

"Export Airbnb comps for ZIP 78704 as a spreadsheet and summarize the median nightly rate."

Tools: rento_export_comps → rento_revenue_stats.

Market screening across cities

"Screen Cleveland, Columbus, Indianapolis and Kansas City for long-term rentals under $250k. Rank them by cap rate and occupancy."

Tools: rento_lookup per city (resource: traditional), or the market_screening prompt.

Hand off to a specialist

"Ask Mashvisor's InvestorGPT for a full 5-year projection on a $415k Airbnb in Dallas with 20% down, then summarize the key risks for me."

Tool: investor_gpt.

Tips for good results

  • Always give a state with a city, and use the two-letter code (TX, not Texas).
  • Say the strategy: "Airbnb / short-term" or "long-term / traditional". The default is Airbnb.
  • Give a price when you care about returns; otherwise the market median home value is used.
  • Ask for assumptions. Ask the assistant to separate reported data from its own calculations.
  • Don't invent addresses. Address-level analysis needs a real address with ZIP and coordinates.

9. Plans, limits and usage

PlanAgent toolsAgent runs per hourAPI keys
FreeGeneral, Investor101
Pro+ Broker, Appraiser1003
Team+ Lender, Developer1,00010
EnterpriseAllUnlimitedUnlimited
  • Hourly limits apply to agent runs. Rento data tools, tools/list, prompts and resources are not counted against the hourly agent limit.
  • All traffic is limited to 100 requests per minute per IP address.
  • Agent runs also draw on your plan's monthly usage quota, shared with your Mashvisor GPT chat usage.
  • Limits may change; your current plan, key count and usage are shown in Settings → API Keys.

10. Errors and troubleshooting

SymptomCauseFix
HTTP 401 MISSING_API_KEYHeader missing or key doesn't start with mvk_Send X-API-Key: mvk_… (check for typos and quotes)
HTTP 401 invalid keyKey revoked or wrongCreate a new key in Settings → API Keys
HTTP 405Client sent GET (opening an SSE stream)Normal for this stateless server; clients fall back to POST. Make sure the transport is Streamable HTTP, not legacy SSE
HTTP 406Accept header missingSend Accept: application/json, text/event-stream
HTTP 429Per-IP or hourly agent limit reachedWait and retry, or upgrade your plan
Access denied: "broker_gpt" requires a higher plan than FREEAgent not in your planUpgrade, or use an agent you have
Provide a location: state with city, ZIP, neighborhoodId, or a verified address.No location givenAdd state + city (or ZIP / neighborhood)
lat and lng must be provided together.Only one coordinate sentSend both, or neither
Address-level analysis requires zipCode together with matching lat and lng.Address + coordinates without ZIPAdd zipCode
The upstream export service returned an expired signed link…Export link staleRetry rento_export_comps in a few minutes
Tools don't appear in Claude DesktopConfig not loadedValidate the JSON, fully quit and reopen, check the mcp-server-mashvisor.log file
npx: command not found / spawn npx ENOENTNode.js not installed or not on PATHInstall Node.js 18+, or use the full path to npx
Agent call takes a long timeAgents research across many sourcesExpected (20–90 s). Increase your client's tool timeout if it cancels early

Tool-level errors come back as a normal MCP result with isError: true and a readable message, so your assistant can correct its own call.


11. Security and data handling

  • Keys are sent only in the HTTP header over HTTPS. The server never requires credentials inside tool arguments.
  • Each key is tied to your account. Usage (tool name, timestamp, outcome, and the location you queried) is logged against the key for quota and support purposes.
  • Create a separate key for each app or teammate so you can revoke one without affecting the others.
  • Revoke a key immediately if it is exposed.
  • Mashvisor data and agent output are for real-estate research and decision support. They are not legal, tax, lending, insurance or investment advice. Verify material decisions with qualified professionals.

12. FAQ

Do I need to install anything? Only for clients that need the mcp-remote bridge (Claude Desktop). Cursor, VS Code, Windsurf, Claude Code and Gemini CLI connect directly.

Which markets are covered? US markets are covered at city, ZIP, neighborhood and address level. Coverage and sample sizes vary by market; check sample_size in results.

Why are some values null? The source had no reliable data for that field in that market. The server never fills gaps with guesses.

How fresh is the data? Rento data comes live from the Mashvisor API on every call. Use rento_historical_performance to see the most recent months available.

Can I use one key in several clients? Yes. Usage from every client counts toward the same plan quota.

Is there a REST API too? Yes. Agents can also be called with POST https://chat.mash-gpt.com/api/v1/agent-api/runs and body {"agent": "investor_gpt", "query": "…"}, using the same key. Check quota with GET /api/v1/agent-api/quota.


Need help? Contact Mashvisor support and include the time of the request and the tool name. Never send your full API key; the first few characters (mvk_ab12…) are enough.

Was this page helpful?