MCP Server

DealMachine runs a remote MCP server at:

1https://mcp.dealmachine.com

Use it when an AI agent needs live property intelligence, owner contact data, comps, property and people search, exports, account usage, or location lookup.

Service health and source version

Unauthenticated GET /health returns the MCP server's status and build identity:

1234567{
  "name": "DealMachine MCP Server",
  "version": "0.3.0",
  "status": "ok",
  "sourceCommit": "1234567890abcdef1234567890abcdef12345678",
  "docs": "https://api.docs.dealmachine.com"
}

sourceCommit is the full Git commit embedded in the deployed Worker. Runtime settings cannot replace it, and the response has Cache-Control: no-store. Local builds without a deployment receipt return null; older deployments may omit the field. A check requiring an exact build must reject missing, null or mismatched receipts.

This identifies the MCP Worker, separately from the API's build identity. A healthy response does not prove authenticated MCP Tool access, the API dependency's version, real data or credit behavior.

You can connect to discover signup and plans before you have an account. Protected tools prompt you to link a DealMachine account through OAuth. The sign-in page also offers signup and returns to your connection after you finish.

MCP Tool	What it does
`dealmachine_signup`	Returns the secure browser signup link. No account or payment required.
`dealmachine_plans`	Reads live prices, included credits, plan benefits and free capabilities. Connected customers see their workspace's prices.
`dealmachine_account`	Reads your current plan and available data credits. Free accounts can use it.
`dealmachine_checkout`	Creates a Stripe checkout link only with `confirmed=true` after your explicit approval of the exact plan, recurring price, interval and quantity.

A free account can discover fields and filters, count properties and people, and request supported cost estimates. Counts and estimates spend no data credits. Enrichment and returning records require paid access. The tool response states the live allowance; agents must not invent starter credits or prices.

When enrichment returns subscription_required or insufficient_credits, the agent explains the refusal and shows options with dealmachine_plans. It asks before creating checkout. Declining keeps you on free access. You enter payment details only on Stripe's page, where Stripe Link may be available depending on the merchant's settings. Creating a checkout link does not charge you or activate access.

After payment, the agent checks dealmachine_account and dealmachine_usage. It retries approved paid work only when the subscription and credit balance permit it. A pending, canceled or failed payment does not unlock enrichment.

Authentication

For protected tools, MCP clients can authenticate with a DealMachine API key in the Authorization header:

1Authorization: Bearer dm_sk_live_xxx

Get an API key from Developer Settings. OAuth-aware MCP clients can also discover authorization metadata from:

1https://mcp.dealmachine.com/.well-known/oauth-protected-resource

Connect Claude Code

12claude mcp add dealmachine --transport http https://mcp.dealmachine.com \
  --header "Authorization: Bearer dm_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Connect Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

