Using Datafiniti's MCP Server

The Datafiniti MCP server lets any MCP-aware client — Claude, ChatGPT, Codex, Cursor, or an agent framework — query Datafiniti's product, business, property, and people data directly. It's one of several ways to use Datafiniti with AI (see the Overview); this one is best when you want an assistant or agent to run queries on its own rather than just help you write them.

MCP and REST return the same data and enforce the same permissions and credit rules, so anything you can do against the REST API you can do here.

When to use MCP

Use the MCP server when:

• Your client supports MCP natively and you want it to execute searches and downloads without a human relaying results.
• You're building an agent that goes from a natural-language goal to a structured data pull in one flow.

If you'd rather have an assistant help you build a query that you run yourself, you don't need MCP at all — see Claude or Other LLMs.

Quickstart

The fastest path to confirming the server works is a single df_count, which returns a match count, spends no credits, and needs no LLM.

1. Get your API token from the Datafiniti Web Portal.
2. Register the server with your client (see Client setup below), or hit it directly to smoke-test (see Verify the connection).
3. Call df_count with a data type and a query:

{
  "data_type": "property",
  "query": "country:US AND province:TX"
}

A count comes back with no records and no credit cost — enough to confirm auth and connectivity before you involve a model.

Authentication

The MCP server uses the same bearer token as REST — there's no separate MCP credential. Get your token from the Datafiniti Web Portal.

The token authenticates the session and determines your field access and credit accounting, exactly as it does for a REST call.

Client setup

The server is mounted at:

https://api.datafiniti.co/v4/mcp

It uses the Streamable HTTP transport. How you register it depends on your client. In each snippet below, set DATAFINITI_API_TOKEN in your environment first.

Claude Code

claude mcp add --transport http datafiniti https://api.datafiniti.co/v4/mcp \
  --header "Authorization: Bearer $DATAFINITI_API_TOKEN"

Cursor / VS Code / Codex / generic**mcpServers**** config**

Most config-file clients accept a mcpServers block. Add:

{
  "mcpServers": {
    "datafiniti": {
      "type": "http",
      "url": "https://api.datafiniti.co/v4/mcp",
      "headers": {
        "Authorization": "Bearer ${DATAFINITI_API_TOKEN}"
      }
    }
  }
}

Client config keys and file locations vary (for example .cursor/mcp.json, .vscode/mcp.json, or a Codex config file). Use your client's documented location for the mcpServers block above; if a field is off, the client will surface a config error you can correct.

Some clients (including claude.ai's custom connectors) don't let you set an Authorization header directly — see the Claude page for that flow. For header-only auth in a client that lacks header support, you can bridge with mcp-remote:

{
  "mcpServers": {
    "datafiniti": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.datafiniti.co/v4/mcp",
        "--header",
        "Authorization: Bearer ${DATAFINITI_API_TOKEN}"
      ]
    }
  }
}

claude.ai uses OAuth, not a pasted header

The instructions above are for clients that support a static bearer header (Claude Code, Claude Desktop via config, Cursor, and similar). Connecting from claude.ai uses an OAuth sign-in flow instead — you won't paste a token. See the Claude page.

Verify the connection

Before involving an LLM, confirm the server responds to your token. Streamable HTTP expects both JSON and event-stream in the Accept header.

curl -sS https://api.datafiniti.co/v4/mcp \
  -H "Authorization: Bearer $DATAFINITI_API_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A successful call returns the list of tools. You can also point the MCP Inspector at the server for an interactive check:

npx @modelcontextprotocol/inspector

The server requires bearer-token authentication on every request, including the smoke test above — an unauthenticated call is rejected.

Tools

Every tool takes a data_type parameter naming the data type — property, people, product, or business — which is how a tool call picks the dataset. (REST uses separate endpoints; MCP folds them into one tool set selected by data_type.)

Choosing a tool

Use df_count to size a result set before spending credits, df_search for small or targeted pulls (up to 50 records), and df_start_download when a use case's scope implies many records.

Tool reference

Every tool that reads data takes a data_type parameter — property, people, product, or business — which selects the dataset.

df_count

Returns { "num_found": <int> }. No credit cost.

df_search

Returns { "num_found", "total_cost", "records": [...] } — the same shape as a REST search.

num_records************************ defaults to 1

If you don't set num_records, df_search returns a single record. Set it explicitly (up to 50) when you want more.

df_start_download

Returns a JSON download response object describing the newly created download, including its download id. Poll that id with df_download_status.

df_download_status

Returns the download's status — one of queued, running, completed, or cancelled — and, once completed, links to the result files. No credit cost.

df_get_record

Retrieves a single record by its Datafiniti id. Costs 1 credit per record.

df_get_schema

