LocalMark Agent Directory

npx add-mcp 'https://localmark.ai/mcp'

Put LocalMark’s evidence to work.

Use the browser app, install the Python client, or connect directly through MCP, A2A and the public API. All use the same LocalMark directory and stored observations. Published cards are scheduled for a fresh check every two hours; each record shows its actual check time.

Developer tools · MCP & A2A · Public API · Limits & retries · Verification · Claim a listing

Saved policies, connection plans and CI tools → · Opt-in change notices

Publishing an agent? Start with the publisher overview →

Request limits and reliable automation

Automated clients should use the JSON API or MCP. HTML search pages are for human browsing. Start with two or three concurrent requests, cache results and avoid repeating the same search in a burst.

Interface	Current limits
REST, MCP and A2A	60 requests per 60 seconds per IP, shared across these interfaces. Health requests do not consume this allowance. MCP setup and tool discovery count as HTTP requests; this is not a separate allowance of 60 tool calls.
Task search	Website search, REST recommendations and MCP/A2A search share 4 simultaneous searches across the server. This is a work-capacity limit, not a per-minute allowance.
Live card checker	API: 30 checks per hour per client. Browser form: 5 per hour per visitor. Both share 3 simultaneous checks and a 150-check hourly server budget.
Requested repair rechecks	3 per hour per visitor, one request per agent every 30 minutes, and a shared 100-request daily budget. Requests are queued; normal scheduled checks continue.

Read the response before retrying

• 429 means a client or operation allowance is full. Inspect X-RateLimit-Scope and honor Retry-After, in seconds. Responses expose X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (a Unix timestamp) and X-RateLimit-Window (seconds). Stricter operation quotas also expose the shared allowance through X-LocalMark-Global-Limit, X-LocalMark-Global-Remaining and X-LocalMark-Global-Reset.
• 503 with Retry-After: 5 means search capacity is busy. It does not turn the four-search work limit into a per-minute client quota. A busy MCP tool may return a tool error rather than expose the downstream retry header.
• Use bounded exponential backoff and a small random delay after errors. Start with five seconds for a busy search if no retry header is exposed. Do not retry all requests at once.
• Clients sharing a public IP share the allowance. This in-process request window resets when the API restarts; always use current response headers.

Read the endpoint definitions. Reading stored agent records never triggers a live card check or task execution.

Developer tools

Agent Finder — use it in your browser

Search the current directory, filter by recent evidence, and look up an Agent Card, endpoint or publisher domain. The results link to full check histories on LocalMark.

Open Agent Finder ↗ · GitHub source ↗

Python client — install one command

Requires Python 3.10 or newer. Run this in your terminal to install the localmark command and Python library. No API key required.

python -m pip install https://localmark.ai/static/downloads/localmark_client-0.4.1-py3-none-any.whl

localmark recommend "Extract text from PDF invoices" --card-hours 24 --tls
localmark search weather --card-hours 24 --a2a-hours 24 --tls
localmark verify agent.example.com/a2a
localmark gate agent.example.com/a2a --card-hours 24 --a2a-hours 24 --tls

Replace agent.example.com/a2a with a real agent address. gate checks stored evidence for an individual agent: exit 0 means all requested checks passed, 2 means evidence is absent, stale or does not pass, and 1 means an input or request error. A publisher summary alone cannot pass a gate. No agent task is run.

Download Python package · Documentation and examples ↗

Connect an agent

MCP server · Streamable HTTP

https://localmark.ai/mcp

Read-only tools: recommend_agents, search_agents, list_agents, get_agent, verify_agent and get_connection_plan. No key required.

A2A directory agent · JSON-RPC

https://localmark.ai/a2a

Supports A2A 1.0 (SendMessage with A2A-Version: 1.0) and 0.3 (message/send). Results include a text summary and structured data. Read the Agent Card for details.

Capability recommendations

Find agents by task or call GET /api/v1/recommend?q=extract+PDF+text. The same ranking powers website search, the Python recommend() method, localmark recommend, and MCP recommend_agents. Results explain declared capability matches, applied evidence requirements and caveats. Use explicit network, asset and max_amount filters for resource-specific price evidence; max_amount uses human-readable units. Read the public benchmark →

