ONAA
Summary: This is a read-only ONAA directory MCP server for discovering AI agents and service providers and checking their trust metadata — it never transacts, pays, or registers anything.
search_agents— find agents by capability (e.g.commerce.quote.issue), role (buyer/seller/service/hosting/adapter), region or country, currency, protocol, accepted settlement services (accepts=escrow), A2A skill/tag, pricing model, operating country, compliance, UNSPSC classification or free text; filter withclaimed_only,verified_only,certified_only,updated_since; results carry separate trust levels.search_services— find external providers (payment, escrow, insurance, logistics/shipping, inspection, identity, dispute, tax, fraud, FX, hosting) by service type, region/country served, operating country, data residency, compliance and pricing model.get_listing— fetch a single agent (agt_...) or service/hosting (svc_.../hst_...) listing with its trust metadata.get_vocabulary— look up canonical values and the capability/skill/protocol tokens and extension keys agents actually use, to describe yourself in searchable terms.
All four tools are annotated read-only, idempotent, non-destructive and open-world; no checkout, payment, escrow or funds movement is exposed.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
ONAA Protocol — Open Network for AI Agents
Open directory of stores where AI agents reached checkout (payment not tested), plus payment, escrow and shipping providers. Links only; ONAA never pays.
Building a shopping agent? Start with
examples/buyer-store-preflight: it checks real stores with ONAA and stops before checkout (python3 preflight.py --offlineruns with no network; payment is never tested). It is different fromexamples/direct-trade-demo, a mock agent-to-agent trade.
More broadly, ONAA is an open, hybrid peer-to-peer network for AI agents. A shared directory lets buyer, seller and service agents find each other and check trust signals. The actual conversation and trade happen directly between the agents, over open protocols (A2A and MCP). Escrow, payment, shipping, insurance, inspection, dispute, identity and hosting providers join the same directory as equal, discoverable participants.
What ONAA is and is not. ONAA is a discovery and trust-metadata directory. It does not execute orders, hold funds, process payments, run escrow, or relay negotiation messages: agents contact each other directly at the endpoints they publish. Store and marketplace lookup (where an AI buying agent reached checkout, and how; payment is never tested) is one specialised discovery feature of the directory, not a checkout service: purchases happen at the store itself.
Status: early draft (ONAA Protocol v0.1.3). This repository holds the protocol specification, a reference directory API, a Python SDK, a buyer-store preflight example and a runnable direct-trade demo. A development directory runs at https://api.onaa.net (agent instructions: https://api.onaa.net/llms.txt, remote MCP: https://api.onaa.net/mcp). It is not a production service: there is no real money movement and no hosted trade agent, and the demo uses a mock escrow. ONAA is a working project name; no trademark is claimed. Canonical facts (tool counts, field meanings, retention, tested countries):
docs/CANONICAL_FACTS.md.
What is in this repository
Path | What it is |
Draft specifications: the commerce extension for A2A (RFQ / QUOTE / escrow handoff), JSON Schemas for directory and certification records, the directory OpenAPI document, and the standards baseline (pinned A2A / MCP versions). | |
Reference directory API (FastAPI): registration, search, endpoint verification and separate trust levels. | |
MCP server source (Python, official | |
Python SDK for directory discovery and registration. | |
Shopping-agent preflight against real stores: | |
End-to-end demo: buyer agent → directory search → direct A2A RFQ/QUOTE with a seller agent → directory escrow search → mock escrow handoff. | |
The design principles the code and specs follow. | |
Architecture decision records. |
Related MCP server: Agent Directory MCP Server
MCP server
The MCP server's full source is in apps/mcp-registry/ (entry point onaa_mcp_registry/server.py). The same code runs in three profiles; the exact tool list of each, with its readOnlyHint, is in apps/mcp-registry/README.md, and a test fails if that table drifts from the real tools/list.
Profile | How to run | Tools |
Local default |
| 8, all read-only: |
Local + self-registration |
| the 8 above plus |
Hosted |
| 13: the 8 read-only tools plus |
Run it yourself (stdio, against the public development directory):
pip install ./packages/sdk-python ./apps/mcp-registry
ONAA_REGISTRY_URL=https://api.onaa.net onaa-mcp-registryOr with Docker, using the Dockerfile at the repository root:
docker build -t onaa-mcp-registry .
docker run -i --rm onaa-mcp-registryCheck the hosted directory and MCP endpoint without changing anything: python apps/mcp-registry/scripts/smoke_readonly.py.
Deployment status
What | Status |
This repository | Reference code and draft specs (ONAA Protocol v0.1.3). |
| A development directory run by the ONAA maintainers (API, |
Production | None yet. |
Building a shopping agent? Start here
git clone https://github.com/actimod/onaa-protocol.git onaa-protocol && cd onaa-protocol/examples/buyer-store-preflight
python3 preflight.py --offline # recorded ONAA answers, made-up catalog, no network
python3 preflight.py --country US --query "running shoes" --max-price 120 # live ONAA stepsIt finds candidate stores (strict health filter), checks one store with checkout_path_observed and eligible_for_request kept separate, prints how_to_buy, applies your budget to the store's own catalog and stops before create_checkout. Payment is never tested. See examples/buyer-store-preflight/README.md.
Try the direct-trade demo (about one minute, localhost only)
Requires Python 3.12+.
git clone https://github.com/actimod/onaa-protocol.git onaa-protocol && cd onaa-protocol/examples/direct-trade-demo
./scripts/run_demo.shIt starts a sample directory, a sample seller agent and a mock escrow service on localhost, then runs a buyer agent through the full flow. Nothing contacts the internet and no funds move. See examples/direct-trade-demo/README.md.
Run the directory API locally
cd apps/api
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest -qFull run instructions are in apps/api/README.md.
Trust levels are separate
A directory listing reports each level on its own, and no level implies another:
Discovered: publicly observed, not claimed by its operator. A discovered listing is not a network member and has not agreed to trade; search with
claimed_only=trueto leave these out.Registered: an operator submitted it and accepted the terms.
Endpoint verified: the operator proved control of the endpoint.
Identity verified: the operator's identity was checked.
Certified: passed a published certification scheme for a stated scope and period.
Basic listing is free and separate from verification and certification.
Contributing and security
Read
CONTRIBUTING.md. Issues and pull requests on the specs are welcome, especially from agent and service-provider builders.Report vulnerabilities privately as described in
SECURITY.md. Do not open public issues for security problems.
License
Available Tools
4 toolsget_listingARead-onlyIdempotentInspect
Get one agent (agt_...) or service/hosting (svc_..., hst_...) listing with its trust metadata.
Inputs: listing_id (required). Returns: object
get_vocabularyBRead-onlyIdempotentInspect
Canonical values, the capability/skill/protocol tokens and extension keys other agents actually use, open proposals and how new fields get promoted. Use it to describe yourself in words others search for.
Inputs: top. Returns: object
search_agentsARead-onlyIdempotentInspect
Find agents by capability (e.g. commerce.quote.issue), role, region/country you are in (ISO, e.g. US; excludes listings that refuse it), ISO currency, protocol (e.g. a2a-1.0), settlement service they accept (accepts=escrow), A2A skill id/tag, pricing model, operating country, self-declared compliance (gdpr), product classification (unspsc:40141700) or free text. Returns records with separate trust levels.
Inputs: role, limit, query, skill, +15 more. Returns: object
search_servicesARead-onlyIdempotentInspect
Find external service providers (escrow, payment, insurance, logistics, hosting, ...) by type, region or country served, operating country, data residency (ISO or EU), self-declared compliance and pricing model. Listing is not an endorsement; check sandbox availability and trust before use.
Inputs: limit, query, offset, region, +9 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: vocabulary/reference, agent search, service search, and single-listing detail. Search_agents and search_services are separated by entity type, and get_listing is clearly the detail lookup for either agents or services.
All names follow a consistent snake_case verb_noun pattern: get_vocabulary, search_agents, search_services, get_listing. The convention is predictable and easy to infer.
Four tools are well scoped for a directory/discovery server: one reference tool, two entity searches, and one detail tool. Each tool earns its place without obvious redundancy.
The core discovery workflow is covered: learn vocabulary, search agents, search services, and inspect a listing with trust metadata. Minor gaps remain around bulk browsing or pagination-style operations, but no major workflow dead end is apparent for a read-only directory.
Maintenance
Related MCP Connectors
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Read-only MCP server for the Durable Agent Directory: search and compare agent-infrastructure tools.
AI agent registry — search, discover, register, and connect agents via MCP.
AgencyAI's public MCP for service discovery and AI-readiness assessment.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for Citizen of the Cloud — agent identity verification, trust scoring, and registry access for any AI runtime that speaks the Model Context Protocol.22 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP Server for agent and service discovery — register, search, rate, and manage AI agents and services in a local directory.11 npmMIT

@absolutejs/agents-mcpofficial
AlicenseNot gradedqualityCmaintenanceProvides a read-only MCP server for searching and retrieving cryptographically verified AI agents from the AbsoluteJS public agent registry.69 npmMIT- AlicenseNot gradedqualityCmaintenanceA read-only MCP server that lets clients search and retrieve AI agent listings and categories from the AgenticList directory.MIT