MCP server
Circlemark as a set of tools
Circlemark runs a remote Model Context Protocol (MCP) server. Any MCP client — Claude, ChatGPT, an agent framework, your own code — connects to one endpoint, signs the user in on circlemark.ai, and calls ten tools under that user’s own seat: the same plan, daily meters and credit ledger as the web app. This page is the reference; the host guides are Claude and ChatGPT.
Connect
| Endpoint | https://circlemark.ai/api/mcp |
|---|---|
| Transport | Streamable HTTP (MCP). No SSE-only mode, no stdio. |
| Authentication | OAuth 2.1 with PKCE (S256). Every call needs a bearer token; there is no API-key mode. |
| Client registration | Dynamic (RFC 7591). A client registers itself on first connect — there is no client ID or secret to paste. |
| Discovery | Protected-resource metadata (RFC 9728) at /.well-known/oauth-protected-resource; authorization-server metadata (RFC 8414) at /.well-known/oauth-authorization-server. A 401 carries WWW-Authenticate: Bearer resource_metadata=… pointing at the first. |
| Scopes | openid, email — the seat's identity. Nothing else is granted and nothing is written back to the host. |
| Sign-in | On circlemark.ai, with a consent screen listing what the client may access. The host never sees a password. Any account works, free seats included. |
In a client that takes a custom connector, paste the endpoint and choose “authentication required” with automatic client registration. In your own code, point an MCP client at the endpoint with an OAuth provider that follows the discovery documents above; the first request returns 401 with the metadata location, the client registers, the user signs in, and every later call carries the token.
Tools
Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) and names its own cost in its description, so a host can gate the writes or ask before spending. The server’s instructions, read at connect time, carry the provenance rules below.
search_loans — Search recorded commercial mortgages.
- Inputs. metroId or county ids; maturity window (dueFromM/dueToM months from today, or dueFrom/dueTo dates); amountMin/Max; propertyType, propertySubtype; lenderType, lender; borrower, borrowerKey, borrowerSegment, borrowerList; address or q; unitsMin/Max, lotAcresMin/Max, buildingSqftMin/Max, parcelsMin; coop and rentRegulated (NYC); activeOnly, distressedOnly, statedOnly; score, sort, sortDir, page, pageSize (≤ 50).
- Returns. total, page, pageSize and rows — one row per property × loan: propertyId, loanId, address, county, property type with its basis, sizes, borrower with its segment and basis, lender and lenderType, amount, originated, statedMaturity / estimatedMaturity / nextResetDate with maturityBasis, rate terms as stated, prepay dates, LTV, prospect score, distress signals, loan status, purpose, document number.
- Access. read-only — reads Circlemark's own database; the only write is the usage meter.
- Cost. Free; one search on the plan's daily meter. An empty page is not counted.
get_property — One property and every loan recorded on it.
- Inputs. propertyId (from search_loans, list_watchlist or get_lender) or loanId.
- Returns. The assessor's record (year built, units, building and lot size, assessed value, owner of record and mailing address, class, sales), every mortgage with status (active, satisfied, consolidated, foreclosed), terms, provenance, distress signals cited to instruments, facility badges, the other properties on the loan, source links, and the COUNT and sources of the people on record — never the people themselves.
- Access. read-only — reads Circlemark's own database; the only write is the usage meter.
- Cost. Free; one property view on the daily meter.
find_lenders — Institutions that closed loans like this one, from recorded instruments.
- Inputs. metroId or county; propertyType; amountMin/Max (a size band); sort volume or recent; limit (≤ 50).
- Returns. Ranked institutions with closings, closingsInCounty, lastDeal and groupKey; comparableLoans and coverage size the claim. stated and contacts are always null — the record holds no credit box and no originator names.
- Access. read-only — reads Circlemark's own database; the only write is the usage meter.
- Cost. Free; counts as a search.
get_lender — One lender's recorded footprint across every market.
- Inputs. groupKey (from find_lenders) or a name; an ambiguous name returns candidates.
- Returns. Closings by county, property type and quarter over 36 months, size band, all-time count, recorded spellings, sibling desks, last 20 closings. No people.
- Access. read-only — reads Circlemark's own database; the only write is the usage meter.
- Cost. Free; counts as a property view.
reveal_contacts — The people behind a property's leading loan.
- Inputs. propertyId; optionally personKey and want (email) for one more principal of an unlocked property.
- Returns. Principals from the public record, each row citing its source and tier, with work emails from vendor lookups; pending flags where a vendor answers later. No phone numbers.
- Access. sensitive write — spends credits from the seat's allowance and queries third-party contact-data vendors; the cost is in the tool description so a host can ask first.
- Cost. 1 credit from the seat's allowance, stated in the tool description. Free when the property was already unlocked (served from the stored answer). A failed unlock is refunded.
find_phone — A direct phone for one revealed person.
- Inputs. propertyId and personKey from a prior reveal_contacts.
- Returns. The number, or phoneOutcome: none, unavailable (nothing was searched), error.
- Access. sensitive write — spends credits from the seat's allowance and queries third-party contact-data vendors; the cost is in the tool description so a host can ask first.
- Cost. 5 credits held, settled only when a number lands; refunded otherwise. Never runs unasked.
add_to_watchlist — Pin a property to the seat's watchlist.
- Inputs. propertyId.
- Returns. The pinned id. Pinning twice leaves the same state.
- Access. write — writes only to the seat's own rows in Circlemark's database.
- Cost. Free; capped per plan.
remove_from_watchlist — Unpin a property.
- Inputs. propertyId.
- Returns. Confirmation. Paid reveals on the property are kept.
- Access. destructive — removes something the user chose; nothing else is affected.
- Cost. Free.
list_watchlist — The watchlist, newest pin first.
- Inputs. None.
- Returns. Property ids; fetch each with get_property.
- Access. read-only — reads Circlemark's own database; the only write is the usage meter.
- Cost. Free.
get_credit_balance — Reveal-credit allowance and usage.
- Inputs. None.
- Returns. limit, used, remaining, resets (monthly on a paid seat, never on the free seat), plan.
- Access. read-only — reads Circlemark's own database; the only write is the usage meter.
- Cost. Free.
Provenance fields
Every modelled value travels with the field that says so. A client that prints these without their basis is presenting an estimate as a fact, the one thing the methodology forbids.
maturityBasis | stated = read off the recorded instrument; stated_term = the document states a term, the date is arithmetic from origination; assumed = modelled from origination and a typical term (present as ≈); reset = a stated rate-change date from the recorded rider, the event on 30-year paper, never a maturity; none = a 1–4 family loan with nothing stated, no date is printed. |
|---|---|
propertyTypeBasis | recorded = the appraisal district's classification; estimated = Circlemark's read from the businesses on record, the district's description or the building (Denton and Tarrant publish no building class). |
borrowerSegmentBasis | registered = the NAICS the entity filed with the Texas Comptroller; estimated = a word in the name. Absent = the record does not say, never "not a builder". |
rentRegulation (NYC) | registered = stabilized units on the Department of Finance tax bill, with the count; likely = Circlemark's presumption from age and size; absent = no test fired, which includes buildings that cannot be tested. |
prepayOpenDate / prepayLockoutEnd | Open at par, versus the day defeasance or yield-maintenance prepayment becomes permitted. Different days; never read the lockout end as open. |
interestRate / rateIndex / rateMargin / rateCaps | As the document states them. On a loan with a reset the rate is the initial fixed-period rate; the all-in rate after reset is never computed. |
One loan, many rows | A loan on several parcels repeats with one loanId, one documentNumber and the same amount on every row. One debt, never summed. Facility members (facilityKind) likewise. |
Limits, errors, money
| Searches and views | Paid seats: 150 a day and 2,000 a month, counted separately for searches and for property or lender views. The free seat spends 60 of each for the life of the seat, under the same day cap. The meter counts pages served — an empty page is given back. |
|---|---|
| Reveal credits | Free seat: 10, once, never renewing. Data only: 100 a month. Data + Outreach: 300 a month. Allowances renew on the 1st. Held and settled around the vendor call in an append-only ledger. |
| Burst | A short per-minute cap on reveals; the refusal says to wait a minute. |
| Refusals | A usage-cap refusal names the cap and links plan information; it never sells. A tool error returns one line of text — never a stack trace or SQL. |
| Expired token | A 401 with WWW-Authenticate and the MCP www_authenticate meta, so a host re-authorizes instead of failing. |
| Nothing is sold in the chat | Reveals spend the allowance already included in the user's Circlemark plan. Plans are bought on circlemark.ai only. |
Plan allowances are on the pricing page; how credits are held and settled is in the methodology.
Coverage
New York City (four ACRIS boroughs), Dallas–Fort Worth (Dallas, Tarrant, Collin, Denton), Houston (Harris), Austin (Travis), San Antonio (Bexar), Jersey City (Hudson), Cleveland (Cuyahoga), Columbus (Franklin), Detroit (Wayne), and Memphis (Shelby). Every live county answers through the same tools; a search for a county outside coverage returns no rows and says so. New metros appear as their backfills complete.
Data handling
- What the server receives. The seat’s identity (openid, email) from the sign-in and the tool calls the host sends. Nothing is read from the host, and nothing is written back to it.
- Who else receives anything. On
reveal_contactsandfind_phoneonly, the name and firm of a borrower principal from the public record go to the contact-data vendors that resolve emails and phones. The Circlemark user’s own identity never does. - Retention and deletion. As the privacy policy states. Reveals and credit entries are the user’s own account records.
- Revoke. Disconnect in the host, or from the Circlemark account page — either ends access at once; the token is scoped to the seat and revocable on its own.
Support
founders@circlemark.ai for a connector that misbehaves, a directory review, or a client that needs something the server does not yet do. Terms · Privacy.