MCP ServerPeople Data with an MCP Server

People Data with an MCP Server

Worked examples of querying Datafiniti people data through the MCP server — counting, searching, downloading, and running a people prompt.

MCP Server — People Examples

This guide walks through end-to-end examples of using the MCP Server against people data. It assumes you've already connected a client and authenticated — see the MCP Server guide for setup, transport, and the full tool reference.

Every example here uses the same tools (df_count, df_search, df_start_download, df_download_status) and the same query syntax as the other data types; what changes are the fields and views specific to people records. For the underlying reference, see the People Data Schema and Constructing People Queries.

The goal

Say we want people with a "Chief Executive Officer" title in the US — first to size the set, then to pull a targeted sample with contact fields, and finally to export the full set.

1. Size the result set with df_count

Every tool call names the dataset with a data_type parameter — here "data_type": "people". This is how the server knows to search people records rather than the other data types. The accepted values are property, people, product, and business.

Start with a count. It returns no records and costs no credits, so it's the cheapest way to confirm a query is scoped correctly before spending anything.

{
  "query": "country:US AND title:"Chief Executive Officer"",
  "data_type": "people"
}

A response tells you how many records match:

{
  "num_found": 41922
}

Sanity-check the count

A count of 0 is a valid result — no records matched — not an error. If you expected matches, check field names against the schema and confirm any exact-match values, then adjust. A count is the cheapest way to test changes before spending credits.

Now retrieve a handful of records. df_search returns up to 50 per call and charges credits identically to REST /search.

{
  "query": "country:US AND title:"Chief Executive Officer"",
  "data_type": "people",
  "num_records": 5,
  "view": ["name", "title", "company", "emails", "phones", "city", "province"]
}

The response has the same shape as a REST search — num_found, total_cost, and a records array:

{
  "num_found": 41922,
  "total_cost": 5,
  "records": [
    {
      "name": "…",
      "title": "Chief Executive Officer",
      "company": "…",
      "emails": ["…"],
      "phones": ["…"],
      "city": "…",
      "province": "…"
    }
  ]
}

Quoting exact-match values

Exact-match values use double quotes in the query: title:"Chief Executive Officer". That's query syntax, not JSON. A client serializes tool arguments for you; only when you hand-write the JSON do you escape the inner quotes as \" (as shown above). Avoid double-escaping (\\").

3. Narrow with additional fields

People queries combine field conditions with boolean operators, negation, and parentheses. To narrow the set to CEOs at companies in a particular city, add conditions:

{
  "query": "country:US AND title:"Chief Executive Officer" AND city:Chicago",
  "data_type": "people"
}

To match more than one title, group alternatives with parentheses:

{
  "query": "country:US AND title:("Chief Executive Officer" OR "Chief Operating Officer")",
  "data_type": "people"
}

4. Choose fields with a view

The view parameter controls which people fields come back. A string names a default or saved view; an array is an ad-hoc view built from {"name": "<field>"} objects, with nested sub-fields expressed as dot notation in the name.

The array form in step 2 is shorthand for the object form:

{
  "view": [
    {"name": "name"},
    {"name": "title"},
    {"name": "emails"},
    {"name": "phones"}
  ]
}

For the available saved views, see Available Views for People Data.

5. Export the full set with df_start_download

When you want all matching records rather than a sample, start an asynchronous download. The number of records a download can return is governed by your Datafiniti subscription plan.

{
  "query": "country:US AND title:"Chief Executive Officer"",
  "data_type": "people",
  "format": "JSON",
  "view": ["name", "title", "company", "emails", "phones"]
}

This returns a download identifier. Poll it with df_download_status:

{
  "download_id": "…"
}

Once the status comes back complete, the response includes links to the result files.

6. Run a people prompt

Prompts turn a people use-case guide into a ready-to-run query template. For example, the gather_people_contact_info prompt builds a query focused on contact fields, and link_people_to_property assembles the cross-reference from a person to their associated property records — then each tells the client whether to call df_search or df_start_download next.

For the full list of people prompts, see People Data with AI.

Next steps

Was this page helpful?