Safe read-only access to internal API docs for AI assistants with MCP
Assistants write better code when they can read the real documentation. Without it they guess: plausible field names, an endpoint that does not exist, a required parameter they never heard of. The Model Context Protocol (MCP) is the standard way to give an assistant a set of tools, and API documentation is one of the best things to give it. This post covers how to do it without handing over the keys.
What the assistant should be able to do#
For documentation the useful tools are modest: list services and endpoints, read the parameters and responses of an endpoint
together with the schemas they use, search the docs (including your hand-written guides), browse versions and the change
log, and read overlays. SelfDocHub's MCP server provides exactly that: list_services, list_endpoints,
get_endpoint_schema, search_docs, list_versions, get_version_changelog, diff_versions, get_overlay and a few more.
Principle 1: read-only by default#
The integration should never create, edit or delete anything, and never expose license or user data. That is how SelfDocHub's MCP endpoint behaves out of the box. The assistant reads the same navigation, search, schema and history data that the web interface shows.
Principle 2: one token per client, scoped narrowly#
Do not share one secret between every assistant in the company. Create a token per client and limit it:
- allowed services: anything else is refused by every tool;
- IP/CIDR allowlist, so a leaked token is useless outside your network;
- a search result limit;
- switches for the schema, version-history and search categories;
- whether overlay text, other branches and historical versions are visible.
The secret is shown once and stored only as a salted hash. Rotating it invalidates the old one immediately, and changes to a token apply without a restart.
Principle 3: log rejections#
When a token asks for something it may not have, you want to know. Rejected MCP requests are written to the audit log, so a misconfigured client or a probe is visible.
Connecting a client#
In a client that supports MCP servers, such as Claude or Cursor, add a server with the URL https://<your-domain>/mcp and the
header Authorization: Bearer <token>. To check the connection from a terminal:
curl -X POST https://<your-domain>/mcp \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
When to allow requests: Try-It through MCP#
Reading documentation is safe. Letting a model send real requests is not, and that is why it is a separate, off-by-default mode. If you enable it for a token, the model can use only the environments an administrator has explicitly opened to it, with the credentials configured in that environment, and every such request is logged. The answers go to the AI provider, so start with test environments, keep limits low and give such tokens a narrow list of services. The decision is a risk assessment, not a default.
A checklist#
- One token per assistant or per team, never a shared one.
- Allowed services as small as the job needs.
- An IP allowlist if the assistant runs from known addresses.
- Try-It off unless you have a concrete need, then on only for test environments.
- Review the audit log for rejected requests after the first week.
Details and the complete tool list are in the MCP Server and Try-It Through MCP pages.
