--- title: "API and MCP server | Agent MCP Directory" description: "How to query the directory as data: the MCP server at /mcp, the REST API described by openapi.json and the NLWeb ask endpoint, all read-only and open." canonical: https://agentmcpdirectory.com/developers site: "Agent MCP Directory" last_updated: 2026-11-05 section: "Developers" --- # API and MCP server | Agent MCP Directory > How to query the directory as data: the MCP server at /mcp, the REST API described by openapi.json and the NLWeb ask endpoint, all read-only and open. Source: https://agentmcpdirectory.com/developers Site: Agent MCP Directory Last reviewed: 2026-11-05 # API and MCP server Agents can query every directory row through an MCP server at /mcp with five read-only tools, a REST API under /api/v1 described by openapi.json, and an NLWeb /ask endpoint over the rows and pages. No credential is needed, the limit is 120 requests a minute, and each answer names the page to cite. ## Connect the MCP server The server speaks the Streamable HTTP transport at `https://agentmcpdirectory.com/mcp`: send JSON-RPC 2.0 messages with POST and read the JSON answer. There is no session, no credential and no server-initiated stream, so one request is one answer. Any MCP client that takes a URL connects with the address alone. The card at [/mcp/server-card](https://agentmcpdirectory.com/mcp/server-card) and the manifest at [/.well-known/mcp.json](https://agentmcpdirectory.com/.well-known/mcp.json) say the same thing in the forms clients read. ```bash curl -s https://agentmcpdirectory.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}' ``` ```bash curl -s https://agentmcpdirectory.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_company","arguments":{"domain":"stripe.com"}}}' ``` A tool answers with the result as `structuredContent` and the same JSON as text. A wrong argument answers `isError: true` with the parameter list; an unknown tool answers JSON-RPC error -32602. The server also lists resources with `resources/list`: the page index, the method page, this page and the two dataset files, readable with `resources/read`. ## The five tools | Tool | What it returns | Parameters | | --- | --- | --- | | search_directory | Lists directory companies (name, domain, category, MCP status, auth type, transport, tool count, whether a CLI is on record, entry page URL). Filter by words in the company name, registry title or domain, by category, status, auth type, transport or CLI. Call it to find a domain before get_company. | q?: Words to look for in the company name, registry title or domain, for example "stripe" or "pay"; category?: A category name or its slug, for example "Payments & Fintech" or "developer-tools". list_categories gives them all; mcp_status?: verified is the only counted state (tools listed); sign-in is a sign-in challenge, tools not seen, not counted; none-found means no endpoint is on record; auth_type?: none, api-key, oauth-dcr (OAuth with client registration), oauth (OAuth without) or unknown. Rows with no endpoint, and rows whose endpoint did not answer, have no auth type, as on the directory page; transport?: The transport the connector observed; has_cli?: true for companies with a CLI package on record, false for those without. The CLI column is a floor: a package is checked only where a source names one | | get_company | Returns the full directory row for one domain (for example stripe.com): status, endpoint and where it was found, transport, protocol revision, auth type, tool count and the recorded tool names, CLI package, OpenAPI, registries, plus how and when the row was observed and the entry page URL to cite. | domain: The company domain as listed in the directory, for example stripe.com. A leading https:// or www. is ignored | | list_categories | Lists the directory categories with how many companies each holds and how many fall in each status: verified (open, tools listed), sign_in (challenge, tools not seen, not counted), credential_wall, no_answer, no_tools and none_found (no endpoint on record). Call it to see where open servers sit before search_directory. | none | | get_directory_stats | Returns the directory totals: companies, how many count as having an MCP server (tools listed), the split by status, auth type (endpoints that answered, as on the directory page) and transport, the distribution of tool counts across the open servers, and how many have a CLI or an OpenAPI file. No parameters. | none | | get_census | Returns the Act Layer Census: for the Tranco top 10,000 and for the domains on the Ora leaderboard, how many probed domains publish each discovery file (MCP, A2A agent card, agents.json, OpenAPI, OAuth metadata, AI catalog, agent skills), and the same counts per leaderboard category. Filter by cohort, category or file path. | cohort?: top10k is the Tranco top 10,000; ora-leaderboard is the domains scored on Ora's public leaderboard. Omit for both; category?: An Ora leaderboard category, for example "Developer Tools". Only the leaderboard cohort has categories; file?: Words from a file path or label to keep one file, for example "openapi" or ".well-known/mcp.json" | ## The REST API Each tool is also one GET endpoint under `/api/v1/`, with the parameters in the query string and the same JSON in the answer. [/api](https://agentmcpdirectory.com/api) is the index; [/openapi.json](https://agentmcpdirectory.com/openapi.json) describes every operation with its parameters, its response schema and the Error schema; [/.well-known/api-catalog](https://agentmcpdirectory.com/.well-known/api-catalog) links that description the way RFC 9727 says. Paginated endpoints take `limit` and the `next_cursor` of the previous page as `cursor`. - [/api/v1/search\_directory?category=Payments+%26+Fintech&mcp\_status=verified](https://agentmcpdirectory.com/api/v1/search_directory?category=Payments+%26+Fintech&mcp_status=verified): Search the directory. Paginated. - [/api/v1/get\_company?domain=stripe.com](https://agentmcpdirectory.com/api/v1/get_company?domain=stripe.com): One company in full. - [/api/v1/list\_categories](https://agentmcpdirectory.com/api/v1/list_categories): List categories with counts. - [/api/v1/get\_directory\_stats](https://agentmcpdirectory.com/api/v1/get_directory_stats): Directory totals. - [/api/v1/get\_census?cohort=top10k](https://agentmcpdirectory.com/api/v1/get_census?cohort=top10k): Act Layer Census. - [/api](https://agentmcpdirectory.com/api): the index with the endpoints, the dataset downloads, the limits and the versioning policy. ```bash curl -s 'https://agentmcpdirectory.com/api/v1/get_company?domain=stripe.com' | jq .observation ``` ## Ask in plain words The `/ask` endpoint follows NLWeb 0.55. It searches the directory rows, the census files and every page, and returns schema.org objects, each with a `grounding.source` URL to cite. GET takes `query`; POST takes the NLWeb request object. Add `streaming=true`, or `prefer.streaming`, for server-sent events named start, result and complete. With `mode=summarize` the answer gains a one-sentence summary assembled from the results, never from a model. ```bash curl -s 'https://agentmcpdirectory.com/ask?query=stripe' ``` ```bash curl -s https://agentmcpdirectory.com/ask -H 'Content-Type: application/json' -d '{"query":{"text":"payments companies with an open MCP server"},"prefer":{"mode":"list"},"meta":{"version":"0.55"}}' ``` No match answers `_meta.response_type: failure` with code NO\_RESULTS; a missing query answers 400 with INVALID\_QUERY. Context objects are accepted and ignored, because the answers come from the data and not from a conversation. ## Discovery files | File | What it holds | | --- | --- | | /openapi.json | OpenAPI 3.1 for the REST API and /ask; linked from every page as rel=service-desc and from the Link header of the home page. | | /.well-known/api-catalog | The RFC 9727 linkset: the API, the MCP server and the ask endpoint with their descriptions. | | /.well-known/mcp/server-card.json | The MCP server card: name, version, remote URL and protocol versions. The same card is served at /mcp/server-card. | | /.well-known/mcp.json | The manifest: endpoint, transport and the tools with their input schemas. | | /.well-known/ai-catalog.json | AI Catalog 1.0 with entries for the MCP card, the OpenAPI document, the ask endpoint and every document; the same file is at /.well-known/ard.json. | | /schemamap.xml | Schema feeds: the directory rows and the census files as JSON-LD lines under /feeds/, named in robots.txt. | | /.well-known/agent-skills/index.json | One agent skill that says how to answer a question about a company's MCP server with these tools. | ## What a count means A company has an MCP server in these answers only when the connector listed its tools: `has_mcp` is true for `mcp_status` verified and for no other status. A sign-in challenge is its own status, listed apart and never counted. A none-found row says that no source read for this edition names an endpoint, which is not proof that no server exists. Auth types are counted for endpoints that answered, as on the directory page, so a row whose endpoint did not answer has none. Every company answer carries `observed_at` and the method, so a reader can see when and how the row was observed. [The method page](https://agentmcpdirectory.com/method/) holds the full rules. ## Access, limits and errors | Credential | None. The OpenAPI document declares security: [] with no security schemes, and auth.md says the same. The site publishes no OAuth metadata because no endpoint takes a token; metadata for an authorization server that does not exist would send agents to a door that is not there. | | --- | --- | | Rate limit | 120 requests a minute per client address, counted per running instance and announced in RateLimit and RateLimit-Policy headers; a 429 carries Retry-After. The host adds its own limits above that. The whole directory is one download from the data page, so bulk readers never need the API. | | Errors | JSON, never HTML: {"error":{"code","message","hint","status","docs"}} with the codes invalid_params, not_found, method_not_allowed, rate_limited and internal. A missing endpoint under /api answers 404 with the list of endpoints in the hint. | | Writes | There are none, so every call is safe to retry and no idempotency key exists. Every call answers in one response; nothing runs long enough to need a job pattern. | | CORS | Every answer carries Access-Control-Allow-Origin: *, so a browser-resident agent can call the API and the MCP server. The home page also registers two of the tools through WebMCP in browsers that offer it. | ## Versioning The path prefix `/api/v1` is the contract. A breaking change, such as a field removed or renamed or a tool removed, ships under `/api/v2` while `/api/v1` keeps answering for at least 180 days, announced on this page and in the `info.version` of openapi.json. Additive changes, such as a new field or a new tool, do not change the prefix. The MCP server follows the same rule: its card and its `serverInfo.version` carry the same version number as the OpenAPI document. The data behind every answer is edition 2026-11-04; the edition is in the `X-Dataset-Edition` header and in every tool result. Each running instance keeps a data file for ten minutes after it reads it. ## Cite the data Every result names the page it comes from; cite that URL. The data files are published under CC BY 4.0 (see [pricing.md](https://agentmcpdirectory.com/pricing.md)). The citation line for the directory is on [the data page](https://agentmcpdirectory.com/data/), where the rows are also published as CSV and JSON. Agent MCP Directory, "MCP and CLI Directory", 4 November 2026 edition, https://agentmcpdirectory.com/data ## What the surface does not do It does not write, hold accounts, generate text with a model or call any company's MCP server. It does not search beyond this site's own rows and pages, and it does not refresh the data: the connector run behind the rows is the one of 4 November 2026. The directory pages remain the record, and [the method](https://agentmcpdirectory.com/method/) explains how each row is made. Edition 4 November 2026 Method [How rows are verified](https://agentmcpdirectory.com/method/) Data [CSV and JSON](https://agentmcpdirectory.com/data/) Markdown [This page as markdown](https://agentmcpdirectory.com/developers/index.md) ## Sources - [MCP transports, Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports), read 4 November 2026 - [NLWeb repository and specification](https://github.com/nlweb-ai/NLWeb), read 4 November 2026 - [OpenAPI Specification](https://spec.openapis.org/oas/latest.html), read 5 November 2026 Last reviewed 5 November 2026