# MCP Server

SelfDocHub can expose its published documentation to AI models over the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). This page explains how to create access tokens, connect a client and which tools are available.

> **Roles:** The **MCP Server** page (`/mcp-server`) and the token API are for `admin` only. MCP needs the `mcp` feature in your license (included in every tier) and its request quota and token limit apply. See [License and Tiers](/documentation/license).

By default the integration is read-only. It never exposes license data and never creates, edits or deletes anything. It reads the same navigation, search, schema, version history, Change Log and overlay data the web UI serves. The one exception, [Try-It Through MCP](/documentation/mcp-try-it), is off for every token until an administrator enables it.

## Tokens

Access is granted by tokens. Any number can be active at once, and each has its own settings, so one client can be limited to a few services while another sees more.

| Setting | Meaning |
|---------|---------|
| Name | Unique, case-insensitive. |
| Enabled | An inactive token is rejected, its settings are kept. |
| Secret | The Bearer secret. |
| Allowed services | Services the token may read. Any other service returns "not allowed" from every tool. |
| Search result limit | Maximum number of search results. |
| Overlay text | Whether overlay text is included in tool responses. |
| IP/CIDR allowlist | Restricts where the token can be used from. |
| Category toggles | Independent switches for the schema, version-history and search tool categories. |
| Service Branches | Lets the model see every branch. |
| Read Historical Versions | Lets the model read the content of any version it can see. |

The page also shows when the secret was last changed and when the token was last used. Actions: **add**, **edit**, **replace the secret**, switch **active/inactive** and **delete**.

The secret is generated by the server and shown exactly once, right after creation or replacement. Copy it immediately: only a salted hash is stored. Replacing it invalidates the previous one at once.

Settings are read on every request, so changes take effect immediately, with no restart. The same operations exist in the admin REST API under `/api/v1/admin/mcp-tokens`.

If you upgrade from the older single global configuration, it becomes one token named `Default`. A fresh install has no tokens and the endpoint refuses every request until one is added.

## Connecting a client

In an MCP-capable client, such as a connector setting in Claude or Cursor, use:

- **URL**: `https://<your-domain>/mcp`
- **Authorization**: `Authorization: Bearer <token>`

A quick check with curl:

```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":{}}'
```

After a new version of SelfDocHub adds tools, refresh the tool list in your client (disable and enable the server or use its reload button).

## Tools

| Tool | Purpose |
|------|---------|
| `list_services`, `get_service_info` | Services you may read, and details of one. |
| `list_endpoints`, `list_tags` | Endpoints and tags of a service. |
| `get_endpoint_schema` | Parameters, responses and the schemas they use. |
| `list_schemas`, `get_schema` | Reusable schemas of a service. |
| `search_docs` | Full-text search, including text pages. |
| `list_versions`, `get_version_changelog`, `search_changelog`, `diff_versions` | Version history and Change Log. |
| `list_branches` | Branches of a service. Needs **Service Branches**. |
| `list_overlays`, `get_overlay` | Overlays. |
| `list_pages`, `get_page`, `list_page_versions`, `get_page_version` | Text pages and their history. |
| `list_environments`, `send_request` | Try-It through MCP. Only for tokens with Try-It on. |

Every tool enforces the token's allowed services and category toggles on each call. With **Read Historical Versions**, `list_endpoints` and `get_endpoint_schema` accept an optional `version_id`. A version that is unknown, belongs to another service or sits on a hidden branch gets the same error. Without **Service Branches**, only the service's main branch is visible, also in `list_versions` and `get_version_changelog`.

## Rejected requests

Any rejected request, whether a missing or unknown secret, a disabled token or an address outside the allowlist, gets a plain `404 Not Found`, never `401` or `403`. A client probing the endpoint learns nothing about whether MCP exists. The operator does: each rejection is written to the audit log as `mcp_request_rejected` with a reason (`disabled`, `ip_not_allowed`, `missing_bearer_token`, `invalid_token`), the remote address and the token name when known, never the secret.

Behind a reverse proxy, the remote address is the proxy's address, and that is what the allowlist is checked against. `X-Forwarded-For` is not read. A failed tool call (a service that is not allowed, a disabled category, an unknown endpoint, bad arguments) is logged as a warning.

## Next steps

- [Try-It Through MCP](/documentation/mcp-try-it)
- [Security and Audit](/documentation/audit-and-security)

---
Source: https://selfdochub.com/documentation/mcp-server
