AI and MCP

Building with AI

llms.txt, the .md twin of every page, and the "Open in Claude" button — three ways to make a model read this correctly.

This documentation was designed for language models as much as for people. There are three mechanisms and they all serve one purpose: stopping the model from inventing.

1. The .md twin of every page

Append .md to any page address:

text
https://apidocs.blesyum.com/en/webhooks       → the page
https://apidocs.blesyum.com/en/webhooks.md    → raw Markdown

It works for reference pages too:

text
https://apidocs.blesyum.com/en/reference/crm.md            → the whole module
https://apidocs.blesyum.com/en/reference/crm/contacts.md   → one resource family

Why it matters: given HTML, a model swallows the menu, header and script noise too; half its context budget goes to navigation. The .md twin carries only the content.

2. llms.txt

A machine-readable map of the site:

text
https://apidocs.blesyum.com/llms.txt        → index (short)
https://apidocs.blesyum.com/llms-full.txt   → full guide text + endpoint summaries

llms.txt tells a model what is where; the model then fetches what it needs. llms-full.txt gives broad context in a single file.

Inside llms-full.txt endpoints are in one-line summary mode. Full records (parameters, auth, examples) would exceed 12 MB and fit in no model's context — and a file that doesn't fit gets truncated mid-way, after which the model treats the missing part as "not there". Full records live in the per-module .md files.

3. The "Give to AI" button

The button at the top of every page does four things:

  • Open in Claude — starts a chat primed to read the page
  • Open in ChatGPT — the same
  • Copy as Markdown — puts the raw text on your clipboard
  • Connect the MCP server — setup instructions

The chat links send the page's address, not its content. The reason is practical: browsers cap URLs at about 8 KB and a reference page is far above that. A design that embeds the content gets silently truncated on long pages — the model then believes a half-missing document is complete and answers confidently and wrongly.

4. Best: MCP

The three above are one-way: you hand over a page and the model reads it. MCP gives the model search — it decides which page it needs.

Setup: MCP server.

What to tell your assistant

The prompt that works best in practice:

text
We're writing an integration against the Blesyum API.

Rules:
- Do NOT invent endpoint paths, auth headers or scope names.
- Search with search_docs on the blesyum MCP first, then confirm with get_endpoint.
- Read the relevant guide with get_guide before writing code.
- Use Idempotency-Key on write requests.
- On 429, wait out Retry-After.

Those last two lines matter: models don't think about rate limits and idempotency on their own, but they apply both correctly when told.

Bu sayfa işine yaradı mı?