# How to integrate a phone-check API with AI coding agents > How AI coding agents read API docs: llms.txt, Markdown twins, OpenAPI and MCP. Set up Claude Code or Cursor, with an AGENTS.md snippet you can copy. Canonical: https://mobilevalidate.com/blog/integrate-mobilevalidate-with-ai-coding-agents · Last updated: 2026-10-22 ![A code editor with an agent side panel is fed by three files labelled llms.txt, AGENTS.md and OpenAPI, with an MCP plug below.](https://mobilevalidate.com/images/blog/integrate-mobilevalidate-with-ai-coding-agents.svg) *Point the coding agent at machine-readable docs, or give it the MCP server.* By MobileValidate team (https://mobilevalidate.com/about) · Published: 2026-10-22 · Category: Developers · Tags: AI agents, MCP, Openapi, Llms txt, Developer tools, API AI coding agents integrate an API well when three things are easy to fetch: a short index of the docs, the docs themselves as plain Markdown, and a machine-readable contract. For MobileValidate those are `/llms.txt`, a `.md` version of every page, and `/openapi.yaml`. Add a test key and an `AGENTS.md` file in your repository, and agents such as Claude Code or Cursor can write and test a working integration without guessing. For checks the agent should run itself, connect the MCP server. ## How do AI coding agents read API documentation? Mostly like a careful developer with no browser. They fetch pages over HTTP, usually without running JavaScript, and they have a limited context window. What helps them, from what we see in agent tool docs and our own sessions: - **An index** that says which page answers which question, so the agent fetches two pages instead of twenty. - **Plain text.** Markdown is compact and unambiguous. HTML full of navigation and scripts wastes context. - **A contract.** An OpenAPI file lists every endpoint, field and error code exactly. - **Runnable examples and test credentials,** so the agent can check its code instead of assuming it works. - **An error catalog with fixes,** so it can correct itself after a failed call. Ours is `/errors.json`. What doesn't help: marketing pages, screenshots of code, and docs that render only in a browser. None of this is a ranking trick. It's about making correct code the easy path. ## Which machine-readable files does MobileValidate publish? | File | What it is | Best for | |---|---|---| | [`/llms.txt`](/llms.txt) | Index of docs, services, posts and policies, one line each, in Markdown (about 20 KB) | The first fetch in any session | | `/llms-full.txt` | Every page in one file (about 490 KB) | Tools that load a whole corpus once | | `.md` | Markdown version of a page: `/docs/quickstart.md`, `/docs/errors.md`, `/services/carrier-lookup.md` | Reading one page with no HTML noise | | [`/openapi.yaml`](/openapi.yaml) | OpenAPI 3.1 contract of every public v1 endpoint, also at `https://api.mobilevalidate.com/v1/openapi.yaml` | Generating clients, checking request and response shapes | | MCP server | `https://mcp.mobilevalidate.com/mcp` (Streamable HTTP) | Letting the agent run checks itself | | [`/facts`](/facts) | Key facts on one page: services, prices, limits and the billing rule, also as `/facts.json` (with a JSON Schema) and `/facts.md` | Quick factual answers without crawling pages | | `/errors.json` | Every API error code with its HTTP status, whether it's retryable, what it means and how to fix it | Letting generated code handle each error correctly | | `/.well-known/api-catalog` | RFC 9727 API catalog: links to the OpenAPI file, the docs and the MCP server card | Automatic discovery of the API | | `/.well-known/ai-catalog.json` | One catalog of the API, MCP server, llms files, facts, error catalog and datasets | Tools that discover everything from one URL | | MCP server card | `https://mcp.mobilevalidate.com/mcp/server-card`, mirrored at `/.well-known/mcp/server-card.json` | MCP clients that read a server's transport and auth before connecting | | [`/datasets`](/datasets) | Our published research data as CSV and JSON, with documentation and licence | Citing or analysing our research | Every HTML page also advertises its Markdown version with ``, and `/llms.txt` links to the `.md` URLs of pages. The [llms.txt proposal](https://llmstxt.org/) dates from September 2024. Treat it as developer experience, not as a search-ranking signal. ## How do you point Claude Code or Cursor at the docs? Start the session with the index and the task, and let the agent choose pages. A prompt that works well: > Read https://mobilevalidate.com/llms.txt, then the quickstart, lookups and errors pages (use the .md links). Write a TypeScript function `checkLineType(numbers: string[])` that calls POST /v1/lookup with checks ["carrier"], polls while status is "pending", and retries only errors with retryable: true. Read the key from MOBILEVALIDATE_API_KEY. Test it with the test numbers from /docs/test-mode.md. In Cursor, you can also add the docs under **Docs** in settings with `https://mobilevalidate.com/llms.txt` as the entry point, then refer to them with `@Docs` in a prompt. For a generated client, give the agent the OpenAPI file and ask it to generate types with a tool such as `openapi-typescript`, rather than writing the types by hand. Two instructions save the most back-and-forth. Tell the agent to use a **test key**, so it can run what it writes. And tell it that `registered: null` means unknown and must never become `false`: agents, like people, tend to collapse three states into two. ## What should go in AGENTS.md? [AGENTS.md](https://agents.md/) is a plain Markdown file at the root of a repository that coding agents read before they start. Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent and others support it. This is the snippet we suggest for a project that uses MobileValidate. Copy it and adjust the commands: ```markdown ## MobileValidate (phone and e-mail checks) - Docs index: https://mobilevalidate.com/llms.txt (every page has a .md version). - API contract: https://mobilevalidate.com/openapi.yaml (OpenAPI 3.1, API base https://api.mobilevalidate.com/v1). - Facts (prices, limits): https://mobilevalidate.com/facts.json. Error codes and fixes: https://mobilevalidate.com/errors.json. - Key: read MOBILEVALIDATE_API_KEY from the environment. Never hard-code keys or print them. - Tests and local runs use a TEST key (mv_test_…) only. Never use a live key (mv_live_…) in tests or CI. - Test numbers: +447700900001 registered/data, …002 not registered, …003 unknown, …004 pending ~5 s, …005 unsupported_country, …429 rate_limited, …402 insufficient_balance. - Send phone numbers and e-mails in POST bodies only, never in URLs, headers or logs. - `registered` is true | false | null. null means unknown: never coerce it to false. - You're not charged for inconclusive results (unknown, unsupported country, timeout, invalid, duplicate). Don't retry them in a loop. - Retry only errors with "retryable": true, after the Retry-After header. - Max 100 identifiers per POST /v1/lookup; use POST /v1/jobs for larger lists. - Never generate or check sequential number ranges (refused as suspected_enumeration). - Webhooks: verify the Standard Webhooks signature on the raw body before parsing. - Commands: `npm test` (unit), `MOBILEVALIDATE_API_KEY=mv_test_... npm run test:integration`. ``` Every rule in it maps to a mistake we'd expect an agent to make otherwise: live keys in CI, numbers in query strings, unknown treated as no, retry loops on non-retryable errors, and generated test data that looks like a number range. ## When should the agent use MCP instead of writing code? When the task is to **do** something with data now, not to build a feature. "Normalize these 40 numbers and tell me which are invalid" or "check this opted-in list for WhatsApp and carrier" are MCP tasks. "Add a line-type check to our sign-up endpoint" is a coding task. The hosted MCP server exposes nine tools, five of them free (`normalize_numbers`, `estimate_cost`, `get_lookup_job`, `list_services`, `get_account`) and four that spend credit. Connect Claude Code with: ```bash claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \ --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY" ``` Cursor and other clients take the same URL and header in their `mcp.json`. A local stdio package also runs with `npx -y @mobilevalidate/mcp`. The server accepts only test keys and agent keys (`mv_agent_…`, scoped, with a daily spend cap), refuses live keys, and asks for confirmation before spending more than USD 1.00 or checking more than 100 numbers. With a test key, `normalize_numbers` on `07911 123456`, `+44 7911 123456` and `12345` (default country GB) returned "3 numbers: 1 valid, 0 ambiguous, 1 invalid, 1 duplicate." [Phone intelligence for AI agents with MCP](/blog/phone-intelligence-for-ai-agents-with-mcp) walks through the tools and the spend safeguards. ## SDK, OpenAPI or plain HTTP: what should the agent generate? | Situation | Suggest to the agent | |---|---| | TypeScript or JavaScript project | The [`mobilevalidate`](https://www.npmjs.com/package/mobilevalidate) SDK (`npm install mobilevalidate`), or plain `fetch`. The SDK handles waiting, retries and idempotency keys | | Another language | Plain HTTP with the standard client, following our language tutorials | | Many endpoints, strict typing | Generate a client or types from `/openapi.yaml` | | One-off data task | MCP tools, no code at all | Our tutorials for [JavaScript, Python, PHP, Go and Java](/blog/phone-number-validation-in-code) are good few-shot examples to paste into a prompt. Each one validates with libphonenumber first, then calls the API, and each was run against the API in test mode. ## How do you keep an agent from spending money or leaking data? Agents act quickly and literally. A few boundaries make them safe to use with a paid API that handles personal data: - **Test keys by default.** They're free and never reach a real network: the test numbers return fixed answers, and any other valid number gets a stable fake answer. An agent can loop on its code without cost. - **Agent keys for real work.** Scoped and capped per day; the cap is the hard limit, whatever the agent decides. - **`max_cost` on every request.** Tell the agent to set it. The API refuses any request whose maximum cost is higher. - **No real numbers in prompts or fixtures.** Use the test range, `+44 7700 900000` to `900999`. Real numbers are personal data and don't belong in chat logs. - **Review before merge.** Agent-written code that handles phone numbers should get the same review as anyone's: POST bodies, masked logs, `null` handled as unknown. The anti-enumeration rules apply to agents exactly as to people: 20 or more consecutive numbers in one request are refused. That's by design. Checks are for numbers you already hold, such as customers and sign-ups. ## How can you tell whether the integration is right? Ask the agent to prove it, with the test numbers: 1. `+447700900001` returns data and `+447700900002` a conclusive "no" (or, for carrier, `unknown` with reason `NO_DATA`). 2. `+447700900003` returns `unknown` and the code keeps it as `null`. 3. `+447700900004` is pending for about five seconds, and the code polls until it completes. 4. `+447700900429` returns `429`, and the code waits for `Retry-After` before retrying. 5. `+447700900402` returns `insufficient_balance`, and the code stops without retrying. If all five pass, the integration handles the cases that break most first attempts. If you use webhooks, add a test that a tampered body fails verification; see [how to verify webhook signatures](/blog/verify-webhook-signatures). ## What are the key takeaways? - Give agents an index (`/llms.txt`), Markdown pages (`.md` twins) and a contract (`/openapi.yaml`), not HTML. - Put the rules in `AGENTS.md`: test keys only in tests, POST bodies, `null` is unknown, retry only retryable errors. - Use code for features and the MCP server for one-off data tasks. - Test keys make agent loops free; agent keys with a daily cap and `max_cost` bound real spending. - Verify the integration with the five test numbers that cover data, unknown, pending, rate limits and balance errors. ## Sources 1. [The /llms.txt file](https://llmstxt.org/) — llmstxt.org, 2024 2. [AGENTS.md](https://agents.md/) — agents.md, 2026 3. [Model Context Protocol specification (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18) — Model Context Protocol, 2025 4. [OpenAPI Specification v3.1.0](https://spec.openapis.org/oas/v3.1.0.html) — OpenAPI Initiative, 2021 ## Frequently asked questions ### What is llms.txt? A proposed convention from 2024: a Markdown file at /llms.txt that lists a site's most useful pages with one-line descriptions, so language models can find the right documentation without crawling HTML. Ours links to Markdown versions of every docs page, service page and post. ### Should my coding agent use the OpenAPI file or the MCP server? Use the OpenAPI file and docs when the agent is writing code that calls the API. Use the MCP server when you want the agent itself to run checks during a session, for example to clean a list. Many teams use both. ### Which API key should an AI agent use? For writing and testing code, a test key (mv_test_…): free, fixed answers, no real network. For an agent that runs real checks through MCP, an agent key (mv_agent_…) with scopes and a daily spend cap. The MCP server refuses live keys. ### Does the agent need to read the whole site? No. Point it at /llms.txt and let it fetch the two or three pages it needs, such as the quickstart, lookups and errors pages. /llms-full.txt has everything in one file if your tool prefers that, but it is about 490 KB.