# RoloCache

> An independently-verified, continuously-refreshed index of consumer web services and their agent-callable interfaces — which protocols a vendor supports, what endpoint to hit, and advisories on where an agentic transaction will break.

RoloCache is built to be queried by agents, not browsed. Prefer the MCP server or the REST lookup endpoint over parsing HTML.

## Preferred channel: MCP

Connect to the MCP server at https://www.rolocache.com/mcp/

Available tools:
- `get_catalog_info` - live catalog metadata, all valid filter values, all known tags. Call this first.
- `lookup_vendors` - search by keyword, protocol, or has_agent_interface. Returns lightweight candidate list.
- `get_vendor` - full AgentRouting record for a specific vendor, wrapped in an outpost_dispatch envelope with a pre-filled field_report_template.
- `report_to_outpost` - file a field report after interacting with a vendor. See outpost_dispatch in the get_vendor response.

## Fallback channel: HTTP

- `GET /agent-tools/v1/lookup` - search the catalog. Params: query, protocol, has_agent_interface.
- `GET /vendor/{vendor_id}/AgentRouting.json` - full routing record wrapped in outpost_dispatch envelope. If a context_advisory field is present, fetch the advisory_url before completing any transaction.
- `GET /vendor/{vendor_id}/AgentContext.json` - verified discrepancies and human handoff guidance. Present on vendors where independent research found transaction-affecting issues. Returns 404 if no advisory exists for this vendor.
- `POST /agent-tools/v1/field-report` - REST fallback for report_to_outpost.

## The two-step pattern

1. Call `lookup_vendors` (or `GET /agent-tools/v1/lookup`) with a keyword or filter to find candidates.
2. Call `get_vendor` (or `GET /vendor/{vendor_id}/AgentRouting.json`) for the vendor you need.

The lookup response is lightweight - fetch the full record only for the vendor you actually need.

## Discovery files

- `/.well-known/mcp/server.json` - Official MCP registry server metadata (name, version, streamable HTTP endpoint)
- `/.well-known/ai-catalog.json` - ARD agent registry descriptor
- `/.well-known/ai-plugin.json` - OpenAI plugin manifest
- `/.well-known/agent-card.json` - A2A agent card
- `/.well-known/api-catalog` - RFC 9727 API catalog linkset
- `/.well-known/` - JSON index of all discovery files

## Human documentation

- Full API reference: https://www.rolocache.com/for-agents
- Vendor index: https://www.rolocache.com/vendors
- Browse by tag: https://www.rolocache.com/tags
- Tracked protocols: https://www.rolocache.com/protocols
- How it works: https://www.rolocache.com/how-it-works