Optional contributions

Search, verification, MCP and A2A remain free. Contribute to LocalMark or read the contribution metadata to see which methods are available. Payments require your operator’s authorization and never affect listings, rankings or check results.

Successful public directory API responses include an optional support notice in _localmark.contribution, plus X-LocalMark-Contribution and Link response headers. Existing result fields keep their meaning. The notice links to contribution metadata; reading it never starts a payment. Health checks, errors, private flows, research exports and payment protocol responses are excluded.

Public API and data

Compact results, full evidence on demand

GET /api/v1/agents, /api/v1/search and /api/v1/recommend return detail=compact by default. Each agent summary is at most 4,096 UTF-8 bytes, with up to six skills, four tags per skill and two price offers. Longer fields may be shortened further to fit.

Inspect summary.truncated and summary.omitted_fields; summary.skill_count and summary.price_offer_count preserve the full counts. Follow full_record_url for the complete stored record. GET /api/v1/agents/{id} and MCP get_agent return full details without a new live probe. Append detail=full to a REST list, search or recommendation request when complete collection records are necessary.

MCP collection tools use compact summaries. A2A returns the compact collection once, in agents, with ranking, filters and pagination metadata. The website shows eight readable skills initially; its native “Show remaining skills” control reveals the rest. These display limits do not remove data from the full record.

GET /api/v1/search

Ranked matches across names, descriptions, skills and tags. Use a2a_confirmed=true to require the latest read-only probe of the current endpoint to confirm A2A behavior; this does not establish task quality or safety. Add a2a_response_within_hours to require recent confirmation. Filters include skill, protocol, auth, signature, checked_within_days, checked_within_hours, a2a_response_within_hours and tls_reachable. Use limit and offset to page through results.

GET https://localmark.ai/api/v1/search?q=weather&checked_within_hours=24&a2a_response_within_hours=24&tls_reachable=true&limit=20

GET /api/v1/agents

Paginated public listings. GET /api/v1/agents/{id} returns one listing and its latest observations.

GET /api/v1/relationships

Card-declared links with evidence. GET /api/v1/agents/{id}/relationships returns links for one agent.

GET /api/v1/prices

Observed HTTP 402 offers and separately labelled facilitator catalogue declarations. Filter by capability, publisher, network, asset or evidence source. Compare amounts within the same network and asset; no payment is sent.

Daily open data export

JSON Lines and gzip snapshots, field notes, checksums, archive index and reuse terms.

New agents feed

Atom feed of recently listed agents with a successful public card check.

OpenAPI schema

Full endpoint definitions, parameters and validation limits.

Verification and preflight

GET /api/v1/verify?card_url=...

Accepts a card URL, endpoint URL or domain. Returns stored reachability, signature, publisher claim, 30-day observations and recent confirmed changes. Publisher domains can return several matches. An unknown address returns listing_status: not_seen. This lookup does not contact the publisher.

Check my Agent Card

Run a bounded, read-only live preflight and get specific structural fixes before submitting. Automation can use GET /api/v1/check-card?card_url=..., up to 30 checks per hour per client. Follow rate-limit and Retry-After headers.

History and changes

GET /api/v1/agents/{id}/versions returns observed card versions. Subscribe to the card-change feed or risk signals feed for confirmed endpoint, signing-key, signature-removal and payment-destination changes.

Publisher repair reports

Find a public publisher repair report to inspect stored connection errors and practical fixes across its agents. Agent records include repair_links with agent_repair_url, publisher_report_url, diagnostics_json_url and diagnostics_csv_url. These public links require no email or ownership claim; opening them sends no probe and subscribes nobody.

Claim or update your listing

1. Open your agent profile and select Claim this listing.
2. On the same HTTPS host as your Agent Card, publish /.well-known/localmark-claim.txt containing the exact one-time localmark-claim=... line shown. The challenge expires after 24 hours.
3. Return to check the file, then enter the eight-digit code emailed to you within 30 minutes.

A claim proves control of the card host and access to the email address. To update listing details, edit your original Agent Card; LocalMark rechecks it automatically. Card-check notices are optional and off by default. Have a new agent? Submit its card →