PropRaven MCP Server

Connect from your AI client

Every client below connects to the same hosted endpoint, https://propraven.com/mcp. Clients with a connector UI sign in with OAuth; there is no client id or secret to enter. Clients that take a config file can also use an API key (see Hosted — API key).

Claude (connector) — OAuth

1. In Claude (claude.ai, or the Claude desktop app), add a custom connector with the URL https://propraven.com/mcp.
2. Choose Connect, sign in to PropRaven, and approve the one-time consent screen. Claude registers itself automatically (dynamic client registration), so there is no client id to enter.
3. Claude keeps the connection alive with refresh tokens. You sign in again after 180 days at most, or sooner if you revoke the connection or it goes unused for 90 days.

Grok — OAuth

1. Add a custom MCP connector with the URL https://propraven.com/mcp.
2. Sign in to PropRaven and approve access when prompted.

Cursor — OAuth

1. Add PropRaven to ~/.cursor/mcp.json with only the URL, no headers:

{
  "mcpServers": {
    "propraven": { "url": "https://propraven.com/mcp" }
  }
}

2. When Cursor asks you to sign in to the server, sign in to PropRaven and approve access.

Codex — OAuth

Add https://propraven.com/mcp as an HTTP MCP server in Codex and connect your PropRaven account. Codex registers its own OAuth client automatically; leave any client ID or client secret override empty. Sign in and approve access in the browser.

From the Codex CLI:

codex mcp add propraven --url https://propraven.com/mcp
codex mcp login propraven

Any other MCP client

1. Point the client at https://propraven.com/mcp (Streamable HTTP).
2. If it supports MCP OAuth, it discovers the authorization server from the 401 challenge, registers itself, and opens a browser for sign-in and consent. Any https, loopback or native-app redirect URI works (see OAuth reference).
3. If it does not support OAuth, send an API key as a header: Authorization: Bearer pz_….

Hosted — API key (recommended for config files)

No install — point your MCP client at the hosted endpoint https://propraven.com/mcp and connect with OAuth or your API key.

For API-key bearer auth, pass Authorization: Bearer pz_…. This works today in Claude Desktop, Claude Code, Cursor, and Smithery (header config). Connector UIs with no header field (Claude, Grok) use OAuth — see OAuth reference. Get a free key →

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "propraven": {
      "url": "https://propraven.com/mcp",
      "headers": {
        "Authorization": "Bearer pz_your_real_key_here"
      }
    }
  }
}

Claude Code

claude mcp add --transport http propraven https://propraven.com/mcp \
  --header "Authorization: Bearer pz_your_real_key_here"

Cursor

Same config at ~/.cursor/mcp.json.

ChatGPT Custom GPT

Add an Action with OpenAPI URL api.propraven.com/openapi.json and authentication = API Key (Bearer). MCP OAuth is live for other clients too: a client that publishes an OAuth client ID metadata document can connect to https://propraven.com/mcp the same way, with nothing to register by hand.

OAuth reference

PropRaven is an OAuth 2.1 authorization server for the MCP endpoint. Clients are public: PKCE is required and no client secret is ever issued.

Discovery

• · Protected resource (RFC 9728): https://propraven.com/.well-known/oauth-protected-resource/mcp (resource https://propraven.com/mcp). An unauthenticated call to /mcp returns 401 with a WWW-Authenticate header that points here.
• · Authorization server (RFC 8414): https://propraven.com/.well-known/oauth-authorization-server
• · Endpoints: /api/oauth/authorize, /api/oauth/token, /api/oauth/register, /api/oauth/revoke.

Supported flows

• · authorization_code with PKCE (S256 only). Codes are single-use and expire after 5 minutes.
• · refresh_token, for clients that registered it.
• · Not supported: client_credentials, implicit and password.
• · Scope: read (the only scope).

Client registration

Two ways, neither of which needs anything from us:

• · Dynamic client registration (RFC 7591): POST /api/oauth/register. Accepted fields:
  • – redirect_uris (required, up to 10): see Redirect URIs below.
  • – grant_types: any subset of ["authorization_code", "refresh_token"] that includes authorization_code. If you omit it, you get both. Any other grant is refused with invalid_client_metadata.
  • – token_endpoint_auth_method: none. A request for client_secret_post or client_secret_basic is accepted but registered as none, and no secret is issued. private_key_jwt and tls_client_auth are refused.
  • – response_types: code; client_name (optional).
• · Client ID metadata document: use an https URL as the client_id that serves your client metadata. List refresh_token in its grant_types to receive refresh tokens; without it you get authorization_code only.

Redirect URIs

Dynamic registration accepts any https redirect URI on a public host, a loopback http URI (127.0.0.1, localhost or [::1], any port), or a native-app scheme such as cursor:// or vscode://. The consent screen shows where you'll be sent back to, so check it before you approve.

Trouble connecting a client? Email support@propraven.com with the client's name and the error it shows.

Tokens and refresh

