Why the confusion exists
All three arrive at the same place — a model does something useful with your product — and all three get announced the same way. What differs is who supplies the knowledge of how to use the thing: your documentation, your schema, or your prose.
Layer one: the API is the surface
The capability itself. Endpoints, verbs, status codes, auth. Complete, stable, and assuming the caller has read something. Every layer above is a way of not making them.
curl -X POST https://read.botook.ai/sites \
-H "Authorization: Bearer otr_live_YOUR_KEY" \
-F file=@index.htmlLayer two: MCP is the interface
The same capability, described so a model can discover and call it without being told the shape. The typed schemas are the point: they turn "read the docs and construct a request" into "call the function". This is where most of the leverage is, and it is why twelve tools are the headline rather than twenty endpoints.
Layer three: a skill is the expertise
Prose that says when and why, not just how. "Publish the report, gate it to the company domain, put the link at the top of the summary" is not an API call, it is a habit. A skill packages the habit — and goes stale faster than the layers below it, because it encodes judgement rather than mechanism.
Side by side
| API | MCP server | Skill | |
|---|---|---|---|
| Answers | What is possible | How to call it | When and why to |
| Consumed by | Any program | Any MCP client | The model, as instructions |
| Discoverable via | Docs and OpenAPI | tools/list | The client's skill list |
| Changes when | The product changes | The API changes | Best practice changes |
| Fails by | Returning an error | Not being called | Being subtly out of date |
When you need each
- API only: the caller is a program you control, or another team's backend.
- API + MCP: the caller is an agent. The common case now, and the one this repository is built for.
- All three: correct usage is not obvious from the schema — when to gate, what expiry to choose, what to do with the link afterwards.
All three, here
The REST surface is documented at /docs and machine-readable at
/openapi.json. The MCP server is at https://read.botook.ai/mcp with twelve tools. The
skill-shaped guidance — how to authenticate, what to gate, what the defaults imply — is published
as markdown at /auth.md and indexed from /llms.txt, so a
client can load it without a package manager.
Which to build first
The API, always — the other two are projections of it. Then MCP, because that is what makes an agent able to use you at all. A skill last, and only once you notice yourself repeating the same advice; that repetition is the signal that judgement is missing from the schema.
Can a skill replace an MCP server?
Only if the capability is already reachable — a skill that says "call this API" still needs the model to be able to. A skill wrapping a shell command is a fine stopgap.
Do skills work across clients?
Less portably than MCP: the instruction-package format varies, whereas MCP is one protocol. That is an argument for keeping essential capability in tools.
Where does an OpenAPI document fit?
It describes the API for programs and for people writing clients. It is not a substitute for tool schemas, because the model needs the smaller, decision-shaped list.
What does this deployment recommend?
Register the MCP server; fall back to curl if you would rather not. Both hit the same
endpoints, so nothing is exclusive to one path.