Agent readiness

Geistdocs can generate /agents.md and /.well-known/mcp.json discovery files from your site config. These files tell AI agents where your docs live and which machine-readable integration surfaces your product declares.

What it provides

The generated /agents.md file gives agents a stable starting point before they crawl the rest of your documentation. The optional /.well-known/mcp.json route advertises configured MCP servers without running an MCP server inside Geistdocs.

It can include:

• Product name, description, category, audience, and use cases
• Human-readable docs entry points
• /llms.txt for full documentation context
• /sitemap.md for semantic navigation
• Page-level Markdown guidance for .md and .mdx URLs
• OpenAPI, authentication, scopes, rate limit, and error docs when configured
• MCP manifests and server URLs when configured
• Additional links and agent instructions

Add the route

Generated projects include a thin App Router adapter:

import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
import { config } from "@/lib/geistdocs/config";

export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
  config,
});

Because the route is under [lang], the Geistdocs proxy can serve /agents.md through the default language route.

Generated projects also include a thin adapter for MCP discovery:

import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
import { config } from "@/lib/geistdocs/config";

export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
  config,
});

The MCP discovery route returns 404 until you configure agent.mcp.servers, so generated sites do not claim MCP support by default.

When configured, /.well-known/mcp.json returns the declared MCP servers:

{
  "name": "My Product",
  "description": "My Product helps teams build and deploy applications.",
  "servers": [
    {
      "name": "My Product MCP",
      "url": "https://example.com/api/mcp",
      "description": "Use product tools through MCP."
    }
  ]
}

Configure agent metadata

Add agent-readiness metadata in geistdocs.tsx, then pass it through defineConfig in lib/geistdocs/config.tsx.

import type { GeistdocsAgentReadinessConfig } from "@vercel/geistdocs/config";

export const agent = {
  product: {
    name: "My Product",
    description: "My Product helps teams build and deploy applications.",
    category: "Developer tools",
    audience: ["Frontend developers", "Platform teams"],
    useCases: ["Deploy applications", "Manage domains", "Inspect logs"],
  },
  api: {
    openApiUrl: "https://api.example.com/openapi.json",
    openApiSpecs: [
      {
        label: "Admin API OpenAPI specification",
        url: "https://api.example.com/admin/openapi.json",
        description: "Administrative API operations.",
      },
    ],
    authDocsUrl: "/docs/authentication",
    scopesDocsUrl: "/docs/scopes",
    rateLimitsUrl: "/docs/rate-limits",
    errorsUrl: "/docs/errors",
  },
  mcp: {
    manifestUrl: "/.well-known/mcp.json",
    servers: [
      {
        name: "My Product MCP",
        url: "https://example.com/api/mcp",
        description: "Use product tools through MCP.",
      },
    ],
  },
  links: [
    {
      label: "Support",
      href: "https://example.com/support",
      description: "Get help from the product team.",
    },
  ],
} satisfies GeistdocsAgentReadinessConfig;

import { agent } from "@/geistdocs";

export const config = defineConfig({
  // ...
  agent,
});

Keep it honest

Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new openApiSpecs entries and MCP servers rendered by /.well-known/mcp.json as absolute http or https URLs or root-relative paths. Existing /agents.md URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.

Use /agents.md and /.well-known/mcp.json with llms.txt, .md extension, and Proxy and markdown routes to give agents a complete discovery path.