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
- Create an API key. It is shown once; copy it then.
- In Claude Code, add our plugin marketplace and install the plugin. It asks for your key.
- 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-readyGet 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-readyUpdates: /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
- "Dynamic Client Registration rejected (HTTP 404)" after Authenticate or Reconnect: the server got no key, or a wrong one. It uses API keys, not sign-in, so do not use Authenticate. Set the key with
/plugin configure agent-ready-directory@agent-ready(or add the hand-made server again with the header), then restart Claude Code. - Reconnect does not ask for the key. It uses the saved one. Only install and
/plugin configureask. - The tools show twice: remove the hand-made server with
claude mcp remove agent-ready-directory. - Lost the key: it cannot be shown again. Create a new one on the key page, revoke the old one, and set the new one as above.
daily_limit: your account used today's calls; they reset at 00:00 UTC. Today's count is on the key page.
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.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trade | string | optional | One of plumbing, hvac, electrical | |
service | string | optional | A code from list_services, like plumbing.water_heater_repair. Max 60 | |
zip | string | optional | Five digits, the job's ZIP. Matches that ZIP only (no radius) | |
city | string | optional | A Texas city, like Round Rock: searches all its ZIPs. Max 60 | |
name | string | optional | The business name or part of it. Max 100 | |
limit | integer | optional | 5 | 1 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
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
id | string | required | A business id like b_xxxxxxxx | |
view | string | optional | standard | standard 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
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
id | string | required | A business id |
Returns {"id", "name", "actions": [...], "note"}: how to reach the business (see actions under Profile).
list_services
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trade | string | optional | all | One 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.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
id | string | required | A business id | |
claim | string | required | closed, moved, wrong_phone, wrong_hours, wrong_website, wrong_address, wrong_services, not_licensed, duplicate, other | |
field | string | optional | The field that is wrong, like phone. Max 40 | |
detail | string | optional | One 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.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trade | string | optional | One of plumbing, hvac, electrical | |
service | string | optional | A service code. Max 60 | |
zip | string | optional | Five digits | |
city | string | optional | A Texas city; not with zip. Max 60 | |
q | string | optional | Part of the business name. Max 100 | |
limit | integer | optional | 10 | 1 to 50 |
offset | integer | optional | 0 | 0 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}
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
id (in the path) | string | required | A business id | |
view | string | optional | standard | card, 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
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
trade | string | optional | all | One 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 field | Type | Required | Default | Notes |
|---|---|---|---|---|
business | string | required | A business id | |
claim | string | required | One of the claims in /v1/meta | |
field | string | optional | Max 40 | |
detail | string | optional | Max 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)
| Field | Type | When | Meaning |
|---|---|---|---|
id | string | always | The business id; use it with get_business |
name, trade | string | always | Name and main trade |
phone | string | if known | E.164, like +15124772200 |
zip, city | string | if known | The business's own ZIP and city |
why | string[] | always | Why it was picked: quote these |
caveats | string[] | if any | Weak spots, like license not verified: always pass them on |
confidence | string | always | high, medium or low |
license_verified | boolean | always | The only basis for saying licensed |
availability_level | integer | always | 0: no booking page known; 1: a booking link. Never a free time slot |
zip_match | string | with zip or city | job: permitted work in that ZIP in the last year; served: its website lists the area; likely: its own address is in that ZIP |
version | integer | always | Profile 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.
| Field | What it holds |
|---|---|
id, view, trade, trades | The id, the view sent back, the main trade and all trades |
status | open, or a warning like may be closed |
identity | name, phone, website, address (zip, city, state, storefront), location (an approximate map point) |
trust | licenses (type, issuer, number, status, expires, verified), insurance, license_applies |
activity | permits_12m, and job_zips_12m (the top ZIPs with permitted work in the last year) |
exists | When each source last saw it, stale, legally_active |
actions | How to reach it: {"type": "call" | "website" | "booking" | ..., "value" or "url", "agent_can": "tell" | "send_link"} |
availability | level (as on the card) and a note |
website_facts | Hours, services, prices, 24/7 from its own website; status: not_crawled means unknown |
caveats | Weak spots to pass on |
confidence, claimed, updated_at, version, profile_version | Overall confidence, whether the owner has claimed it, the last update, versions |
merged_from | Only 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
| Where | Header |
|---|---|
REST /v1/* | X-API-Key: ard_... |
MCP /mcp | X-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."}}
| Status | Codes |
|---|---|
| 400 | no_filter, bad_zip, bad_trade, bad_service, bad_view, unknown_city, bad_request |
| 401 | no_key, bad_key (wrong, revoked or turned off) |
| 403 | blocked (the account is turned off) |
| 404 | not_found, no_profile |
| 409 | name_taken, key_limit (key page: a name you already use, or 3 keys already) |
| 429 | rate_limited (per minute) and daily_limit (per UTC day), with a Retry-After header in seconds |
| 500 | internal: try again later |
Over MCP the same codes come back as a tool error: bad_zip: zip is five digits, like 78701.
Limits
- 30 requests a minute and 1,000 a day per account, shared by all its keys.
- Up to 3 active keys per account. Each key's name is unique within your account (any case); a revoked key frees its name.
- Reports: 10 a minute.
- Per caller address: 120 requests a minute.
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.