vibecheck0.3.0
AI readinessaeomcp-discovery-missinginfo

No agent interface (MCP) advertised in Next.js

Most AEO is about being read; this one is about being acted on. If your site exposes actions an agent could take — booking, search, checkout, an API — advertising a Model Context Protocol (MCP) interface lets assistants discover and use those tools instead of scraping. It’s optional and only relevant for app/API sites, but for those it’s how you become agent-usable rather than merely agent-readable.

Framework fixes
GeneralNext.jsVanilla JS

Symptoms

  • A GET to /.well-known/mcp.json returns 404
  • Agents can read your content but can’t invoke your actions
  • No machine-discoverable description of your tools/endpoints

How VibeCheck catches it

In your widget · Problems

infoaeoNo agent interface (MCP) advertised

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "aeo", issue: "No agent interface (MCP) advertised", threshold: "/.well-known/mcp.json is not served as a 2xx JSON response" }

The same string in your widget and in your agent’s context — no screenshot, no copy-paste.

Root causes

  • No MCP server exists for the site’s actions yet
  • An MCP server exists but isn’t advertised at a discoverable well-known path

The fix for Next.js

Serve the discovery document from a Route Handler at app/.well-known/mcp.json/route.ts, returning application/json.

app/.well-known/mcp.json/route.tsts
export function GET() {
  return Response.json({ name: 'acme', server: { url: 'https://acme.com/mcp' } })
}

Steps

  1. Decide whether agents should take actions on your site (skip if it’s content-only)
  2. Build an MCP server exposing those actions as tools
  3. Advertise it at /.well-known/mcp.json with an application/json content type

See the general, framework-agnostic fix →

FAQ

Do content sites need this?
No. MCP discovery only matters if you want agents to take actions (search, book, buy, call an API). A blog or docs site can safely ignore it — that’s why VibeCheck reports it as info, not a warning.
What is MCP?
The Model Context Protocol is an open standard for exposing tools and data to AI agents in a structured way. Advertising an MCP server lets assistants discover and use your actions rather than reverse-engineering your UI.
How is an MCP server different from a REST API?
A REST API is a set of endpoints a developer wires up by hand; an MCP server describes those same actions as self-documenting tools an agent can discover and call without a bespoke integration. If you already have an API, an MCP server is usually a thin wrapper that makes it agent-usable.