# 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:

```bash
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

1. One token per assistant or per team, never a shared one.
2. Allowed services as small as the job needs.
3. An IP allowlist if the assistant runs from known addresses.
4. Try-It off unless you have a concrete need, then on only for test environments.
5. Review the audit log for rejected requests after the first week.

Details and the complete tool list are in the [MCP Server](/documentation/mcp-server) and
[Try-It Through MCP](/documentation/mcp-try-it) pages.

---
Source: https://selfdochub.com/blog/ai-assistants-read-only-access-to-internal-api-docs-with-mcp
