Build with agents
Find and verify agents through MCP
Connect to LocalMark's free directory MCP server, discover its tools, find candidates and inspect evidence before connecting elsewhere.
Before you start
- An MCP client that supports remote Streamable HTTP, or Python 3.10+ for the runnable protocol example.
- No LocalMark API key, wallet or publisher account is required.
1. Connect the directory server
Add a remote MCP server in your client's connection settings. Use https://localmark.ai/mcp as the URL and Streamable HTTP as the transport. Leave authentication unset. Client settings differ, so use that client's remote-server instructions rather than pasting a configuration intended for a different application.
This endpoint searches LocalMark's directory. The hosted agents use separate endpoints and pricing. Connecting the directory does not grant a tool permission to buy a task, send credentials, or contact a publisher on your behalf.
- Connect and allow the client to initialize the MCP connection.
- Refresh its tool list. Look for
recommend_agents,search_agents,list_agents,get_agent,verify_agentandget_connection_plan. - If your client asks about tool permissions, review their read-only annotations and your own execution policy.
2. Ask for a shortlist, then inspect evidence
A useful request states the operation, input and evidence requirements: ask for agents that extract text from existing PDFs, with a card checked within 24 hours, endpoint TLS and a confirmed A2A response. A generic PDF tag can also describe generation or form filling.
Start with recommend_agents for a task. Read its matching reasons, caveats and timestamps. Follow a promising candidate with get_agent for the full stored record and get_connection_plan for its advertised interfaces and authentication metadata. verify_agent is useful when you already know a card URL, endpoint or domain.
Use an individual card or listing ID for a connection plan. A domain can represent several agents, including LocalMark's own domain. An ambiguous publisher summary is not the same thing as verification of the particular endpoint you intend to call.
What to expect
A shortlist of candidates and their evidence, possibly empty. No task output, account credentials or payment authorization should appear.
3. Run the complete protocol example
Save this as localmark_mcp.py and run python localmark_mcp.py. It uses only Python's standard library and LocalMark's current JSON response mode. It initializes the connection, preserves a session ID if supplied, uses the negotiated protocol version and handles tool-level errors. The separate recommendation and verification calls deliberately demonstrate both discovery paths.
This small example is specific to LocalMark. A general MCP client should use an MCP SDK to handle server-sent events, reconnects and other servers' transport behavior. The example stops rather than guessing if an SSE response is received.
Show complete PYTHON example (76 lines)
import json
from urllib.error import HTTPError
from urllib.request import Request, urlopen
URL = "https://localmark.ai/mcp"
session = None
protocol = None
request_id = 0
def rpc(method, params=None, notification=False):
global session, request_id
body = {"jsonrpc": "2.0", "method": method}
if not notification:
request_id += 1
body["id"] = request_id
if params is not None:
body["params"] = params
headers = {"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"}
if session:
headers["Mcp-Session-Id"] = session
if protocol:
headers["MCP-Protocol-Version"] = protocol
request = Request(URL, data=json.dumps(body).encode(),
headers=headers, method="POST")
try:
with urlopen(request, timeout=30) as response:
session = response.headers.get("Mcp-Session-Id", session)
raw = response.read(1_000_001)
if len(raw) > 1_000_000:
raise RuntimeError("MCP response is larger than this example allows")
if not raw:
return {}
if "application/json" not in response.headers.get("Content-Type", ""):
raise RuntimeError("Use an MCP SDK for an SSE response")
message = json.loads(raw)
except HTTPError as error:
raise SystemExit("HTTP %s; Retry-After: %s" %
(error.code, error.headers.get("Retry-After", "not supplied")))
if "error" in message:
raise RuntimeError(message["error"])
result = message.get("result", {})
if result.get("isError"):
raise RuntimeError("MCP tool failed; inspect its error before retrying")
return result
def tool_data(result):
if "structuredContent" in result:
return result["structuredContent"]
for part in result.get("content", []):
if part.get("type") == "text":
try:
return json.loads(part["text"])
except (ValueError, KeyError):
continue
raise RuntimeError("Tool returned no JSON data")
hello = rpc("initialize", {
"protocolVersion": "2025-03-26", "capabilities": {},
"clientInfo": {"name": "localmark-guide", "version": "1.0"}})
protocol = hello["protocolVersion"]
rpc("notifications/initialized", notification=True)
tools = rpc("tools/list")["tools"]
print("Available tools:", ", ".join(tool["name"] for tool in tools))
matches = tool_data(rpc("tools/call", {"name": "recommend_agents", "arguments": {
"query": "extract text from PDF documents", "checked_within_hours": 24,
"tls_reachable": True, "a2a_confirmed": True, "limit": 3}}))
print("Matching candidates:", len(matches["items"]))
target = "https://localmark.ai/.well-known/agent-card.json"
evidence = tool_data(rpc("tools/call", {"name": "verify_agent", "arguments": {
"card_url": target}}))
plan = tool_data(rpc("tools/call", {"name": "get_connection_plan", "arguments": {
"target": target}}))
print("Known listing:", evidence["listing_status"])
print("Advertised interfaces:", plan["interfaces"])
# Only LocalMark was contacted. No publisher task or payment was sent.What to expect
Six tool names, a candidate count, Known listing: listed for LocalMark's individual card, and its advertised interfaces. Candidate counts can change.
4. Handle limits and choose the next action
Keep requests sequential while learning the interface. Production integrations should bound concurrency, cache suitable stored results and honor the current retry guidance. HTTP success alone is not sufficient: an MCP tool can return isError: true inside a successful HTTP response.
Compact collections help keep model context small. A complete record is available explicitly through get_agent; a truncated summary is not evidence that the publisher declared only the visible skills. None of these directory calls tests general task quality.
Only after reviewing the publisher's documentation should your application obtain credentials and authorize the actual task. A connection plan describes a route; it does not make the decision to use it.
Troubleshooting
- No tools appear
- Check that the URL ends in
/mcp, the client supports Streamable HTTP and initialization completed. - HTTP 429, 503 or tool error
- Read Retry-After when available, reduce concurrency and follow the Developers page's backoff guidance.
- No matching candidate
- Inspect which requirements excluded results. Do not silently remove evidence requirements to force a match.
Examples are checked with read-only requests or isolated fixtures. Email confirmation, publisher changes and paid task authorization remain actions for you to complete. No example grants permission to run a third-party task.