Connect an agent to the directory

Local businesses in and around Austin, Texas, as MCP tools and a REST API. Every fact carries its source and how sure we are.

Quick start

  1. Create an API key. It is shown once; copy it then.
  2. In Claude Code, add our plugin marketplace and install the plugin. It asks for your key.
  3. Ask Claude a home-service question with a ZIP in Austin.
/plugin marketplace add continuoustech-ai/agent-ready-plugins
/plugin install agent-ready-directory@agent-ready

Get a key

Sign in on the key page with your email (a link or a 6-digit code), accept the terms, and create a key. You can have up to 3 active keys, for example one per machine. A key is shown once: we keep only its hash, so a lost key cannot be shown again. Revoke it and create a new one.

Claude Code plugin

The plugin adds the MCP server and the skill that tells Claude how to use it: which tools to call in what order, to keep the returned order, to quote why and caveats, and never to invent a phone number, price or opening hours.

At install, Claude Code asks for api_key and keeps it in your system's secure storage. Restart Claude Code, then check with /mcp: plugin:agent-ready-directory:agent-ready-directory is connected with 5 tools.

To change the key later (a new key, or the old one was revoked):

/plugin configure agent-ready-directory@agent-ready

Updates: /plugin marketplace update agent-ready, or turn on auto-update for the agent-ready marketplace in /plugin.

Without the plugin, add the server by hand (use one or the other, not both, or the tools show twice):

claude mcp add --transport http agent-ready-directory {API}/mcp --header "X-API-Key: YOUR_KEY"

Troubleshooting

Reference

Everything each call takes and gives back. Leave out an optional parameter you do not have; do not send empty values. Text is trimmed; trade, view and claim accept any case.

MCP

Streamable HTTP, stateless, JSON responses, at {API}/mcp. Send the key as X-API-Key or Authorization: Bearer. Five tools. An error comes back as a tool error reading code: message (codes under Errors).

find_businesses

Ranked business cards. Give at least one of trade, service, zip, city or name; zip or city, not both.

ParameterTypeRequiredDefaultNotes
tradestringoptionalOne of the trades list_services returns
servicestringoptionalA code from list_services, like plumbing.water_heater_repair. Max 60
zipstringoptionalFive digits: the job's ZIP (for a business the person visits, where they come from). Exact matches first, then businesses in nearby ZIPs, closest first (zip_match: nearby)
citystringoptionalA Texas city, like Round Rock: searches all its ZIPs. Max 60
namestringoptionalThe business name or part of it. Max 100
limitintegeroptional51 to 10

Returns {"results": [card, ...], "total", "limit", "offset"}, plus "city": {"name", "zips"} for a city search. The card's fields are under Card.

get_business

ParameterTypeRequiredDefaultNotes
idstringrequiredA business id like b_xxxxxxxx
viewstringoptionalstandardstandard for answering; full adds every fact's sources and conflicts

Returns a profile. For a merged id, the kept business's profile comes back with merged_from set to the id you sent.

get_actions

ParameterTypeRequiredDefaultNotes
idstringrequiredA business id

Returns {"id", "name", "actions": [...], "note"}: how to reach the business (see actions under Profile).

list_services

ParameterTypeRequiredDefaultNotes
tradestringoptionalallOne of the trades list_services returns

Returns {"trades": {"<trade>": {"status", "services": [{"code", "name", "synonyms"}]}}}.

report_issue

The only tool that writes. Use it only when the person says something is wrong; a person checks every report.

ParameterTypeRequiredDefaultNotes
idstringrequiredA business id
claimstringrequiredclosed, moved, wrong_phone, wrong_hours, wrong_website, wrong_address, wrong_services, not_licensed, duplicate, other
fieldstringoptionalThe field that is wrong, like phone. Max 40
detailstringoptionalOne sentence, no personal details. Max 500

Returns {"accepted": true, "message"}. Limit: 10 a minute per key.

REST

Base URL {API}. Send the key in X-API-Key. JSON in and out.

GET /v1/search

The same search as find_businesses, with paging. Give at least one of trade, service, zip, city or q.

ParameterTypeRequiredDefaultNotes
tradestringoptionalOne of the trades list_services returns
servicestringoptionalA service code. Max 60
zipstringoptionalFive digits. Nearby ZIPs too, after the exact matches
citystringoptionalA Texas city; not with zip. Max 60
qstringoptionalPart of the business name. Max 100
limitintegeroptional101 to 50
offsetintegeroptional00 to 1000
curl -s -H "X-API-Key: $KEY" "{API}/v1/search?trade=plumbing&zip=78704&limit=1"
{"results": [{
   "id": "b_ryTsBiT1", "name": "Clarke Kent Plumbing", "trade": "plumbing",
   "why": ["TSBPE license current", "42 permits in the last year", "phone confirmed by 2 sources"],
   "phone": "+15124772200", "zip": "78704", "city": "Austin", "confidence": "high",
   "license_verified": true, "availability_level": 0, "version": 2, "zip_match": "job"}],
 "total": 31, "limit": 1, "offset": 0}