• · Access tokens (pzoauth_…, Bearer) last 60 days. Each one maps to a read-only app-connection key on your account's plan. App connections don't count toward your 5 API key slots, and reconnecting the same app reuses its key; revoke one under Settings → API keys.
• · Refresh tokens (pzrt_…) are issued only to clients that registered the refresh_token grant. Call POST /api/oauth/token with grant_type=refresh_token, refresh_token and client_id (in the body, or as the HTTP Basic user name).
• · Refresh tokens rotate on every use: the response carries a new access token and a new refresh token, and the old refresh token stops working. Presenting a refresh token that has already been rotated revokes the whole family (every access and refresh token from that sign-in).
• · Expiry: a refresh token expires 90 days after it was issued (sliding; each rotation starts a new 90 days), and a family never lasts more than 180 days after sign-in (absolute). After that the user signs in again.
• · Scope can only narrow on refresh; asking for more than the original grant returns invalid_scope. Your current plan is re-read on every refresh, so an upgrade applies without signing in again.
• · Connections made before 2026-10-04 have no refresh token. Their access tokens keep working until they expire; reconnect once to start receiving refresh tokens.

Revocation

• · POST /api/oauth/revoke with token=<token> (RFC 7009). Revoking a refresh token revokes its whole family. Revoking an access token revokes that token and the refresh token issued with it. The endpoint always returns 200.
• · Revoking the connected client's key under Settings → API Keys disconnects it immediately; refreshing does not bring it back.

Limits, 429 and 503

Every MCP request counts against the same per-plan windows as the REST API. When a request is refused for rate or load, the answer has that HTTP status, a Retry-After header (seconds) and a JSON-RPC error with code -32003 whose data carries http_status and retry_after. It is never a 401: your credential is still good, so don't reconnect or sign in again. Wait at least Retry-After, then retry with backoff.

• · Burst / daily windows by plan: Free 60 a minute and 1,000 a day; Developer 3,000 a minute and 100,000 a day; Team 12,000 a minute and 1,000,000 a day. Requests without a credential: 60 a minute and 100 a day per IP.
• · 429: your plan's window is used up; or the credential is cooling down for up to 15 minutes because its request rate spiked far above its own recent baseline (it is not banned or revoked, and other keys are unaffected); or one address failed authentication more than 60 times in a minute.
• · 503: PropRaven is briefly shedding load to protect the service (requests without a credential first, paid plans last), or the rate limiter is briefly unavailable.

Local (stdio)

Use the hosted server unless you need a local stdio process (a client that can only launch local commands, or a network that blocks remote MCP servers). The npm package talks to the PropRaven REST API directly with your API key.

The npm package (@propraven/mcp v0.2.0) exposes only 8 tools: parcel_lookup, parcel_search, parcel_compare, owner_pierce, hazard_score, valuation_estimate, permits_history, sales_history. The other 39 hosted-only tools (the free discovery tools, the paid products, comps, coverage, owner cards, licensee and tax-status lookups, deal screens and more) are marked hosted only in the table below; an agent on the npm package does not see them at all. For the full set of 47 tools, connect to https://propraven.com/mcp.

npm install -g @propraven/mcp

{
  "mcpServers": {
    "propraven": {
      "command": "propraven-mcp",
      "env": {
        "PROPRAVEN_API_KEY": "pz_your_real_key_here"
      }
    }
  }
}

Tools

Each tool description is tuned for agent reasoning — explicit “use when / do NOT use when” framing.

Licensee coverage

licensee_firm_search and the licensees block of occupant_lookup cover 10 states, from the free files each state's issuing boards publish: 268,466 firm, branch and office licenses, counted on 2026-10-10. Both require an account; an anonymous call gets a 401.

A sole proprietorship named for its licensee is people data: shown to an account, metered and logged, and withheld for anyone on the privacy suppression list.

Licensed individuals

licensee_individual_search (REST GET /api/v1/licensees/individuals) finds licensed individuals by name, license number, city or ZIP, with the board's published address and, where published, the employer and its business license. People data: an account is required (anonymous gets 401), each page counts as one lookup and is logged, and a person on the privacy suppression list is withheld. Counted on 2026-10-10:

People data

Owner names, mailing addresses, co-owners, phones, e-mails, registered agents and officers are served to any caller with an account (OAuth sign-in or an API key) and to paid calls on the paid tools. Unpaid anonymous calls get the same records with these fields withheld and a people_fields marker saying why.

• permits_history: each permit's owner_name and applicant_name; permit_contacts, every phone and e-mail the jurisdiction published with its role (owner, applicant, contractor, or unknown when the publisher states none); and people_fields_published, the publisher's own owner / applicant / contact fields verbatim.
• owner_card: owner e-mails a permit published for the current owner (emails, email_status), unknown-role phones in people_on_permits, and for an entity owner its Secretary of State filings (registry_filings: registered agent, officers / managers / members, addresses).

Every served people-data response is recorded in PropRaven's access log (ids and field names only).

Verification

curl -X POST https://propraven.com/mcp \
  -H "Authorization: Bearer pz_your_real_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'
# expect: 47

Resources

• · Connect your agent — the discover → preview → pay flow, the x402 dossier walkthrough, and pricing
• · Source on GitHub
• · Model Context Protocol spec
• · Python SDK
• · TypeScript SDK