How to Make Your API Discoverable by AI Agents

You built an API. It works. Humans can read your docs and integrate it. But the next wave of consumers are not humans -- they are autonomous AI agents that need to find, understand, and invoke your API without a developer in the loop.

Here is every method available today to make your API discoverable by AI agents, ranked from simplest to most powerful.

1. Start with a Machine-Readable OpenAPI Spec

If your API does not have an OpenAPI 3.x spec, nothing else matters. This is the foundation that every other discovery method builds on.

Serve your spec at a predictable URL:

curl https://api.yourservice.com/openapi.json

Key requirements for agent-friendly specs:

• Descriptive summary and description fields on every operation. Agents use these to decide which endpoint to call.
• Example values in request/response schemas. LLMs perform better when they can see concrete examples.
• Authentication documented in the securitySchemes section.

{
  "paths": {
    "/search": {
      "get": {
        "summary": "Search products by keyword",
        "description": "Returns a list of products matching the query. Supports pagination via offset and limit parameters.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "wireless headphones"
          }
        ]
      }
    }
  }
}

2. Add /.well-known/ai-plugin.json

Originally introduced for ChatGPT plugins, the ai-plugin.json manifest has become a de facto standard for AI agent discovery. It tells agents what your API does, where to find the spec, and how to authenticate.

{
  "schema_version": "v1",
  "name_for_human": "Weather API",
  "name_for_model": "weather",
  "description_for_human": "Get current weather and forecasts for any location.",
  "description_for_model": "Retrieves real-time weather data including temperature, humidity, wind speed, and 7-day forecasts. Use this when the user asks about weather conditions in a specific location.",
  "auth": {
    "type": "service_http",
    "authorization_type": "bearer"
  },
  "api": {
    "type": "openapi",
    "url": "https://api.weather.example.com/openapi.json"
  }
}

Serve this at https://yourdomain.com/.well-known/ai-plugin.json.

3. Add /.well-known/agent.json

The agent.json spec is the newer, more expressive alternative designed specifically for autonomous agents. It supports capability declarations, pricing information, and protocol negotiation.

{
  "name": "Weather Service",
  "description": "Real-time weather data and forecasts",
  "url": "https://api.weather.example.com",
  "capabilities": ["search", "data-retrieval"],
  "protocols": ["rest", "mcp"],
  "authentication": {
    "type": "bearer",
    "token_url": "https://auth.weather.example.com/token"
  },
  "pricing": {
    "model": "per-request",
    "currency": "USDC",
    "base_price": "0.001"
  },
  "openapi_url": "https://api.weather.example.com/openapi.json"
}

The pricing field is what sets agent.json apart. It lets agents make autonomous decisions about whether to use your API based on cost.

4. Publish an llms.txt File

The llms.txt convention (proposed by Jeremy Howard) gives LLMs a human-readable map of your site. Think of it as robots.txt for AI.

Place it at your domain root:

# Weather API

> Real-time weather data for 200,000+ locations worldwide.

## API Documentation
- [Getting Started](https://docs.weather.example.com/quickstart): Authentication, rate limits, and your first request
- [Endpoints Reference](https://docs.weather.example.com/endpoints): Full endpoint documentation
- [Pricing](https://weather.example.com/pricing): Free tier and paid plans

## Integration
- [OpenAPI Spec](https://api.weather.example.com/openapi.json): Machine-readable API specification
- [MCP Server](https://www.npmjs.com/package/@weather/mcp-server): Model Context Protocol server for Claude and other AI assistants

You can also publish llms-full.txt with your complete documentation flattened into a single file. This works well for smaller APIs where the full docs fit within a context window.

5. Build an MCP Server

The Model Context Protocol (MCP) is the most powerful discovery and invocation method available. An MCP server lets AI assistants like Claude directly call your API as a tool.

A minimal MCP server in TypeScript:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "weather-api",
  version: "1.0.0",
});

server.tool(
  "get_weather",
  "Get current weather for a location",
  { location: z.string().describe("City name or coordinates") },
  async ({ location }) => {
    const res = await fetch(`https://api.weather.example.com/current?q=${location}`);
    const data = await res.json();
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
);

Publish it to npm so users can connect with a single command:

npx @weather/mcp-server

6. List Your API in a Discovery Directory

All the methods above require agents to already know your domain. Directories solve the cold-start problem by letting agents search for APIs by capability.

BluePages is an open directory where you can list your API for free. Agents can search it by keyword or capability, and the directory returns the connection details they need:

curl "https://bluepages.ai/api/skills?q=weather+forecast"

The response includes your API's endpoint, authentication method, pricing, and supported protocols -- everything an agent needs to connect without human intervention.

Putting It All Together

Here is the full checklist for maximum discoverability:

1. Publish an OpenAPI 3.x spec with rich descriptions and examples
2. Serve /.well-known/ai-plugin.json for ChatGPT-compatible agents
3. Serve /.well-known/agent.json with pricing and capability metadata
4. Add llms.txt and optionally llms-full.txt at your domain root
5. Build and publish an MCP server for direct tool integration
6. List your API in directories like BluePages

Each layer reaches a different type of agent. OpenAPI covers the basics. Well-known endpoints enable automatic discovery by agents that crawl domains. MCP enables deep integration. And directories solve the "how do agents find you in the first place" problem.

Get Started

The fastest path: list your API on BluePages (takes 2 minutes) and publish an agent.json file. That combination covers both directory-based and domain-based discovery with minimal effort.

If you want the full integration, add an MCP server. The MCP TypeScript SDK makes it straightforward to wrap any REST API.