> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andiai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build with AI agents
> Connect AI agents to Andi web search via MCP, and to the Andi docs via MCP, llms.txt, and markdown content negotiation. Optimized for Claude Code, Cursor, VS Code, and other AI tools.
The Andi AI Search API is built for AI agents. You can call the REST endpoints from agents you build (see the [quickstart](/getting-started/quickstart) and [AI agent tool example](/examples/ai-agent-tool)), or connect the MCP server to your coding tools for web search and page fetch.
## Add Andi to your agent
Your agent installs and configures the Andi Search API itself — paste one line:
```text title="Paste into Claude Code, Cursor, or Codex" theme={null}
Set up Andi search for this project: andiai.com
```
Your agent fetches `andiai.com`, follows it to the [install guide](https://api.andiai.com/install.md) at `api.andiai.com`, then gets an API key from the [API Console](https://console.andiai.com/signup), connects the MCP server, and verifies the setup.
**Are you an AI agent?** Fetch [https://api.andiai.com/install.md](https://api.andiai.com/install.md) and follow it to configure Andi Search — MCP server, API key, and verification.
The [install guide](https://api.andiai.com/install.md) includes setup snippets for Claude Code, Cursor, Codex, and generic MCP clients.
## Andi Search MCP server
Use Andi as your agent's web search and page fetch tool over the [Model Context Protocol](https://modelcontextprotocol.io/).
**Server URL:** `https://api.andiai.com/mcp`
**Transport:** Streamable HTTP
**Authentication:** Pass your API key in the `x-api-key` header. Get a key from the [API Console](https://console.andiai.com/signup).
Your API key is account-level, not project-level, so a system-wide install works everywhere at once. Each client below notes how to choose between project and system-wide scope.
### Claude Code
For the current project:
```bash theme={null}
claude mcp add --transport http andi https://api.andiai.com/mcp --header "x-api-key: YOUR_API_KEY"
```
System-wide, for all projects:
```bash theme={null}
claude mcp add --scope user --transport http andi https://api.andiai.com/mcp --header "x-api-key: YOUR_API_KEY"
```
### Cursor
Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects:
```json theme={null}
{
"mcpServers": {
"andi": {
"url": "https://api.andiai.com/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}
```
### Claude web and desktop
Add this as a custom connector in your MCP server settings:
```json theme={null}
{
"mcpServers": {
"andi": {
"url": "https://api.andiai.com/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}
```
### VS Code
Add to your VS Code settings (JSON):
```json theme={null}
{
"mcp": {
"servers": {
"andi": {
"type": "http",
"url": "https://api.andiai.com/mcp",
"headers": {
"x-api-key": "YOUR_API_KEY"
}
}
}
}
}
```
### Codex CLI
Add to `~/.codex/config.toml` (system-wide — Codex config applies to all projects), with `ANDI_API_KEY` exported in your shell:
```toml theme={null}
[mcp_servers.andi]
url = "https://api.andiai.com/mcp"
env_http_headers = { "x-api-key" = "ANDI_API_KEY" }
```
The same config is shared by the Codex CLI, IDE extension, and ChatGPT desktop app.
### Other MCP clients
Any client that supports the Streamable HTTP transport can connect: server URL `https://api.andiai.com/mcp`, with your API key in the `x-api-key` request header.
### Stdio-only clients
For MCP clients that only support the stdio transport, the [Andi CLI](/getting-started/cli) runs a local server exposing the same tools:
```json theme={null}
{
"mcpServers": {
"andi": {
"command": "npx",
"args": ["-y", "@andiai/cli", "mcp"],
"env": { "ANDI_API_KEY": "YOUR_API_KEY" }
}
}
}
```
## MCP tools
### `andi_web_search`
Searches the web and returns LLM-ready markdown. Wraps `GET /api/v1/search` with `format=context` and `metadata=full`.
| Parameter | Type | Default | Description |
| ------------------ | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` | string | — | Search query. Supports [query operators](/features/query-operators). Required unless `queries` is supplied. |
| `queries` | array of strings | — | Run up to 5 related queries in one call and get fused, deduplicated results. Alternative to `q` — supply exactly one of the two. |
| `limit` | integer | `10` | Results to return (1–50) |
| `offset` | integer | `0` | Skip this many results — paginate deeper into an existing result set without re-searching |
| `searchMode` | string | `auto` | `auto` (default) sets the search effort per query automatically. Fixed modes — `low-cost`, `fast`, `balanced`, `deep`, `exhaustive` — pin an effort level: `fast` \~1s lowest latency; `balanced` \~1–2s everyday web search; `deep` \~2–3s adds spell correction and broader coverage; `exhaustive` multi-round agentic retrieval (up to \~15s). |
| `effort` | string | — | Pins an effort level by generic tier name instead of a mode: `low`, `medium`, `high`, `max`. An explicit `searchMode` wins over `effort`. Omit for adaptive. |
| `content` | boolean | `false` | Include cleaned page content for each result. Increases cost and tokens. |
| `maxContentLength` | integer | — | Maximum content characters per result when `content=true` |
| `country` | string | — | ISO 3166-1 country code (e.g., `US`, `GB`) |
| `language` | string | — | ISO 639-1 language code (e.g., `en`, `es`) |
| `safe` | string | — | Safe search: `off`, `moderate`, or `strict` |
| `dateRange` | string | — | Recency filter: `24h`, `7d`, `30d`, `90d`, `1y` |
| `includeDomains` | string | — | Comma-separated domains to restrict results to |
| `excludeDomains` | string | — | Comma-separated domains to exclude |
The MCP tool caps `limit` at 50. The REST endpoint allows up to 100.
Results carry the `metadata=full` fields — `content_type`, `word_count`, `lang`, `publisher`, `summary` — in each result's frontmatter when available (see [response format](/features/response-format#per-result-structure)), plus a per-call `cost_dollars`. Results default to extracts; set `content=true` or follow up with `andi_fetch_url` only when extracts aren't enough.
### `andi_fetch_url`
Fetches a web page and returns its content as LLM-ready markdown. Wraps `GET /api/v1/fetch`.
| Parameter | Type | Default | Description |
| ------------------ | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `url` | string | **required** | URL to fetch |
| `query` | string | — | What you want from the page. Returns query-focused extracts (`query_extracts`/`query_snippet`) instead of only full content. |
| `maxContentLength` | integer | `100000` | Maximum content length in characters (minimum 500, maximum 200000) |
See [content retrieval](/search/content-retrieval) for the full fetch endpoint reference.
### Error handling
MCP tool errors come back as a text result with `isError: true`, not a raw HTTP status — the message is written for the calling agent to act on:
| Cause | What the agent sees |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Rate limited (`429`) | Retry-after guidance in seconds |
| Out of credits (`402`) | A message pointing to [console.andiai.com](https://console.andiai.com) to top up |
| Temporarily unavailable / still warming (`503`) | A retry hint, with a wait time when the server provides one |
| Fetch page-level failure (`422`) | The reason (`not_found`, `blocked`, or `unextractable`) and a note that retrying the same URL won't help |
## Agent Skill
The API hosts an installable [Agent Skill](https://agentskills.io/) that gives agents a description of the search tool, its parameters, and usage guidance. Agents that support skills can install it directly:
```bash theme={null}
npx skills add https://api.andiai.com/.well-known/skills/andi-web-search/SKILL.md
```
The skill is also available at `https://api.andiai.com/.well-known/agent-skills/andi-web-search/SKILL.md`, with an index at [`/.well-known/agent-skills/index.json`](https://api.andiai.com/.well-known/agent-skills/index.json).
### Claude Code plugin
The [`andisearch/andi-agent-skills`](https://github.com/andisearch/andi-agent-skills) repository doubles as a Claude Code plugin marketplace. The `andi` plugin installs the `andi-web-search` skill and connects the hosted MCP server in one step:
```text theme={null}
/plugin marketplace add andisearch/andi-agent-skills
/plugin install andi@andi-agent-skills
```
Set `ANDI_API_KEY` in your environment before first use.
### Install from the GitHub repo
The same repository works with the skills CLI — `npx skills add andisearch/andi-agent-skills` — and with Codex's skill installer. See the [repo README](https://github.com/andisearch/andi-agent-skills#install) for the full install matrix, including the Codex plugin.
## Agent-native output
The API supports `format=context`, which returns search results as markdown with YAML frontmatter — sized for LLM context windows and ready to use without JSON parsing. See [response format](/features/response-format) for the full contract.
## Keyless pay-per-call
Agents can also pay per call via x402 through [Orthogonal](https://x402.orth.sh) without signing up for an API key. See the [auth guide](https://api.andiai.com/auth.md) for details.
## API discovery files
The API publishes these files for automated agent and tool integration:
| URL | Description |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [`/install.md`](https://api.andiai.com/install.md) | Step-by-step agent self-install guide |
| [`/llms.txt`](https://api.andiai.com/llms.txt) | API summary and links for LLMs |
| [`/auth.md`](https://api.andiai.com/auth.md) | Agent-readable guide to authentication and x402 |
| [`/openapi.json`](https://api.andiai.com/openapi.json) | OpenAPI specification |
| [`/.well-known/api-catalog`](https://api.andiai.com/.well-known/api-catalog) | RFC 9727 API catalog entry |
| [`/.well-known/integrations.json`](https://api.andiai.com/.well-known/integrations.json) | Integration metadata |
| [`/.well-known/mcp/server-card.json`](https://api.andiai.com/.well-known/mcp/server-card.json) | MCP server card (transport, docs URL) |
| [`/.well-known/agent-card.json`](https://api.andiai.com/.well-known/agent-card.json) | A2A-style agent card: tools, transports, and auth scheme |
| [`/.well-known/skills/andi-web-search/SKILL.md`](https://api.andiai.com/.well-known/skills/andi-web-search/SKILL.md) | Installable Agent Skill |
| [`/.well-known/oauth-protected-resource`](https://api.andiai.com/.well-known/oauth-protected-resource) | OAuth protected resource metadata |
## Docs Q\&A MCP server (searches this documentation only)
This docs site runs its own [Model Context Protocol](https://modelcontextprotocol.io/) server, separate from the Andi Search MCP server above. It lets AI tools search and read *this documentation* — it does not perform web search.
**Server URL:** `https://docs.andiai.com/mcp`
### Claude Code
```bash theme={null}
claude mcp add --transport http andi-docs https://docs.andiai.com/mcp
```
### Claude web and desktop
Add this to your MCP server settings:
```json theme={null}
{
"mcpServers": {
"andi-docs": {
"url": "https://docs.andiai.com/mcp"
}
}
}
```
### Cursor
Add to your `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"andi-docs": {
"url": "https://docs.andiai.com/mcp"
}
}
}
```
### VS Code
Add to your VS Code settings (JSON):
```json theme={null}
{
"mcp": {
"servers": {
"andi-docs": {
"type": "http",
"url": "https://docs.andiai.com/mcp"
}
}
}
}
```
## llms.txt
The site publishes [llms.txt](https://llmstxt.org/) files that list all documentation pages with direct markdown URLs.
| File | Contents |
| --------------------------------------------------------- | ------------------------------------------------ |
| [`/llms.txt`](https://docs.andiai.com/llms.txt) | Page titles and descriptions with markdown links |
| [`/llms-full.txt`](https://docs.andiai.com/llms-full.txt) | Full page content inlined as markdown |
Use `/llms.txt` for discovery and navigation. Use `/llms-full.txt` when you need the complete documentation in a single request.
## Markdown content negotiation
Any docs page returns clean markdown when requested with the `Accept: text/markdown` header. The markdown response includes YAML frontmatter.
```bash theme={null}
curl -H "Accept: text/markdown" https://docs.andiai.com/getting-started/quickstart
```
The response includes `Link` headers pointing to `/llms.txt` and `/llms-full.txt`, and an `X-Llms-Txt` header.
## AI crawler access
The site's `robots.txt` explicitly allows AI crawlers including GPTBot, ClaudeBot, and PerplexityBot.
## Next steps
Search and fetch workflows for AI agents.
Full fetch endpoint reference.
Make your first API call.
JSON and context format output.