> ## Documentation Index
> Fetch the complete documentation index at: https://docs.realie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Property data for AI agents

> Nationwide U.S. property records through MCP, CLI, or REST. Sign in with OAuth. Extended FAQ for coding agents.

Same data as the [homepage agents hub](https://www.realie.ai/agents). This page is the docs copy: install commands, OAuth discovery, and a longer FAQ.

Agent-readable Markdown: [agents.md](https://www.realie.ai/agents.md) · [auth.md](https://www.realie.ai/auth.md). Append `.md` to any docs URL (including this one: [agents.md](/agents.md)).

## OAuth first

Do not register an OAuth app in the Clerk dashboard. Hosts discover Realie's authorization server and register themselves (DCR).

<Steps>
  <Step title="Sign in with OAuth">
    Add `https://app.realie.ai/api/mcp` in your MCP host, or run `realie login`. Sign up or sign in in the browser (`accounts.realie.ai`). New accounts are created in that Clerk window.
  </Step>

  <Step title="Enable API access">
    If the Realie account is new, add a payment method in [Billing](https://app.realie.ai/billing/). OAuth does not mint an API key. `tools/call` and `realie lookup` need a billed user. CI and REST keep using `Authorization: YOUR_API_KEY`.
  </Step>
</Steps>

OAuth discovery (on `app.realie.ai`, not clerk.com):

* Resource: `https://app.realie.ai/api/mcp`
* Protected resource metadata: `https://app.realie.ai/.well-known/oauth-protected-resource/mcp`
* Authorization server metadata: `https://app.realie.ai/.well-known/oauth-authorization-server`

<Note>
  `https://docs.realie.ai/mcp` is Mintlify documentation search only. It cannot return property records. Use `https://app.realie.ai/api/mcp` for property data.
</Note>

## Pick how your agent talks to Realie

Same records behind every interface. Start with MCP OAuth unless you already have a key for CI or REST.

<CardGroup cols="3">
  <Card title="MCP" icon="plug" href="/realie-mcp-server">
    Live property tools for Cursor, Claude Code, and other MCP hosts. Add the URL with no API key. Host-specific install steps.
  </Card>

  <Card title="CLI" icon="terminal" href="/realie-cli">
    Terminal and shell workflows. `realie login` opens Clerk, then stores the existing API key. Prefer `--json`.
  </Card>

  <Card title="REST API" icon="code" href="/api-reference/v3/overview">
    Address, parcel, owner, location, and comparables. API key in the Authorization header after OAuth and billing.
  </Card>
</CardGroup>

### MCP

**URL:** `https://app.realie.ai/api/mcp`

```bash theme={null}
claude mcp add --transport http realie https://app.realie.ai/api/mcp
```

```bash theme={null}
npx add-mcp https://app.realie.ai/api/mcp
```

Do not put an API key in the URL or in `mcp.json`. `initialize` and `tools/list` work without a token. `tools/call` returns HTTP 401 with `WWW-Authenticate` pointing at [protected-resource metadata](https://app.realie.ai/.well-known/oauth-protected-resource/mcp).

| Tool | REST |
| - | - |
| `address_lookup` | `GET /api/public/property/address` |
| `property_search` | `GET /api/public/property/search` |
| `parcel_lookup` | `GET /api/public/property/parcelId` |
| `location_search` | `GET /api/public/property/location` |
| `owner_search` | `GET /api/public/property/owner` |
| `comparables` | `GET /api/public/premium/comparables` (premium) |

### CLI

```bash theme={null}
curl -fsSL https://app.realie.ai/api/cli/install | bash
```

```bash theme={null}
realie login
```

```bash theme={null}
realie lookup --address "504 LAVACA ST" --state TX --county TRAVIS --json
```

CI (non-interactive, after a key exists):

```bash theme={null}
realie login --api-key YOUR_API_KEY
```

Or set `REALIE_API_KEY`.

### REST API

Base: `https://app.realie.ai/api`

```bash theme={null}
curl -H "Authorization: YOUR_API_KEY" \
  "https://app.realie.ai/api/public/property/address?address=504%20LAVACA%20ST&state=TX"
```

OpenAPI: [openapi.json](/api-reference/v3/openapi.json)

## Machine-readable resources

* [Homepage agents.md](https://www.realie.ai/agents.md)
* [auth.md](https://www.realie.ai/auth.md)
* [This page as Markdown](/agents.md)
* [Docs llms.txt](https://docs.realie.ai/llms.txt)
* [Site llms.txt](https://www.realie.ai/llms.txt)
* [Agent skill](https://docs.realie.ai/.well-known/agent-skills/realie/skill.md)
* [MCP server card](https://app.realie.ai/api/mcp/server-card)
* [OAuth protected resource](https://app.realie.ai/.well-known/oauth-protected-resource/mcp)

<Tip>
  Prefer this page and [auth.md](https://www.realie.ai/auth.md) for OAuth URLs. The generated skill may still mention the docs MCP until Mintlify rebuilds it.
</Tip>

## FAQ

### Account and OAuth

<AccordionGroup>
  <Accordion title="Can an agent create an account and sign in with OAuth?">
    Yes. Add `https://app.realie.ai/api/mcp` or run `realie login`. Complete Clerk sign-up or sign-in in the browser. New accounts then add a payment method in [Billing](https://app.realie.ai/billing/). OAuth does not mint an API key; billing does.
  </Accordion>

  <Accordion title="Should I register an OAuth app in the Clerk dashboard?">
    No. Hosts read [protected-resource metadata](https://app.realie.ai/.well-known/oauth-protected-resource/mcp), then Realie's [authorization server metadata](https://app.realie.ai/.well-known/oauth-authorization-server), and register themselves (DCR). Creating a client at clerk.com is the wrong path and will not work.
  </Accordion>

  <Accordion title="Does OAuth mint an API key?">
    No. OAuth identifies the Clerk user. MCP `tools/call` and the CLI map that user to the API key already on the Realie billing record. REST and CI still send `Authorization: YOUR_API_KEY`.
  </Accordion>

  <Accordion title="Why do I still need billing after OAuth?">
    Property calls spend tokens on a billed account. A Clerk session without a payment method can list tools and still fail `tools/call` or `realie lookup`. Add a card in [Billing](https://app.realie.ai/billing/). See the [API FAQ](/api-reference/faq) for invoice recovery.
  </Accordion>

  <Accordion title="How do new accounts differ from existing ones?">
    The Clerk window creates the user if they do not exist. Existing Realie users sign in to the same account. New users still need a payment method before property calls succeed. Existing billed users can call tools as soon as OAuth completes.
  </Accordion>

  <Accordion title="What does realie login store?">
    The same Clerk window as MCP, then the CLI stores the existing API key in `~/.realie/config.json`. It does not persist the Clerk access token. MCP hosts keep the Clerk token themselves.
  </Accordion>
</AccordionGroup>

### MCP, CLI, and REST

<AccordionGroup>
  <Accordion title="Should my agent use MCP, CLI, or REST?">
    MCP when the IDE or harness speaks Model Context Protocol (OAuth, no API key in the config). CLI for terminal and shell workflows (prefer `--json`). REST when you are building an app or need full control over requests and pagination.
  </Accordion>

  <Accordion title="Should I put an API key in mcp.json or the MCP URL?">
    No. Add only `https://app.realie.ai/api/mcp`. An API key in the URL or config is the docs-MCP pattern and is wrong for product data. If a host supports a custom header, `Authorization: Bearer YOUR_API_KEY` still works, but OAuth is the path for a new session.
  </Accordion>

  <Accordion title="What is https://docs.realie.ai/mcp?">
    Mintlify's documentation-search MCP. Auth is none. It cannot look up parcels, owners, or comparables. Property data is `https://app.realie.ai/api/mcp`.
  </Accordion>

  <Accordion title="Why does tools/call return 401?">
    Expected before OAuth. `initialize` and `tools/list` are unauthenticated. `tools/call` returns HTTP 401 with `WWW-Authenticate` pointing at the protected-resource metadata. Complete Clerk consent, then retry. A 401 after a finished login usually means the host is not sending the access token.
  </Accordion>

  <Accordion title="Does MCP search return real property records?">
    Yes. Each tool wraps the matching public REST handler (`property_search` → `GET /api/public/property/search`, and so on). Successful tool results contain live parcel data. Check `isError` for lookup or validation failures, which can still arrive with HTTP `200`.
  </Accordion>

  <Accordion title="How do I authenticate in CI?">
    Do not run interactive `realie login`. After a key exists, use `realie login --api-key YOUR_API_KEY` or `REALIE_API_KEY`. REST: `Authorization: YOUR_API_KEY`.
  </Accordion>
</AccordionGroup>

### Billing and errors

<AccordionGroup>
  <Accordion title="Why do I get HTTP 403 after OAuth succeeded?">
    The Clerk user is signed in, but the Realie account is blocked for billing: unpaid invoices, inactive subscription, missing or unverified card, or overage cap. Read `error.message` in the MCP JSON-RPC response. REST API denials instead include `code` and `action` fields. Recovery: [Billing](https://app.realie.ai/billing) and the [API FAQ](/api-reference/faq). Denied `403` requests do not spend tokens.
  </Accordion>

  <Accordion title="Why do I see a $0.50 charge when I add a card?">
    Temporary card verification hold, not a charge. It is released immediately. Details: [API FAQ](/api-reference/faq).
  </Accordion>

  <Accordion title="Do MCP calls spend tokens?">
    Yes. A successful property `tools/call` (`200`) spends one token, same as the REST endpoint it wraps. `401`, `403`, and empty `404` lookups do not. See [What is a token?](/api-reference/pricing#what-is-a-token).
  </Accordion>
</AccordionGroup>

### Docs and discovery

<AccordionGroup>
  <Accordion title="Where should agents read documentation?">
    Start with [auth.md](https://www.realie.ai/auth.md), then [agents.md](https://www.realie.ai/agents.md) or this page as [Markdown](/agents.md). Full docs index: [llms.txt](https://docs.realie.ai/llms.txt). Individual docs pages are also available as Markdown (append `.md` to the URL).
  </Accordion>

  <Accordion title="Is there an agent skill for Realie?">
    Yes. Docs publish a skill at [/.well-known/agent-skills/realie/skill.md](https://docs.realie.ai/.well-known/agent-skills/realie/skill.md). Prefer this page and [auth.md](https://www.realie.ai/auth.md) for OAuth URLs if the skill still mentions the docs MCP.
  </Accordion>

  <Accordion title="What is the difference between this page, the homepage, and agents.md?">
    [www.realie.ai/agents](https://www.realie.ai/agents) is the marketing hub. This page is the same setup inside docs, with the extended FAQ. [agents.md](https://www.realie.ai/agents.md) is that hub as clean Markdown for agents that prefer not to parse HTML.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.