A search with service that finds no business listed for that service answers for the service's trade instead: the answer has "fallback": "trade", and every card's first caveat is not checked for this service: listed for the trade. Not when trade names a different trade than the service.

GET /v1/businesses/{id}

ParameterTypeRequiredDefaultNotes
id (in the path)stringrequiredA business id
viewstringoptionalstandardcard, standard or full

Returns a profile (a card with view=card). A merged id answers 301 to the kept id.

curl -s -H "X-API-Key: $KEY" "{API}/v1/businesses/b_ryTsBiT1"

GET /v1/services

ParameterTypeRequiredDefaultNotes
tradestringoptionalallOne of the trades list_services returns

Returns the same as list_services.

GET /v1/meta

No parameters. Returns {"data_version", "profiles", "fields", "trades", "claims"}: the data's version, how many profiles there are, the field names, the trades and the report claims.

POST /v1/reports

Body fieldTypeRequiredDefaultNotes
businessstringrequiredA business id
claimstringrequiredOne of the claims in /v1/meta
fieldstringoptionalMax 40
detailstringoptionalMax 500

Answers 202 with {"accepted": true, "message"}.

curl -s -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"business":"b_ryTsBiT1","claim":"wrong_phone","field":"phone"}' "{API}/v1/reports"

Card (a search result)

FieldTypeWhenMeaning
idstringalwaysThe business id; use it with get_business
name, tradestringalwaysName and main trade
phonestringif knownE.164, like +15124772200
zip, citystringif knownThe business's own ZIP and city
whystring[]alwaysWhy it was picked: quote these
caveatsstring[]if anyWeak spots, like license not verified: always pass them on
confidencestringalwayshigh, medium or low
license_verifiedbooleanalwaysThe only basis for saying licensed
availability_levelintegeralways0: no booking page known; 1: a booking link (an action book_online). Never a free time slot
zip_matchstringwith zip or cityjob: permitted work in that ZIP in the last year; served: its website lists the area; likely: its own address is in that ZIP; nearby: its own address is in a nearby ZIP (ZIP search only, after the others)
distance_kmnumberwith zip_match: nearbyAbout how far, ZIP center to ZIP center
versionintegeralwaysProfile version

Profile (get_business)

Each fact is {"value", "certainty"}; certainty is confirmed, likely or may. A fact we do not have is left out: say "call to ask", never guess.

FieldWhat it holds
id, view, trade, tradesThe id, the view sent back, the main trade and all trades
statusopen, or a warning like may be closed
identityname, phone, website, address (zip, city, state, storefront), location (an approximate map point)
trustlicenses (type, issuer, number, status, expires, verified), insurance, license_applies
activitypermits_12m, and job_zips_12m (the top ZIPs with permitted work in the last year)
existsWhen each source last saw it, stale, legally_active
actionsHow to reach it: {"type": "call" | "website" | "booking" | ..., "value" or "url", "agent_can": "tell" | "send_link"}
availabilitylevel (as on the card) and a note
website_factsHours, services, prices, 24/7 from its own website; status: not_crawled means unknown. Long lists (service-area ZIPs and cities, services) show their first items; *_total gives the count and view=full lists all
caveatsWeak spots to pass on
confidence, claimed, updated_at, version, profile_versionOverall confidence, whether the owner has claimed it, the last update, versions
merged_fromOnly when the id you sent was merged into this business

view=full adds, on every fact, its sources (where and when it was seen) and any conflict between sources.

Auth

WhereHeader
REST /v1/*X-API-Key: ard_...
MCP /mcpX-API-Key: ard_... or Authorization: Bearer ard_...

Keep keys out of code you share, logs and screenshots. If one leaks, revoke it on the key page.

Errors

Always the same shape, with a stable code and a message you can show:

{"error": {"code": "bad_zip", "message": "zip is five digits, like 78701."}}
StatusCodes
400no_filter, no_place (a trade or service with no zip, city or name), bad_zip, bad_trade, bad_service, bad_view, unknown_city, bad_request
401no_key, bad_key (wrong, revoked or turned off)
403blocked (the account is turned off)
404not_found, no_profile
409name_taken, key_limit (key page: a name you already use, or 3 keys already)
429rate_limited (per minute) and daily_limit (per UTC day), with a Retry-After header in seconds
500internal: try again later

Over MCP the same codes come back as a tool error: bad_zip: zip is five digits, like 78701.

Limits

Need more? Write to support@myownline.com.

Coverage

Austin, Texas and the cities around it; the trades list_services returns only. A ZIP search also returns businesses in nearby ZIPs (a radius set per trade), after the exact matches. Facts come from state licenses, city permits, open place data and each business's own website. They can be wrong or out of date: each one says how certain it is, and caveats say what we could not check. A business is never called licensed unless license_verified is true.