Skip to content
WebMCP

Setup guide

Claude Desktop

Connect your SuperHomes account to Claude Desktop using a personal MCP token. Takes about 5 minutes.

Why mcp-remote?Claude Desktop’s config natively supports stdio MCP servers (local programs). It does not natively read remote HTTP servers from config. mcp-remote is a small npm proxy that wraps the HTTP server as stdio so Claude Desktop can use it. It is installed automatically on first launch via npx -y.

Prerequisites

  • ✓A SuperHomes agentaccount (buyer accounts can’t generate MCP tokens)
  • ✓Claude Desktop installed (macOS or Windows)
  • ✓Node.js installed (for npx) — LTS recommended
1

Generate a token

  1. Sign in at www.superhomes.my.
  2. Open Dashboard → MCP Tokens or go directly to /dashboard/settings/mcp-tokens.
  3. Click Generate token.
  4. Give it a recognisable name like Claude Desktop, MacBook.
  5. Choose scopes — start with read-only, add write later:
    • read:listings — list your active listings
    • read:leads — read leads + inquiry threads
    • write:inquiries — send WhatsApp replies (dry-run enforced)
    • write:listings — toggle listing active state (dry-run enforced)
  6. Click Generate. The raw token (shmcp_…) appears with a 30-second countdown.
Copy your token now. It will not be shown again.
2

Add SuperHomes to Claude Desktop

Locate your config file and add the server block:

OSPath
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json

Open it (create if missing). If it already has other servers, append under mcpServers— don’t replace.

{
  "mcpServers": {
    "superhomes": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.superhomes.my/api/mcp",
        "--header",
        "Authorization: Bearer shmcp_PASTE_YOUR_TOKEN_HERE"
      ]
    }
  }
}

Replace shmcp_PASTE_YOUR_TOKEN_HERE with the token you just copied. Keep the literal Authorization: Bearer prefix.

3

Restart and verify

  1. Quit Claude Desktop fully (not just close the window).
  2. Re-open it and start a new conversation.
  3. Look for the MCP indicator (slider/hammer icon) in the bottom-right of the input area.
  4. Click the indicator — you should see SuperHomes tools listed.
  5. Try a real query:
    “Show me my five most recent leads via SuperHomes.”
Verifying the audit log: every authenticated tool call lands in your audit log. Open Dashboard → MCP Audit and you should see a row appear within seconds.

Alternative: claude.ai web (Custom Connectors)

If you primarily use claude.ai in a browser, go to claude.ai → your profile → Settings → Connectors → Add custom connector → enter https://www.superhomes.my/api/mcp.

Limitation: Custom Connectors currently expects OAuth authentication. Our v1 server uses bearer tokens — the auth step may fail until we add an OAuth wrapper. The mcp-remote path above is the working path today.

Security — please read

Treat your MCP token like an SSH key

Never paste your token into a chat window. Never commit it to git — even a private repo. Generate one token per device so you can revoke individually if a device is lost. The dashboard shows last_used_at per token — audit it occasionally.

Don't connect untrusted MCP servers in the same session

An AI session with both SuperHomes (reads your leads) and an attacker-controlled MCP server can be tricked into exfiltrating buyer PII via the attacker’s tool. Only connect servers you wrote yourself or trust as much as a desktop app. Audit your claude_desktop_config.json periodically.

AI-drafted replies are drafts, not auto-sends

respond_to_inquiry requires a two-step: Claude calls with dry_run: true → server returns a preview + 5-min single-use confirm token → Claude must call again with the token for the message to actually send. Keep the tool-call confirmation prompt on and read the preview carefully.

Revocation is instant

If you suspect a token leak, open the dashboard and click Revoke. The token stops working within 1 minute. Generate a fresh one immediately after.

Troubleshooting

No MCP indicator after restart

Config file has a syntax error, or npx isn't on PATH. Check logs at ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows).

tools/list returns only the three public tools

Bearer token isn't being sent. Check that the Authorization: Bearer prefix has exactly one space and no trailing whitespace in the token string.

forbidden (-32001 "host not allowed")

Only triggers if you point mcp-remote at a non-allowlisted host. The URL in this guide is allowlisted — don't change it.

forbidden (-32001 "insufficient scope")

Your token lacks the scope the tool requires. Regenerate the token with the correct scopes, update your config, restart Claude Desktop.

authentication required (-32003)

Token is malformed, expired, or revoked. Check your dashboard and generate a fresh one.

rate limit exceeded (-32002)

Per-token cap: 120/min reads, 30/min writes. Wait a minute and retry.

Tool call hangs forever

Quit Claude Desktop fully and re-open. If it persists, delete ~/.npm/_npx to clear the mcp-remote cache and retry.

What’s next

Cursor setup guide

Cursor speaks HTTP natively — one fewer hop, simpler config.

Read guide

Manage tokens

Generate, rename, or revoke your MCP tokens.