API Catalog

RFC 9727 defines a standard API discovery endpoint and api-catalog link relation. Use it to list your API endpoints and their documentation.

When MCP Toolkit runs on the server and site.url is set, Nuxt AI Ready adds its endpoint automatically. The entry also links its server card when enabled. Set apiCatalog: false to disable the catalog.

nuxt.config.ts

export default defineNuxtConfig({
  site: {
    url: 'https://example.com',
  },
  aiReady: {
    apiCatalog: {
      entries: [
        {
          anchor: '/api/v1',
          serviceDesc: {
            href: '/openapi.json',
            type: 'application/vnd.oai.openapi+json;version=3.1',
          },
          serviceDoc: {
            href: '/docs/api',
            type: 'text/html',
          },
          status: {
            href: '/api/health',
            type: 'application/json',
          },
        },
      ],
    },
  },
})

Relative anchor and href values resolve against the deployed site URL. With app.baseURL: '/docs/', /api resolves to https://example.com/docs/api. Nuxt redirects origin-root discovery requests to the handler under that base path. Absolute URLs stay unchanged, including URLs on other origins.

Entries and Relations

Use anchor for the API endpoint or link context. Add at least one relation target. Each relation accepts one target object or an array of targets.

Option	Linkset relation	Use
`item`	`item`	API endpoint belonging to the catalog
`serviceDesc`	`service-desc`	Machine-readable description, commonly OpenAPI
`serviceDoc`	`service-doc`	Human-readable documentation
`serviceMeta`	`service-meta`	Policies, licensing, or other metadata
`status`	`status`	Health or service status
`apiCatalog`	`api-catalog`	Nested catalog

Targets support href, type, title, hreflang, and media. Add registered relation tokens or absolute extension relation URIs through relations. anchor is reserved for the link context.

export default defineNuxtConfig({
  aiReady: {
    apiCatalog: {
      entries: [{
        anchor: '/api',
        relations: {
          license: { href: '/legal/api-license', type: 'text/html' },
        },
      }],
    },
  },
})

Publish only APIs you intend clients to discover. Check endpoint access controls before adding them to the catalog.

Entries and Relations

Related