# agentbuilt MCP server

A small, stateless [Model Context Protocol](https://modelcontextprotocol.io) server that gives any AI agent a free **AI-readiness audit of a URL**, plus an [A2A](https://a2a-protocol.org) endpoint exposing the same capability as an agent. It runs as plain Vercel serverless functions — no framework, no database, no SDK.

Live endpoint: `https://agentbuilt.dev/api/mcp` (Streamable HTTP, protocol `2025-06-18`).
Listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as `dev.agentbuilt/agentbuilt`.

## Tools

| Tool | What it does | Cost |
|---|---|---|
| `audit_ai_readiness` | Fetches a URL the way an AI crawler would and scores how legible it is to assistants: robots.txt rules for GPTBot / ClaudeBot / PerplexityBot / Google-Extended and friends, whether the page has real text without JavaScript, JSON-LD types, `llms.txt`, sitemap, canonical, meta description, FAQ schema. Returns a score, findings and concrete fixes. | free |
| `list_agentbuilt_tools` | Catalog of agentbuilt's pay-per-result data tools (YouTube transcripts, Substack, Shopify → ChatGPT product feeds, AI visibility audits) with a "how to call" block for each. | free |
| `request_visibility_audit` | Requests the paid-tier audit (does ChatGPT / Perplexity actually *recommend* this brand?) — requires explicit consent and double opt-in by email. | free to request |

## Use it from a client

**Claude.ai / Claude Desktop** — Settings → Connectors → Add custom connector → URL `https://agentbuilt.dev/api/mcp`.

**Cursor** — `.cursor/mcp.json`:
```json
{ "mcpServers": { "agentbuilt": { "url": "https://agentbuilt.dev/api/mcp" } } }
```

**VS Code** — `.vscode/mcp.json`:
```json
{ "servers": { "agentbuilt": { "type": "http", "url": "https://agentbuilt.dev/api/mcp" } } }
```

**curl**
```bash
curl -s https://agentbuilt.dev/api/mcp -H 'content-type: application/json' -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"audit_ai_readiness","arguments":{"url":"https://example.com"}}}'
```

**A2A** — agent card at `https://agentbuilt.dev/.well-known/agent-card.json`; `message/send` to `https://agentbuilt.dev/api/a2a` with a message containing a URL.

## Why the readiness check is built the way it is

- **SSRF-safe fetching** (`api/_lib/net.js`): the hostname is resolved once, every address is validated against private / link-local / CGNAT / metadata ranges (IPv4 and IPv6, including v4-mapped, NAT64 and 6to4 forms), and the HTTPS connection is **pinned to the validated address** via Node's `lookup` option — so a hostile nameserver can't answer public for the check and private for the connect. Redirects are followed manually and re-validated per hop. Only ports 80 and 443.
- **Honest crawler-access reporting**: if a site refuses the anonymous request, the check retries as the documented AI crawler user-agents. A 403 to *our* spoofed GPTBot is reported as exactly that — bot managers such as Cloudflare verify real crawlers by IP and reject impostors — never as "GPTBot is blocked". We learned this the hard way on a real audit; the only proof of a block is a robots rule or the assistant itself failing to read the page.
- **Real-JSON / real-XML probes**: a SPA that returns 200 HTML for `/llms.txt` or `/sitemap.xml` is not counted as having them.
- **Stateless**: no sessions, no storage for the free tool. `GET` with `Accept: text/event-stream` returns 405 by design (no server-initiated streams).

## Deploy your own

Fork, `vercel deploy`. The free tools need no environment variables. `request_visibility_audit` needs `WAITLIST_KEY` (32-byte base64, for sealing emails), `APIFY_TOKEN` and `WAITLIST_DATASET_ID`; without them it returns a clear error and the other tools keep working.

`server.json` is the registry manifest; `PUBLISHING.md` records the exact `mcp-publisher` commands and the gotchas we hit (schema version, description length, UTF-8 BOM).

## About

agentbuilt is an AI-operated studio: an AI agent builds and runs it, and [Matt Edward](https://agentbuilt.dev) (Calgary, Canada) is the accountable human owner. The studio publishes its ledger and its data — e.g. [AI share of voice: lease accounting software](https://agentbuilt.dev/ai-share-of-voice-lease-accounting-software) — at [agentbuilt.dev](https://agentbuilt.dev).

MIT licensed. Issues and PRs welcome; an AI agent reads them, and the owner is accountable for what gets merged.