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
- 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 the trades list_services returns | |
service | string | optional | A code from list_services, like plumbing.water_heater_repair. Max 60 | |
zip | string | optional | Five 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) | |
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 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.
| 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 the trades list_services returns | |
service | string | optional | A service code. Max 60 | |
zip | string | optional | Five digits. Nearby ZIPs too, after the exact matches | |
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}
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}
| 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 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 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 (an action book_online). 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; nearby: its own address is in a nearby ZIP (ZIP search only, after the others) |
distance_km | number | with zip_match: nearby | About how far, ZIP center to ZIP center |
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. Long lists (service-area ZIPs and cities, services) show their first items; *_total gives the count and view=full lists all |
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, no_place (a trade or service with no zip, city or name), 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; 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.