MCP & agent access

There is nothing to download

RealSiteWorth's MCP surface is a hosted HTTPS endpoint:

https://realsiteworth.com/api/mcp

There is no npm package, no binary, and no local server to run. You point your agent client at that URL and send a Bearer token. "Installing" it means writing a few lines of client config.

The endpoint speaks JSON-RPC 2.0 over POST. It exposes four valuation and account methods plus a tools listing.

What you need first

API access requires a Pro plan. The check is exact: the endpoint accepts a request only when the key belongs to an account whose tier is pro. Free and Basic keys are rejected with the same error as an invalid key.

Pro is $99 per month or $999 per year.

Pro's runtime allowances, straight from the constants:

For contrast, TIER_QUOTAS.basic.basicPerMonth is 250, TIER_QUOTAS.basic.deepPerMonth is 10, and TIER_QUOTAS.free.basicPerMonth is 90 with a per-IP daily cap of 3. Neither tier can call the API — Basic's advanced allowance is real, but this MCP transport is not the way it is spent, and the in-app trigger is rolling out.

Getting your key

1. Sign in and open your account page at /account.
2. Scroll to the API keys section (the heading reads REST API). This block only renders when your tier is pro. If you do not see it, your account is not on Pro. The working interface behind these keys is the MCP endpoint described on this page.
3. In the API Keys panel, type an optional name and press Create key.
4. Copy the key immediately. The full key is returned exactly once. After that only the prefix is stored for display.
5. To revoke, press Revoke next to the key. Revocation is a delete, and any service using that key loses access on the next call.

Key format: rsw_ followed by 40 lowercase hex characters, 44 characters total. Only a SHA-256 hash is stored server side. The panel and the list endpoint show a 12-character prefix (rsw_ plus 8 characters).

A key that has been revoked, or whose enabled flag is false, fails authentication.

Request shape

Every call is a POST with a JSON-RPC 2.0 envelope. All four fields matter:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "value_website",
  "params": { "url": "example.com" }
}

Rules enforced by the parser:

• jsonrpc must be the exact string "2.0".
• method must be present and a string.
• id is required. A request without an id is rejected.
• params is optional and defaults to {}.
• The body must be a JSON object and must be 16384 bytes or smaller.

The request runs for at most 90 seconds.

Responses always return HTTP 200

This trips people up. Success and failure both come back as HTTP 200 with content-type: application/json. The outcome lives in the body: a result key on success, an error key on failure. Do not branch on the HTTP status code. Branch on error.

The only headers added beyond content-type are the rate-limit headers on a throttled request.

There are no CORS headers on this route, so call it from a server, a CLI, or an agent runtime, not from browser JavaScript on another origin.

Methods

Call methods directly by name. There is no tools/list, no initialize, and no notifications/initialized handler. method: "tools/list" returns a method-not-found error. To list what is available, either send method: "tools" or send an unauthenticated GET to /api/mcp.

value_website

Runs a website or domain valuation and returns the full report.

The URL must resolve to a public host. localhost, hostnames without a dot, and private ranges (127., 10., 192.168., 169.254., 0., 172.16-31.) are rejected with an invalid-params error.

The result is the valuation report object, including range (low, mid, high), confidence (label of LOW, MEDIUM, or HIGH, plus pct), mode, category, multiple, est_revenue_monthly, est_profit_monthly, margin, traffic_monthly, authority, trust, memo, roadmap, and nameValue.

kind selects which monthly allowance the run counts against. It does not change the data-pull profile, which is derived from your tier alone. Do not assume deep returns different fields.

value_social

Runs a social account valuation.

youtube and twitch are accepted by the schema but are not served over MCP. Both return an upstream error telling you the platform is not yet available on this surface. Only tiktok, instagram, twitter, and facebook produce a report today.

The result includes surface, handle, range, confidence, multiple, est_monthly_revenue, est_annual_sde, signals, memo, roadmap, and generatedAt.

get_watchlist

Returns the tracked assets on your account. No quota is charged.

Returns { "watchlist": [...] }. Each row has id, domain, surface, targetKind, target, lastRefreshedAt, createdAt, and lastValuation with range, confidenceLabel, and mode. Rows are ordered newest first. If the query errors, the method returns an empty list rather than an error.

get_history

Queries the valuation run ledger. No quota is charged.

Returns { "history": [...] } with requestId, surface, domain, outcome, tier, runKind, createdAt, valueLow, valueMid, and valueHigh.

