--- title: "Ayush Rai API and MCP server" description: "Developer docs for Ayush Rai's public read-only REST API, OpenAPI spec, and remote MCP server: endpoints, pagination, versioning, and discovery." canonical: "https://www.ayushrai.site/developers/" last-updated: "2026-10-16" --- # Ayush Rai API and MCP server Source: https://www.ayushrai.site/developers/ Markdown: https://www.ayushrai.site/developers.md Developer docs for Ayush Rai's public read-only REST API, OpenAPI spec, and remote MCP server: endpoints, pagination, versioning, and discovery. ## Overview Ayush Rai's site has a public REST API and an MCP server over the same records as the website. Free and public. No account or API key is needed because every endpoint is read-only over published content. There is no separate test environment or paid tier. Clients may cache responses for five minutes. REST responses grant CORS only to the site's own origins, so call the REST API from a server, an agent, or the CLI rather than from a browser page on another site. The MCP endpoint and its Server Card allow any origin. Search is lexical: exact title, title substring, tag or type, then summary. It is not a model and does not infer intent. ## When to use it Answering who Ayush Rai is, what he works on, or how to contact him: read `/index.md`, `/about.md`, and `/contact.md`. Checking whether he has built something in an area (agents, retrieval, extensions, research): call `GET /api/v1/search?q=` and open the `href` of each hit with `.md` appended. Listing, fetching, or comparing his projects with stable fields: call `GET /api/v1/projects`, `/api/v1/projects/{slug}`, or `/api/v1/compare?slugs=a,b`, or the matching MCP tools. Citing a claim: quote the Markdown page that states it and link its HTML URL. Pages mark unverified numbers; do not repeat those as fact. Not for: General programming help, other people, or companies: this site only covers one person's work. Not for: Live data such as availability, prices, or job openings: the content changes when the site is redeployed, not in real time. Not for: Semantic or vector search: search is lexical, so try several short keywords instead of a sentence. Not for: Unconfirmed award details: they are deliberately not published. ## REST API (v1) `GET /api/v1/search?q=open+framework` searches the site index. `type` filters by record type. `GET /api/v1/projects` lists active projects. `category`, `type`, and `archive=1` filter it. `GET /api/v1/projects/overlay-text-box` fetches one. `GET /api/v1/compare?slugs=overlay-text-box,expert-o` compares two to four. The OpenAPI 3.1 spec at `/openapi.json` gives a typed schema for every response, including errors. ## Errors Every error is JSON: `{ "error": { "code", "message", "hint", "docs" } }`. `code` is stable and safe to branch on; `hint` says how to fix the request. Codes: `invalid_query`, `invalid_slug`, `invalid_filter`, `invalid_compare`, `invalid_cursor` (400); `not_found` and `route_not_found` (404); `method_not_allowed` (405); `rate_limited` (429). Unknown paths under `/api/` return `route_not_found` as JSON, not an HTML page. ## Rate limits 60 requests per 60 seconds per client address, counted per server instance. Every response carries RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers-11). Over the limit, the API returns 429 with a Retry-After header in seconds and error code rate_limited. Example: `RateLimit-Policy: "default";q=60;w=60` and `RateLimit: "default";r=57;t=41` mean 57 requests remain and the window resets in 41 seconds. ## Pagination List endpoints are cursor-based. Responses include `nextCursor`; pass it back as `cursor` to get the next page. `nextCursor` is `null` on the last page. `limit` sets the page size from 1 to 20. Treat cursors as opaque. ## MCP server Endpoint: `POST https://www.ayushrai.site/api/mcp` over Streamable HTTP. It is stateless: each request gets a JSON response, with no session and no GET event stream. No authentication. Tools: `list_projects` (with `cursor`), `get_project`, `compare_projects`, and `search_portfolio`. All are read-only and return the same records as the REST API. Server Card (SEP-2127): `GET https://www.ayushrai.site/api/mcp/server-card`, media type `application/mcp-server-card+json`. Domain discovery: ARD at `/.well-known/ard.json` (canonical) and the AI Catalog at `/.well-known/ai-catalog.json` (legacy path). Client config: `{ "mcpServers": { "ayush-portfolio": { "url": "https://www.ayushrai.site/api/mcp" } } }`. The repository also runs the same server over stdio with `npx tsx mcp/server.ts`. ## Natural-language ask `POST /ask` (also GET with `?query=` or `?q=`) accepts an NLWeb-shaped request and returns lexical search hits over the same index as `/api/v1/search`. It is not a generative model. Responses include `_meta.response_type` and `_meta.version` (`0.55`). ## Command line The repository has a zero-dependency CLI in `packages/cli` (`ayushrai search`, `projects`, `project`, `compare`) that prints the API's JSON. It is not yet published to npm, so run it with `node packages/cli/bin/ayushrai.mjs` from a clone. ## Versioning and deprecation Versioned in the URL path. /api/v1 is stable: fields may be added, but none are removed or renamed. Breaking changes ship under a new path such as /api/v2. A replaced version keeps working for at least 90 days; during that window its responses carry Deprecation and Sunset headers and a Link with rel="successor-version", and the dates are listed on /developers. The unversioned /api/search and /api/projects are aliases of v1 and follow the same policy. No version is deprecated today. ## Discovery API catalog (RFC 9727): `/.well-known/api-catalog`. ARD: `/.well-known/ard.json`. MCP discovery: `/.well-known/ai-catalog.json`. Auth notes: `/auth.md`. Agent view: `/?mode=agent`. Index of pages: `/llms.txt`. Agent notes: `/AGENTS.md` and `/SKILL.md`. Every page has a Markdown version at the same path plus `.md`, and `Accept: text/markdown` on a page URL returns it. ## Not provided There is no published SDK or CLI package, API key, OAuth, separate test environment, or paid tier, and the MCP server is not listed in a registry. There is no A2A agent-card because no A2A JSON-RPC endpoint is implemented. The API is small enough to call directly from the OpenAPI spec. _Unverified award metrics are omitted. Wording matches the public site._