Build with AI agents

The Andi AI Search API is built for AI agents. You can call the REST endpoints from agents you build (see the quickstart and AI agent tool example), 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:

Paste into Claude Code, Cursor, or Codex

Set up Andi search for this project: andiai.com

Your agent fetches andiai.com, follows it to the install guide at api.andiai.com, then gets an API key from the API Console, connects the MCP server, and verifies the setup.

Are you an AI agent? Fetch https://api.andiai.com/install.md and follow it to configure Andi Search — MCP server, API key, and verification.

The install guide 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. 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. 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:

claude mcp add --transport http andi https://api.andiai.com/mcp --header "x-api-key: YOUR_API_KEY"

System-wide, for all projects:

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:

{
  "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:

{
  "mcpServers": {
    "andi": {
      "url": "https://api.andiai.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

VS Code

Add to your VS Code settings (JSON):

{
  "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:

[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 runs a local server exposing the same tools:

{
  "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. 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), 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 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 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 that gives agents a description of the search tool, its parameters, and usage guidance. Agents that support skills can install it directly:

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.

Claude Code plugin

The 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:

/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 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 for the full contract.

Keyless pay-per-call

Agents can also pay per call via x402 through Orthogonal without signing up for an API key. See the auth guide for details.

API discovery files

The API publishes these files for automated agent and tool integration:

URL	Description
`/install.md`	Step-by-step agent self-install guide
`/llms.txt`	API summary and links for LLMs
`/auth.md`	Agent-readable guide to authentication and x402
`/openapi.json`	OpenAPI specification
`/.well-known/api-catalog`	RFC 9727 API catalog entry
`/.well-known/integrations.json`	Integration metadata
`/.well-known/mcp/server-card.json`	MCP server card (transport, docs URL)
`/.well-known/agent-card.json`	A2A-style agent card: tools, transports, and auth scheme
`/.well-known/skills/andi-web-search/SKILL.md`	Installable Agent Skill
`/.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 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

claude mcp add --transport http andi-docs https://docs.andiai.com/mcp

Claude web and desktop

Add this to your MCP server settings:

{
  "mcpServers": {
    "andi-docs": {
      "url": "https://docs.andiai.com/mcp"
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "andi-docs": {
      "url": "https://docs.andiai.com/mcp"
    }
  }
}

VS Code

Add to your VS Code settings (JSON):

{
  "mcp": {
    "servers": {
      "andi-docs": {
        "type": "http",
        "url": "https://docs.andiai.com/mcp"
      }
    }
  }
}

llms.txt

The site publishes llms.txt files that list all documentation pages with direct markdown URLs.

File	Contents
`/llms.txt`	Page titles and descriptions with markdown links
`/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.

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

AI agent tool example

Search and fetch workflows for AI agents.

Content retrieval

Full fetch endpoint reference.

Quickstart

Make your first API call.

Response format

JSON and context format output.

Getting started

Search

Features

Resources

Add Andi to your agent

Andi Search MCP server

Claude Code

Cursor

Claude web and desktop

VS Code

Codex CLI

Other MCP clients

Stdio-only clients

MCP tools

`andi_web_search`

`andi_fetch_url`

Error handling

Agent Skill

Claude Code plugin

Install from the GitHub repo

Agent-native output

Keyless pay-per-call

API discovery files

Docs Q&A MCP server (searches this documentation only)

Claude Code

Claude web and desktop

Cursor

VS Code

llms.txt

Markdown content negotiation

AI crawler access

Next steps

AI agent tool example

Content retrieval

Quickstart

Response format

​Add Andi to your agent

​Andi Search MCP server

​Claude Code

​Cursor

​Claude web and desktop

​VS Code

​Codex CLI

​Other MCP clients

​Stdio-only clients

​MCP tools

​andi_web_search

​andi_fetch_url

​Error handling

​Agent Skill

​Claude Code plugin

​Install from the GitHub repo

​Agent-native output

​Keyless pay-per-call

​API discovery files

​Docs Q&A MCP server (searches this documentation only)

​Claude Code

​Claude web and desktop

​Cursor

​VS Code

​llms.txt

​Markdown content negotiation

​AI crawler access

​Next steps

AI agent tool example

Content retrieval

Quickstart

Response format

Add Andi to your agent

Andi Search MCP server

Claude Code

Cursor

Claude web and desktop

VS Code

Codex CLI

Other MCP clients

Stdio-only clients

MCP tools

`andi_web_search`

`andi_fetch_url`

Error handling

Agent Skill

Claude Code plugin

Install from the GitHub repo

Agent-native output

Keyless pay-per-call

API discovery files

Docs Q&A MCP server (searches this documentation only)

Claude Code

Claude web and desktop

Cursor

VS Code

llms.txt

Markdown content negotiation

AI crawler access

Next steps