MCP Server

SelfDocHub can expose its published documentation to AI models over the Model Context Protocol (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.

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

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#

Screenshots

Last updated: