Agent discovery
The machine-readable surfaces that let AI agents and crawlers find and understand CommSync automatically — no human pointing them at a URL first.
CommSync publishes a small set of well-known, machine-readable files. These files let an AI agent — or the crawler behind one — figure out what CommSync is and how to authenticate. They also show where the MCP server lives, without a human walking it through the app first. Each surface below answers one question a generic discovery process would otherwise have to guess at.
The surfaces
A root map for LLMs — an overview of the product, links to the docs, and the crawling policy, in the format llmstxt.org describes.
/.well-known/api-catalogAn RFC 9727 linkset that indexes both HTTP surfaces (the REST API and the MCP endpoint) and where their docs and health checks live.
/.well-known/mcp/server-card.jsonAn MCP server card (SEP-1649) — transport, auth scheme, and the full tool catalog, readable before a client ever opens a connection.
/auth.mdHow to get credentials: the API key model, in plain terms, at the well-known location the auth.md convention expects.
Crawlers and training policy
/robots.txt explicitly names 18 user agents for AI crawlers (GPTBot,
ClaudeBot, PerplexityBot, Google-Extended, and more) as welcome. These
crawlers can access the marketing site and the knowledge base for the docs — see
robots.txt. Every group also carries a
Content Signals directive:
Content-Signal: search=yes, ai-train=yes, ai-input=yesCommSync says yes to all three signals on purpose: indexing, live AI answers created with retrieval-augmented generation, and model training. This is a deliberate positioning choice, not an oversight — the product wants maximum reach in AI answers and agent tool use.
Link headers
Public marketing pages and every /docs page carry an RFC 8288 Link
response header that points at the three discovery entry points above. An
agent that already fetched the homepage does not need to know any well-known
path in advance:
Link: </.well-known/api-catalog>; rel="api-catalog",
</docs>; rel="service-doc",
</llms.txt>; rel="describedby"; type="text/plain"Markdown on demand
Send Accept: text/markdown to the homepage or any /docs page and CommSync
returns the markdown source instead of rendered HTML — same URL, no
separate .md path to guess:
curl -H "Accept: text/markdown" https://commsync.ai/docs/mcpThe response carries Content-Type: text/markdown and Vary: Accept. Regular
browser requests (which send Accept: text/html,...) are completely
unaffected — this only fires when the client explicitly asks for markdown.
Every docs page also has a public .md mirror for browsers and tools that
cannot set an Accept header — /docs/mcp → /docs/mcp.md,
/docs → /docs.md. The Copy page menu on every article
(top-right of the title) copies that markdown. It can also open the page in
ChatGPT, Claude, or Perplexity with the docs URL as context.
Scope
Negotiation currently covers the homepage and the /docs knowledge base —
the two surfaces an agent is most likely to want as clean text. The rest of
the site, which includes the authenticated app, always returns HTML.
How it fits together
An agent with no prior knowledge of CommSync can bootstrap entirely from
https://commsync.ai/:
Fetch the homepage
Either read the Link header for the catalog URL, or send
Accept: text/markdown for a plain-text summary.
Read the API catalog
/.well-known/api-catalog names both HTTP surfaces — the REST API and
/api/mcp — each with a link to its docs.
Read the MCP server card
/.well-known/mcp/server-card.json gives the transport, the auth header
format, and a full tool-category breakdown.
Get a credential
/auth.md explains the model behind API keys. You mint keys under
Settings, in API Keys — see API keys.
Connect
POST /api/mcp with Authorization: Bearer csk_.... See
MCP server for the full tool catalog.