Skip to content

Connect Cursor (MCP)

Cursor talks to RealtyPad over HTTP MCP on the same public host as the web app (/mcp). In production the MCP process is isolated from the REST API; the URL you configure does not change.

Prerequisites

  • Cursor installed
  • RealtyPad account (web login works)
  • API reachable from your machine (local: http://localhost:8000, production: your operator’s HTTPS URL)
  • PUBLIC_BASE_URL set to the public API origin (MCP discovery / token endpoints)
  • WEB_BASE_URL set to the web UI origin (consent page; local default http://localhost:5173)

Step 1 — Add the MCP server (browser OAuth)

Preferred: Cursor discovers OAuth, opens your browser, you sign in and approve the agent. No pasted Bearer token.

  1. Open Cursor Settings → MCP (or edit MCP config).
  2. Add a server with the MCP URL only:

Local example (API on port 8000):

{
  "mcpServers": {
    "RealtyPad": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Production example:

{
  "mcpServers": {
    "RealtyPad": {
      "url": "https://api.yourdomain.com/mcp"
    }
  }
}
  1. Save and reload MCP. Cursor should prompt to authorize → browser opens the web app at /oauth/consent → sign in (if needed) → Authorize.
  2. Ask the agent to call list_deals (limit 3). You should see deals from your tenant only.

If you see “Protected resource … does not match expected”

Clear the server’s stored OAuth state in Cursor (remove/re-add the MCP server, or clear auth), then reconnect. The MCP URL should be without a trailing slash:

http://localhost:8000/mcp

If you see “Authorization session ended” / Cursor never gets the URL

Cursor’s cloud callback (cursor.com/.../oauth/callback) often fails against a localhost MCP URL. Prefer mcp-remote (local :8787 callback) or fully quit Cursor (Cmd+Q) and reconnect:

{
  "mcpServers": {
    "RealtyPad": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "http://localhost:8000/mcp", "8787"]
    }
  }
}

If the browser never opens

Known Cursor issue: discovery succeeds but openExternal never runs. Try in order:

  1. In Settings → MCP, click Needs authentication (not only Connect).
  2. Open Output → MCP: RealtyPad, find Redirect to authorization / authorize URL, paste it into a browser.
  3. Or use the mcp-remote stdio proxy above.

Fallback — static agent JWT

If you need a long-lived token without the browser flow:

  1. Sign in to the web app.
  2. Open Agent → Mint agent JWT.
  3. Configure MCP with a Bearer header:
{
  "mcpServers": {
    "RealtyPad": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

ChatGPT

Same MCP URL: https://app.realtypad.ai/mcp (no trailing slash). ChatGPT needs a public HTTPS endpoint (localhost will not work).

  1. In ChatGPT, open Settings → Apps and turn on Developer mode.
  2. Create a connector, paste the MCP URL, and choose OAuth.
  3. Sign in and authorize. Then ask ChatGPT to list a few deals and to call get_agent_manual.

ChatGPT does not see Cursor project skills. Use get_agent_manual the same way as Claude.

Claude (claude.ai / Claude Desktop)

Same MCP URL: https://app.realtypad.ai/mcp (no trailing slash). Claude uses browser OAuth + Dynamic Client Registration.

Claude does not see Cursor project skills. At session start, call MCP tool get_agent_manual (omit workflow for the full manual, or pass ingest / research / investors / …). That is the reliable path — Claude often cannot read MCP resources or prompts.

For investor share chat and buyer financing profiles, use get_agent_manual(workflow=investors) plus tools such as list_investor_message_threads, list_deal_buyer_messages, and add_deal_buyer_message.

Optional prompts (realtypad_agent_manual, realtypad_skill_*) and resources (guide://realtypad/…) still exist for clients that support them; they return the same Markdown as the tool. Guides ship under api/app/mcp_guides/skills/.

If you see “Couldn’t register with RealtyPad’s sign-in service” (reference like ofid_…), the edge proxy must route /.well-known/* to the API (not the SPA). That is configured in deploy/Caddyfile. After a Caddy reload, these should return JSON (not HTML):

  • https://app.realtypad.ai/.well-known/oauth-protected-resource/mcp
  • https://app.realtypad.ai/.well-known/oauth-authorization-server/mcp

Troubleshooting

Symptom What to check
401 / no authorize prompt PUBLIC_BASE_URL must match the URL Cursor uses; MCP_OAUTH_ENABLED must be true
Consent opens on API HTML / wrong host Set WEB_BASE_URL to the web UI (e.g. http://localhost:5173) and restart API
Claude: couldn’t register / ofid_… GET /.well-known/oauth-protected-resource/mcp must be API JSON; fix Caddy /.well-known/* → API
Empty deals Token/consent bound to a different workspace
Connection refused Wrong host/port; production requires HTTPS

Docker MCP vs remote HTTP

Some setups use a Docker MCP bridge (user-HouseMaxxMCP) on the operator’s machine. For a shared hosted API, prefer the remote HTTP URL above so OAuth scopes to your tenant on the server. Local bridges must send a Bearer agent JWT (or use remote URL + browser OAuth).

Revoking access

Deny on the consent screen, rotate passwords, or mint a new agent JWT and drop the old one from Cursor config. OAuth refresh tokens are server-side and expire (~90 days).