---
title: "Docs MCP server"
description: "Configure systhema-docs and use its five read-only, version-aware documentation tools."
requested_language: fr
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/fr/next/ai-agents/mcp-server
version: unreleased (main)
docs_index: https://docs.systhema.app/fr/next/llms.txt
---
> This page isn't translated yet. Showing English.


`systhema-docs` is a Streamable HTTP documentation server at the documentation site's `/mcp` endpoint. It reads docs and release notes. It does not inspect a local project, read a site's database or edit files.

> [!IMPORTANT]
> A separate `systhema-site` MCP for editing a site's content is planned. It is not this server. Never request content edits, user changes or publishing from `systhema-docs`.

## Install

Use the Systhema CLI connection command:

```bash
systhema mcp add docs
```

Select the agent and scope in the wizard, or set both explicitly:

```bash
systhema mcp add docs --agent claude,codex,cursor,vscode,gemini,opencode --scope project
systhema mcp list --json
```

Use `--dry-run` to inspect writes before adding the connection. `--scope user` configures supported user locations; VS Code's writer supports project scope only. `--agent agents` expands to Claude Code and Cursor, not every agent. `--all-agents` requests all targets and reports unsupported writers.

Existing unrelated entries are preserved. An identical entry is a no-op. Disconnect with `systhema mcp remove docs --agent <id> --scope <scope>` when needed. Older installed CLIs without `mcp` can use the manual configuration below. No documentation version belongs in the endpoint; tools select versions per call.

In the examples below, replace `<docs-origin>` with the documentation site's HTTPS origin, without a trailing slash. These are configuration templates, not literal connection URLs.

### Claude Code

```bash
systhema mcp add docs --agent claude --scope project
```

Merge this entry into the project's `.mcp.json`:

```json title=".mcp.json"
{
  "mcpServers": {
    "systhema-docs": {
      "type": "http",
      "url": "<docs-origin>/mcp"
    }
  }
}
```

For user scope, use Claude Code's MCP settings or its remote-server installer. Keep unrelated server entries intact.

### Codex

```bash
systhema mcp add docs --agent codex --scope project
```

Add this table to the trusted project's `.codex/config.toml`, or to the user's `~/.codex/config.toml`:

```text title=".codex/config.toml"
[mcp_servers.systhema-docs]
url = "<docs-origin>/mcp"
```

Project configuration requires the project to be trusted. Restart or reconnect the agent after adding the entry.

### Cursor

```bash
systhema mcp add docs --agent cursor --scope project
```

Merge into the project `.cursor/mcp.json` or the user's `~/.cursor/mcp.json`:

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "systhema-docs": { "url": "<docs-origin>/mcp" }
  }
}
```

### VS Code

```bash
systhema mcp add docs --agent vscode --scope project
```

Merge the entry into the project's `.vscode/mcp.json`:

```json title=".vscode/mcp.json"
{
  "servers": {
    "systhema-docs": { "type": "http", "url": "<docs-origin>/mcp" }
  }
}
```

The CLI does not write VS Code user settings. Use the editor's MCP settings for a user-wide connection.

### Gemini CLI

```bash
systhema mcp add docs --agent gemini --scope project
```

Merge into `.gemini/settings.json`, or `~/.gemini/settings.json` for user scope:

```json title=".gemini/settings.json"
{
  "mcpServers": {
    "systhema-docs": { "httpUrl": "<docs-origin>/mcp" }
  }
}
```

### OpenCode

```bash
systhema mcp add docs --agent opencode --scope project
```

Merge the remote server into the project `opencode.json`, or the user's `~/.config/opencode/opencode.json`:

```json title="opencode.json"
{
  "mcp": {
    "systhema-docs": {
      "type": "remote",
      "url": "<docs-origin>/mcp",
      "enabled": true
    }
  }
}
```

## Tool behavior

`systhema mcp` accepts the `docs` target. It defaults to project scope when it detects a Systhema project, otherwise user scope; non-interactive calls default to the `agents` target. Only `add` accepts `--all-agents`; `list` accepts `--json` and has no agent or scope filter. See [systhema mcp](https://docs.systhema.app/fr/next/cli/mcp.md).

Every tool returns one text content block containing markdown. The output budget is about 24,000 characters. Long documents include an outline and a continuation instruction. Tool errors set `isError` and give a recovery action.

Read `node_modules/@systhemaui/core/package.json` locally before the first call. Supply that installed version to the tools. The server cannot read it for you.

The following outputs are illustrative excerpts, not live responses. Links in actual output use the documentation origin and the resolved version routes.

## resolve_docs_version

| Argument  | Type                                   | Behavior                                                                        |
| --------- | -------------------------------------- | ------------------------------------------------------------------------------- |
| `version` | optional string, at most 64 characters | Installed version, range, docs minor, `latest` or `next`; omit to list versions |

```json title="Arguments"
{ "version": "1.7.5" }
```

```text title="Example output excerpt"
Systhema docs 1.7 (resolved from 1.7.5)
Latest stable release: 1.7.5. This project is current.
Index: <docs-origin>/llms.txt
```

The index route is unprefixed when the resolved version is latest. An older kept minor uses `/v/<minor>/llms.txt`. A prerelease of a kept minor uses that minor; a prerelease of a newer unreleased minor uses `/next/llms.txt`. Ranges use their minimum version. Older-than-kept versions, archived gaps and newer stable versions return fallback docs with warnings, rather than guaranteeing an exact snapshot.

## search_docs

| Argument  | Type                                   | Behavior                                         |
| --------- | -------------------------------------- | ------------------------------------------------ |
| `query`   | required string, 2–200 characters      | Search one concept per call                      |
| `version` | optional string, at most 64 characters | Defaults to latest; supply the installed version |
| `limit`   | integer, 1–10                          | Defaults to 5                                    |

```json title="Arguments"
{ "query": "custom blocks", "version": "1.7.5", "limit": 3 }
```

```text title="Example output excerpt"
Systhema docs 1.7 (resolved from 1.7.5) · 1 result for "custom blocks"

