Connect an agent to the directory

Local plumbing, HVAC and electrical 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 plumbing, hvac, electrical
servicestringoptionalA code from list_services, like plumbing.water_heater_repair. Max 60
zipstringoptionalFive digits, the job's ZIP. Matches that ZIP only (no radius)
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 plumbing, hvac, electrical

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 plumbing, hvac, electrical
servicestringoptionalA service code. Max 60
zipstringoptionalFive digits
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}

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 plumbing, hvac, electrical

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. 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
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
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, 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; plumbing, HVAC and electrical only. 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.