Known limitation. Ledger rows are written with a SHA-256 hash prefix of the caller id, but this method filters on a raw user-id prefix. The two do not line up, so get_history commonly returns an empty list even when you have run valuations. Read your history in the account portal until this is fixed.

tools

Takes no params. Returns { "tools": [...], "name": "realsiteworth", "description": ..., "version": "1.0.0" } with the JSON Schema for each method's inputs.

End-to-end example

curl -sS https://realsiteworth.com/api/mcp \
  -H "Authorization: Bearer rsw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "value_website",
    "params": { "url": "example.com", "kind": "basic" }
  }'

A successful response looks like this, trimmed:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "url": "https://example.com/",
    "mode": "C",
    "range": { "low": 0, "mid": 0, "high": 0 },
    "confidence": { "label": "LOW", "pct": 0 },
    "memo": [],
    "roadmap": []
  }
}

List the methods without a key:

curl -sS https://realsiteworth.com/api/mcp

Value a TikTok handle:

curl -sS https://realsiteworth.com/api/mcp \
  -H "Authorization: Bearer rsw_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "value_social",
    "params": { "platform": "tiktok", "handle": "someaccount" }
  }'

Client configuration

These snippets point a client at the hosted endpoint with a Bearer header. The config file format is owned by each client, so check your client's own documentation if a field name has changed.

Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "realsiteworth": {
      "url": "https://realsiteworth.com/api/mcp",
      "headers": { "Authorization": "Bearer rsw_your_key_here" }
    }
  }
}

Claude Code, in .mcp.json at your project root:

{
  "mcpServers": {
    "realsiteworth": {
      "type": "http",
      "url": "https://realsiteworth.com/api/mcp",
      "headers": { "Authorization": "Bearer rsw_your_key_here" }
    }
  }
}

Cursor, in ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "realsiteworth": {
      "url": "https://realsiteworth.com/api/mcp",
      "headers": { "Authorization": "Bearer rsw_your_key_here" }
    }
  }
}

Read this before you file a bug: the endpoint answers JSON-RPC method calls directly and does not implement the MCP lifecycle handshake. A client that insists on initialize and tools/list before it will use a server may refuse to connect or may show zero tools. The verified path today is a direct JSON-RPC call from your agent's HTTP tooling or a shell, as in the curl examples above. Use GET /api/mcp or method: "tools" to get the schemas your agent needs.

Never commit a key to a repository. Read it from an environment variable or your client's secret store.

Rate limits

The limiter is a per-user token bucket: 5 requests per second with a burst of 10. It is process local, so it resets on deploy.

When you exceed it, you get error code -32003 and these headers:

These headers are only set on a throttled response.

Error codes

A -32002 tier-forbidden code exists in the code base but this endpoint does not emit it. A non-Pro key produces -32001, because the authentication check and the tier check are one condition.

How API runs meter against your plan

The gate is evaluate, then run, then commit.

1. Before the pipeline starts, the request is checked against your monthly allowance for the requested kind. If it fails, you get -32004, the run is written to the ledger with outcome denied, and nothing is charged.
2. The valuation runs.
3. On success, consumption is committed against your monthly counter, the run is written to the ledger with outcome success, and a daily API call is recorded against the mcp endpoint for your account.
4. On failure, the run is written to the ledger with outcome error and no consumption is committed.

There is one refund case worth knowing. If a social valuation comes back fully degraded, meaning every provider missed and the report holds no real signals, the commit is skipped entirely. A report with nothing in it costs you nothing. Because the gate never reserved anything up front, skipping the commit is the refund, and repeating it cannot mint usage.

get_watchlist and get_history never touch the quota gate and are not recorded as API calls. They still consume rate-limit tokens.

Discovery files

These are public, unauthenticated, and cached for an hour. Point a crawler or an agent at them to learn the surface without a key.

The server card reports capabilities.tools: true with resources and prompts both false, which is accurate. This server exposes callable methods only.

Safety and scope

Every number the endpoint returns comes from the deterministic RealSiteWorth valuation engine, not from a language model. Output is an automated estimate. It is not a formal appraisal, and it is not investment or financial advice.

If you are wiring this into an agent, hold it to the same rule the published skill docs state: the agent may explain and summarize what the endpoint returned, and must not invent valuation inputs, metrics, or dollar figures that RealSiteWorth did not return.

get_watchlist and get_history are private account surfaces scoped to the key holder. Treat what they return as user-owned workspace data.