---
title: Agent readiness
description: Expose agents.md and MCP discovery files that help AI agents discover and use your docs site
type: guide
summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
related:
  - /docs/llms-txt
  - /docs/md
  - /docs/proxy
---

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.

<CopyPrompt text="Review this Geistdocs site's /agents.md and /.well-known/mcp.json files. Check whether they list the product description, documentation links, llms.txt, sitemap.md, OpenAPI specs, and MCP servers accurately.">
  Review this Geistdocs site's `/agents.md` and `/.well-known/mcp.json` files. Check whether they list the product description, documentation links, `llms.txt`, `sitemap.md`, OpenAPI specs, and MCP servers accurately.
</CopyPrompt>

## What it provides

The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. Its product section states when to use the documented product, and the homepage serves the same guidance when an agent requests `text/markdown`. 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:

```ts title="app/[lang]/agents.md/route.ts"
import { createAgentsRoute } from "@vercel/geistdocs/routes/agents";
import { config } from "@/lib/geistdocs/config";

export const { GET, generateStaticParams } = 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:

```ts title="app/[lang]/.well-known/mcp.json/route.ts"
import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
import { config } from "@/lib/geistdocs/config";

export const { GET, generateStaticParams } = 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:

```json
{
  "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`.

```tsx title="geistdocs.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;
```

```tsx title="lib/geistdocs/config.tsx"
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](/docs/llms-txt), [.md extension](/docs/md), and [Proxy and markdown routes](/docs/proxy) to give agents a complete discovery path.