12345678910111213{
  "mcpServers": {
    "dealmachine": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.dealmachine.com",
        "--header",
        "Authorization: Bearer dm_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Connect Cursor

Add this to .cursor/mcp.json:

12345678910111213{
  "mcpServers": {
    "dealmachine": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.dealmachine.com",
        "--header",
        "Authorization: Bearer dm_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Direct HTTP Check

1234curl -X POST https://mcp.dealmachine.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dm_sk_live_YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

MCP Tools

DealMachine exposes named MCP Tools for common workflows and three tools for discovering and executing the wider public API.

Use dealmachine_enrich_name for a specific person by name. Use dealmachine_people_search only for audiences defined by filters and locations. The people search MCP Tool does not accept a person's name as a filter.

Public API operations on demand

Three MCP Tools give access to 127 published API operations without placing every operation's schema in the initial tool list:

MCP Tool	Purpose
`dealmachine_operations_search`	Search by words, category or route. Omit `query` to browse; use `limit` (1–25, default 10) and the returned `next_offset` to paginate.
`dealmachine_operation_schema`	Load one operation's published parameters, request body, response schemas, credit guidance and referenced definitions.
`dealmachine_operation_execute`	Call that operation using the connected account. Pass `operation`, `path`, `query`, `body` and, when required, `confirmed`.

Operation IDs are the exact method and route returned by search, including parameter placeholders. They are not URLs. For example:

1{"query":"create task"}

Pass that to dealmachine_operations_search, then load its schema:

1{"operation":"POST /v1/tasks"}

After the user approves creating the task, call dealmachine_operation_execute:

1{"operation":"POST /v1/tasks","body":{"title":"Call the property owner"},"confirmed":true}

Read tasks using the same execution tool:

1{"operation":"GET /v1/tasks","query":{"page":1,"per_page":10}}

The catalog covers tasks, address autocomplete and validation, activity, exports, full list management, prospect notes/files/photos/tags, webhook delivery management, driving, mail designs/settings/return addresses/wallets, account and subscription operations, and property/people data. Existing named MCP Tools remain available.

All non-GET operations and property/person GET lookups require confirmed: true. This conservative rule also includes free POST queries. Check the operation schema for actual costs, use estimates and counts, and obtain user approval before changing records, consuming credits, charging a saved payment method, sending mail, or sending webhook events. Confirmation records the agent's approval check; the API still enforces account permissions, plans, validation, pagination and billing. Do not automatically retry writes after a timeout or uncertain result.

The gateway accepts only catalog operations and published path/query parameter names. It forwards the JSON body to the API for validation and preserves API error status, code, category and retryability. Large results use the existing MCP response limit; request smaller pages or fewer fields if response_truncated is returned. Large person IDs should be decimal strings to preserve precision.

File downloads return a short-lived signed URL with redirect=false. Use that URL outside MCP to download bytes. File uploads return an upload URL; transfer the bytes outside MCP, then register the file through the published operation. MCP does not read or write local files. Never send the DealMachine bearer token to a signed URL.

Signup, device authorization, OAuth authorize/token/revoke, local CLI login/logout, configuration and local development commands are outside the operation catalog. Connection setup remains in the client. Private API routes are not exposed by this catalog. Search results identify the pinned public API source revision, which is updated through a reviewed MCP release.

Enrichment

MCP Tool	Description	Cost
`dealmachine_enrich_address`	Look up a property by street address.	1 property data credit per match
`dealmachine_enrich_latlng`	Look up the closest property by GPS coordinates.	1 property data credit per match
`dealmachine_enrich_apn`	Look up a property by Assessor's Parcel Number.	1 property data credit per match
`dealmachine_enrich_email`	Look up a person by email address.	1 people data credit per matched person
`dealmachine_enrich_phone`	Look up a person by phone number.	1 people data credit per matched person
`dealmachine_enrich_name`	Look up people by name. Always narrow with location.	Free with `estimate_cost=true`. Otherwise 1 people data credit per person returned

Search, Export, Comps, And Locations

MCP Tool	Description	Cost
`dealmachine_property_search`	Search properties by location and filters.	Credit-consuming unless `estimate_cost=true`
`dealmachine_property_count`	Count matching properties before a search or export.	Free
`dealmachine_property_export`	Export matching property-owner contacts as CSV.	Credit-consuming export
`dealmachine_property_get`	Fetch one property by ID.	1 property data credit unless `enrich=false`
`dealmachine_property_get_many`	Fetch up to 25 properties by ID.	1 property data credit per property unless deduped
`dealmachine_comps`	Find comparable sales and active listings for subject properties.	1 property data credit per subject found
`dealmachine_people_search`	Search people by location and filters.	Credit-consuming unless `estimate_cost=true`
`dealmachine_people_count`	Count matching people before a search or export.	Free
`dealmachine_people_get`	Fetch one person by ID.	Credit-consuming unless deduped
`dealmachine_people_get_many`	Fetch up to 25 people by ID.	Credit-consuming unless deduped
`dealmachine_location_search`	Look up FIPS codes, ZIP codes, and location IDs by name.	Free

Lists and prospects

MCP Tool	Description	Cost
`dealmachine_list_create`	Create a list, optionally pre-filled with up to 250 record IDs. Filed records become prospects unless `add_as_prospects` is false.	Free
`dealmachine_list_add_items`	Add up to 10,000 property or person IDs to a list.	Free
`dealmachine_prospect_add`	Track up to 1,000 records as prospects.	Free
`dealmachine_prospect_get`	One prospect by ID or by the record it tracks.	Free
`dealmachine_prospect_search`	List prospects by lifecycle, source, list, tag, or search words.	Free
`dealmachine_prospect_update`	Move a prospect between active, opportunity, and archived, or star it.	Free
`dealmachine_prospect_note_add`	Add a note to a prospect.	Free
`dealmachine_prospect_tags_set`	Replace the tags on a prospect.	Free
`dealmachine_tags_list`	The prospect tag catalog with usage counts.	Free
`dealmachine_webhook_list`	Outbound webhooks with delivery health, optionally the event catalog.	Free
`dealmachine_webhook_create`	Register an https URL that receives prospect and list events.	Free

Driving

MCP Tool	Description	Cost
`dealmachine_driving_read`	List recorded drives or get one drive with its route, visits, events, and linked Prospects.	Free

Driving uses one compact read-only MCP Tool with list_drives and get_drive operations. Use the Prospect MCP Tools for lifecycle, notes, and tags. Filter dealmachine_prospect_search with source=driving to find Prospects added during drives.

Mail

MCP Tool	Description	Cost
`dealmachine_mail_read`	Read campaigns, recipients, analytics, cost estimates, designs, pricing, or wallet balance. List campaigns that accept properties, and estimate the cost of adding properties.	Free
`dealmachine_mail_campaign_draft`	Create or update a draft, or pause or resume a campaign. Set `accepts_properties: true` on create to keep adding properties after it is sent.	Free
`dealmachine_mail_campaign_send`	Launch a draft campaign.	Wallet dollars based on recipients and steps
`dealmachine_mail_campaign_add_properties`	Add properties to a Ready, Active, or Paused campaign, with the recipient set to the owner or the current resident.	Wallet dollars: pieces going out today now, later pieces as they go out
`dealmachine_mail_campaign_end`	End a Ready, Active, or Paused campaign permanently and stop its unsent mail. A draft cannot be ended.	Free
`dealmachine_mail_campaign_cancel`	Cancel a campaign, kept for existing clients. Ends a started campaign like `dealmachine_mail_campaign_end`, cancels a draft, and returns an ended campaign unchanged.	Free

Campaign status is draft, ready, active, paused, or ended. Use dealmachine_mail_read with search_campaigns and accepting_properties: true to find campaigns that properties can be added to.

Read a campaign's cost estimate and get the user's approval before sending. Before adding properties, the assistant calls dealmachine_mail_read with add_properties_estimate and the property count, tells the user the charge due today and the amount charged later, and adds only after the user approves. Each added property starts at step 1 on its own schedule, and the result lists every skipped property with its reason. Sending, adding properties, ending, and cancelling require confirmed: true.

Discovery And Account

MCP Tool	Description	Cost
`dealmachine_filters`	List available search filters with types, operators, and options.	Free
`dealmachine_fields`	List available result fields.	Free
`dealmachine_usage`	Get credit usage for the current billing cycle.	Free
`dealmachine_whoami`	Check the authenticated account and organization.	Free

Address autocomplete is available through GET /v1/addresses/autocomplete in the operation catalog. Use dealmachine_location_search to normalize a city, county, state, or ZIP, and dealmachine_enrich_address to look up a known property address.

Parameters Added Across MCP Tools

MCP Tools	Parameters and output
`dealmachine_property_get`	Accepts `fields` and `contact_audience`, including `none` for property-only data
Property enrichment tools	Accept `fields` and `contact_audience`, including `none`
Email, phone, and name enrichment	Accept `fields` and return free `property_count` metadata
`dealmachine_people_get` and `dealmachine_people_get_many`	Accept `fields` and `property_limit`, default 20 and max 100

Phone output types use wireless, landline, voip, or unknown. dealmachine_enrich_name estimates include associated property totals and page-aware property credits when both estimate_cost=true and include_properties=true are passed.

Credit-Safe Agent Defaults

Call dealmachine_filters and dealmachine_fields before constructing searches.
Call dealmachine_property_count or dealmachine_people_count before any large search or export.
Call dealmachine_usage before batch work.
Use contact_audience: "none" for property lookup or enrichment when contacts are not needed.
Confirm with the user before exporting or returning a large credit-consuming result set.
Default property exports to owner contact rows unless the user explicitly asks for property-only rows.

Export phone activity

dealmachine_property_export accepts active_phones_only: true to exclude phone numbers with inactive or unknown reported activity. It combines with the existing phone-type and Do Not Call controls.