Returns the field-name-to-type map an agent needs to write a valid query. No credit cost. See also the schema and possible-values links under Querying.

Run a query

Call df_search with a data type, a query string, and a record count:

{
  "data_type": "property",
  "query": "country:US AND propertyType:"Single Family Dwelling"",
  "num_records": 10
}

The response contains num_found, total_cost, and a records array — the same shape a REST search returns.

Querying

The server exposes Datafiniti's full query syntax to the client: boolean operators, negation, parentheses, nested-field dot notation, ranges, and the compound {} syntax for matching multiple sub-field requirements within a single nested object.

Construction guides:

Schemas

(field names and types — pair these with df_get_schema):

Possible values

Possible values pages for each data type. (People data has no possible-values page):

Views

The view parameter on df_search and df_start_download controls which fields come back. Pass a JSON array — either of field-name strings, or of {"name": "<field>"} key/value objects. Nested sub-fields use dot notation in the field name (for example, "descriptions.value").

Fuzzy match scope

fuzzy_match controls fuzzy-matching on the address field and defaults to 'on'. It is valid only for the address field within property and business data. It has no effect on people or product queries.

Paging past 50 records

df_search returns at most 50 records per call, and a client can page through results up to the total found by the query, to a ceiling of 10,000 records. To retrieve more than 10,000 records — or to pull a large set in one operation rather than paging — use df_start_download instead.

Tips for agents

Models predictably make a few mistakes against these schemas. If you're writing a system prompt or tool description, call these out:

• Confirm field names with df_get_schema (or the schema pages) before building a query, rather than guessing by analogy.
• Property status is split by side. Sale-side values live on mostRecentStatus; rental-side values on mostRecentRentalStatus. A rental value queried against the sale field returns zero results.
• Enum fields need exact values from the Possible Values pages — not paraphrases.
• Count before you search or download to size a result set without spending credits.

Credits

MCP tools spend credits on the same basis as REST, using your token's account.

• df_count, df_download_status, df_get_schema — free.
• df_search — charged per record returned.
• df_start_download — charged per record requested and found. If fewer records match than the query could return, you're charged only for the records actually found.
• df_get_record — 1 credit per record.

To keep spend predictable: run df_count first, keep num_records low while iterating (it defaults to 1), and reserve df_start_download for when you actually need the full set. If a call returns credit_limit_exceeded, your account has hit its credit limit and the query was not fulfilled.

Limits

• Records per**df_search**** call:** 50.
• Records via paging (df_search): up to 10,000 total for a query. Beyond that, use df_start_download.
• Records per download (df_start_download): governed by your subscription plan, not a fixed MCP cap.
• Download link lifetime: 7 days.
• Rate limiting: Datafiniti reserves the right to restrict, limit, throttle, or suspend API access at its discretion, and to protect infrastructure from unreasonable load, as described in the API Usage section of the Terms of Use. Don't attempt to circumvent throttling or suspension (for example, by rotating IPs) — that's a Terms violation. Build clients to back off and retry rather than hammer the endpoint.

Errors

When a call fails, the server returns a structured error object in the response body rather than a bare status code or loose string:

{
  "code": "invalid_query",
  "message": "…",
  "field": "query"
}

Branch on the stable code rather than string-matching message.

Prompts

The server ships a library of prompts, each converting a docs.datafiniti.co use-case guide into a ready-to-run query template. A prompt doesn't execute anything itself — it returns a built query and tells the client which tool to run next (df_search for a small, targeted result set, or df_start_download when the guide's scope implies many records).

In many clients, prompts surface as slash commands or a prompt picker. Where a prompt argument has a small, verified value set (such as a property status), it's defined as an enum, so clients that render prompt forms show a dropdown instead of a free-text box.

The prompts available for each data type are listed on that data type's page: Property · People · Product · Business.

Worked examples

For full, end-to-end walkthroughs per data type — count, search, a data-type-specific technique, and a download — see:

Property Examples · People Examples · Product Examples · Business Examples

Troubleshooting

• tools/list**************** returns nothing / connection refused — re-check the URL and that your Accept header includes both application/json and text/event-stream. Try the cURL smoke test.
• 401 / auth error — confirm DATAFINITI_API_TOKEN is set and current; it regenerates on password change.
• A client won't accept the**Authorization**** header** — use the mcp-remote bridge, or the OAuth flow on the Claude page.
• Queries return zero unexpectedly — a zero-result query isn't an error; adjust it. Check for a rental status queried against the sale field, an enum value that isn't in Possible Values, or a field name that doesn't match the schema. Run df_count to test changes for free.

Next steps

• Test the connection by hand: Verify the connection.
• Per-client details: Claude · ChatGPT / Codex · Postman.
• Data-type walkthroughs: the "…with AI" and Examples pages above.