---
title: Connect as an AI agent
description: "Discovery files, markdown docs, OpenAPI, WebMCP, and how to call the ledger API."
canonical: https://bennybooks.com/developers/guides/agents
markdown: https://bennybooks.com/developers/guides/agents.md
---
# Connect as an AI agent

Discovery files, markdown docs, OpenAPI, WebMCP, and how to call the ledger API.

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

> **Documentation index.** Start with GET https://bennybooks.com/developers/llms.txt (this section) or GET https://bennybooks.com/llms.txt (site-wide). Follow markdown links — do not scrape HTML.

Prefer Streamable HTTP MCP at /api/mcp with a bb_live_ token (see Connect Streamable HTTP MCP). Use @bennybooks/cli for agent setup and shell/CI (see CLI for agents & shell). OpenAPI + AnythingMCP and direct REST remain supported. Use the curated tool set described in MCP tool design.

## Markdown for agents

- Every HTML docs page has a .md twin (e.g. https://bennybooks.com/developers/quickstart.md)
- rel=alternate Link header points at the twin; describedby → https://bennybooks.com/llms.txt and https://bennybooks.com/developers/llms.txt
- Send Accept: text/markdown (without preferring text/html) to receive markdown with YAML frontmatter
- Responses include X-Markdown-Tokens for rough context budgeting
- Content-Signal: search=yes, ai-input=yes, ai-train=yes on public agent surfaces

```bash curl
curl -sS "https://bennybooks.com/developers/guides/agents" \
  -H "Accept: text/markdown"
```

## Discovery URLs

| URL | What it is |
| --- | --- |
| https://bennybooks.com/llms.txt | Site-wide curated markdown map (llmstxt.org) |
| https://bennybooks.com/developers/llms.txt | Docs index for this https://bennybooks.com/developers tree |
| https://bennybooks.com/llms-full.txt | Full docs corpus for RAG |
| https://bennybooks.com/index.md | Product overview in markdown |
| https://bennybooks.com/auth.md | Agent authentication (bb_live_ tokens) |
| https://bennybooks.com/skill.md | Agent playbook: auth, curated tools, workflows |
| https://bennybooks.com/developers/guides/audit-log.md | How writes appear in Log for humans |
| https://bennybooks.com/agents.txt | Capability announcement (skills + WebMCP pages) |
| https://bennybooks.com/agents.json | Structured companion to agents.txt |
| https://bennybooks.com/.well-known/api-catalog | RFC 9727 API catalog (OpenAPI + ontology) |
| https://bennybooks.com/.well-known/ard.json | ARD manifest (agentic resource discovery) |
| https://bennybooks.com/.well-known/agent-skills/index.json | Agent Skills index with digests |
| https://bennybooks.com/.well-known/mcp/server-card.json | MCP Server Card (Streamable HTTP at /api/mcp) |
| /api/mcp | Streamable HTTP MCP endpoint (Bearer bb_live_) |
| https://bennybooks.com/.well-known/oauth-protected-resource | RFC 9728 protected resource metadata |
| https://bennybooks.com/openapi.json | OpenAPI 3 spec with x-mcp annotations (public) |
| https://bennybooks.com/api/v1/ontology.jsonld | JSON-LD ontology (public) |
| https://bennybooks.com/api/v1/ontology.ttl | Turtle ontology (public) |
| https://bennybooks.com/api/v1/ontology/sparql | SPARQL over static ontology (public, query-only) |

## Call the API

```http
Authorization: Bearer bb_live_<token>
```

- Create a token in Settings → MCP & agents (see https://bennybooks.com/auth.md)
- read lists ledger data; propose-write creates approval-queue items (audit-logged in Log)
- Prefer categoryCode (5100) over display names
- Use limit≤50 on list calls
- Never auto-post journal entries — POST https://bennybooks.com/api/v1/proposals/journal-entry
- Write clear reason/confidence/evidence — humans see them in Approvals and Log

## WebMCP

Browser agents that support WebMCP can call in-page tools on /, https://bennybooks.com/developers, https://bennybooks.com/dashboard, https://bennybooks.com/ledger, and https://bennybooks.com/log. Tools are read-only discovery and same-origin navigation. They do not return ledger or audit rows — use the REST API for data; do not scrape Log.

| Tool | Where | Purpose |
| --- | --- | --- |
| list_discovery_urls | all WebMCP pages | llms.txt, OpenAPI, skill, auth, docs |
| describe_current_page | all WebMCP pages | What an agent should do here |
| open_path | all WebMCP pages | Same-origin navigation |
| search_docs | https://bennybooks.com/developers | Find docs by title; returns .md URLs |
| list_doc_pages | https://bennybooks.com/developers | Full docs tree with HTML + markdown |
| get_docs_index | https://bennybooks.com/developers | Pointer to https://bennybooks.com/developers/llms.txt + start steps |

## Agent readiness (isitagentready.com)

Public docs set Content-Signal (search/ai-input/ai-train), AI bot rules in robots.txt, Markdown Accept negotiation, auth.md, OAuth protected-resource metadata, MCP Server Card (Streamable HTTP at /api/mcp), Agent Skills index, ARD, and WebMCP. We do not publish an A2A Agent Card, Web Bot Auth signing keys, or agentic commerce protocols. DNS-AID records are configured at the DNS provider — see docs/DEPLOY.md.

> WebMCP is a Chrome origin trial (149–156) via document.modelContext.registerTool. Verified in Chrome 152 with chrome://flags/#enable-webmcp-testing (or --enable-features=WebMCPTesting). Cursor's embedded browser does not ship it — tools no-op when modelContext is missing. This page shows live registration status when the API is present. Permissions-Policy: tools=(self) allows same-origin WebMCP.

---

## Machine-readable

- HTML: https://bennybooks.com/developers/guides/agents
- Markdown: https://bennybooks.com/developers/guides/agents.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Connect as an AI agent",
  "description": "Discovery files, markdown docs, OpenAPI, WebMCP, and how to call the ledger API.",
  "url": "https://bennybooks.com/developers/guides/agents",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers/guides/agents",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers/guides/agents.md",
    "encodingFormat": "text/markdown",
    "name": "Connect as an AI agent (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