1. Custom blocks
   <docs-origin>/payload/custom-blocks.md
   Define a block, register it in a tier and render it.

Read more: read_doc(path, section) with the slug and section of a result, or fetch its URL.
```

Search matches headings and content. Read the selected page or section before coding.

## read_doc

| Argument  | Type                                    | Behavior                                                                                   |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `path`    | required string, 1–300 characters       | Page slug, docs URL, repo docs path or recognized installed-package docs path              |
| `version` | optional string, at most 64 characters  | Explicit version takes precedence over a version in the path; otherwise defaults to latest |
| `section` | optional string, at most 120 characters | Heading slug; returns that section and its subsections                                     |

```json title="Arguments"
{ "path": "payload/custom-blocks", "version": "1.7.5" }
```

```text title="Example output excerpt"
Systhema docs 1.7 (resolved from 1.7.5)
# Custom blocks
URL: <docs-origin>/payload/custom-blocks.md

Define a block, register it in a tier and render it.
```

An anchor or `?section=` in the path can select a section. For over-budget pages, request the section named in the outline. Unknown paths return suggestions; use them rather than guessing another URL.

## list_docs

| Argument  | Type                                   | Behavior                                            |
| --------- | -------------------------------------- | --------------------------------------------------- |
| `version` | optional string, at most 64 characters | Defaults to latest                                  |
| `area`    | optional string, at most 60 characters | Filter by an area or path prefix, such as `payload` |

```json title="Arguments"
{ "version": "1.7.5", "area": "payload/custom-blocks" }
```

```text title="Example output excerpt"
Systhema docs 1.7 (resolved from 1.7.5) · 2 pages in payload/custom-blocks

## payload
- payload/custom-blocks: Custom blocks
- payload/custom-blocks/converters: Converters

Read a page: read_doc(path: "<slug>", version).
```

Page sizes appear when known. The server accepts `section` as an alias for `area`, but use the canonical `area` key in new calls.

## get_upgrade_notes

| Argument | Type                                   | Behavior                                  |
| -------- | -------------------------------------- | ----------------------------------------- |
| `from`   | required string, 1–64 characters       | Installed version                         |
| `to`     | optional string, at most 64 characters | Target version; defaults to latest stable |
| `detail` | `outline` or `full`                    | Defaults to `outline`                     |

```json title="Arguments"
{ "from": "1.6.0", "to": "1.7.5", "detail": "outline" }
```

```text title="Example output excerpt"
Systhema upgrade notes 1.6.0 → 1.7.5 · 6 releases (outline)

## 1.7.0
<docs-origin>/changelog/v1.7.0.md
### Upgrade
Upgrade instructions for this release.
### Breaking and behavioral changes
Headings for the changes that require review.
```

The interval includes stable releases greater than `from` and no greater than `to`. A prerelease before a stable release includes that stable release. `full` includes breaking-change text; follow any continuation instruction when the result reaches the budget.

The tool supplies documentation, not an upgrade plan for the local database. Combine it with the [upgrade recipe](https://docs.systhema.app/fr/next/guides/recipes/upgrading-a-client-site.md) and the CLI dry run.

## Verify the connection

Ask `resolve_docs_version` for the installed core version. Confirm the response identifies the resolved docs version and that all five tools are available. Then search and read one page. No site access or content-editing capability should appear under this server.

For connection and lookup failures, use [Troubleshooting](troubleshooting.md) or the [HTTP fallback](docs-for-agents.md).