--- title: "systhema mcp" description: "Connect coding agents to version-correct Systhema documentation and manage their MCP configuration." requested_language: fr language: en translation_notice: "This page isn't translated yet" url: https://docs.systhema.app/fr/cli/mcp version: unreleased (main) docs_index: https://docs.systhema.app/fr/llms.txt --- > This page isn't translated yet. Showing English. `systhema mcp` configures the read-only `systhema-docs` MCP server for coding agents. The only current target is `docs`. Pass the installed `@systhemaui/core` version to the server's tools to read the matching documentation. ```bash systhema mcp add docs --agent claude,codex,cursor --scope project systhema mcp list --json systhema mcp remove docs --agent cursor --scope project ``` ## `systhema mcp add docs` ```bash systhema mcp add docs [options] ``` Adds `systhema-docs` with the HTTP endpoint `https://docs.systhema.app/mcp`. The endpoint is unversioned; the tools resolve the project's version, so upgrades do not need to rewrite the URL. With no flags in a terminal, the command prompts for scope and agents. It prefers project scope when it detects a Systhema project, otherwise user scope. Detected agents are preselected; when none are detected, it selects `agents`. With flags or outside a terminal, the defaults are `agents` and project scope inside a detected Systhema project, otherwise user scope. `agents` expands to Claude Code and Cursor for MCP configuration. This differs from the shared skills directory with the same agent ID. | Flag | Description | Default | | ------------------ | -------------------------------------------------------------- | ------- | | `--agent ` | Agent(s), comma-separated; agents means Claude Code and Cursor | | | `--all-agents` | Connect all supported agents | | | `--dry-run` | Show changes without writing | | | `--json` | Output as JSON | | | `--scope ` | Scope(s): project,user (comma-separated) | | `--agent` accepts comma-separated IDs: `agents`, `claude`, `codex`, `cursor`, `gemini`, `copilot`, `vscode`, `opencode`, `roo`, `windsurf`, `cline`, `continue`, `goose`. The last five currently report `skipped` because this command has no MCP writer for them. `--all-agents` selects every ID and takes precedence over `--agent`; expanded agent IDs are deduplicated. `--scope project,user` configures both scopes. Project scope requires a detected Systhema project. `--dry-run` reads configurations and reports the intended changes without writing files or running the Claude CLI. `--json` returns the per-destination result array instead of the human-readable report. Use `--help` on the command or a subcommand for Commander help. ## Configuration files Project paths are relative to the detected project root; user paths are relative to your home directory. | Agent | Project scope | User scope | Server entry | | ----------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------------------- | | Claude Code | `.mcp.json` | `.claude.json`, managed through `claude mcp` | `mcpServers.systhema-docs`, `{ type: 'http', url }` | | Codex | `.codex/config.toml` | `.codex/config.toml` | `[mcp_servers.systhema-docs]` with `url` | | Cursor | `.cursor/mcp.json` | `.cursor/mcp.json` | `mcpServers.systhema-docs`, `{ url }` | | Gemini CLI | `.gemini/settings.json` | `.gemini/settings.json` | `mcpServers.systhema-docs`, `{ httpUrl }` | | OpenCode | `opencode.json` | `.config/opencode/opencode.json` | `mcp.systhema-docs`, `{ type: 'remote', url, enabled: true }` | | VS Code / Copilot | `.vscode/mcp.json` | Unsupported | `servers.systhema-docs`, `{ type: 'http', url }` | For Claude user scope, the command inspects `.claude.json` and delegates changes to `claude mcp add --scope user --transport http` or `claude mcp remove --scope user`. An update removes the existing entry before adding its replacement. If the Claude executable is missing, it reports `manual` and prints the command to run. JSON files must contain valid JSON objects, including the server group when present. A malformed file produces an `error` for that destination. Other servers and unrelated settings remain, though a changed JSON file is reformatted. Codex edits only the named TOML table, preserving surrounding bytes and comments. ## `systhema mcp list` ```bash systhema mcp list [--json] ``` Reads the known configuration locations and reports `already configured` or `not configured`, with the path and configured URL when available. Inside a project it inspects project and user scopes; outside one it inspects user scope. It lists Claude, Codex, Cursor, VS Code, Gemini and OpenCode, skipping unsupported scopes. It does not contact the server or verify the agent can use it. The only command-specific flag is `--json`. ## `systhema mcp remove docs` ```bash systhema mcp remove docs --agent claude,codex,cursor --scope project,user ``` Accepts `--agent `, `--scope `, `--dry-run` and `--json` with the same meanings as `add`. It has no `--all-agents` flag and does not prompt. Without flags it uses the same agent and scope defaults as noninteractive `add`. Removal deletes only `systhema-docs`, removes an empty JSON server group, and leaves the configuration file itself in place. Removing an absent entry reports `not configured` and writes nothing. ## Idempotence and results Adding an identical JSON server entry or a Codex entry with the same URL reports `already configured` and writes nothing. A different entry reports `updated`; a missing one reports `added`. Repeating removal is a no-op. Dry runs return those same intended statuses with `dryRun: true`. Results include `target`, `server`, `agent`, `scope`, `status` and, when applicable, `path`, `url`, `message` or a manual `command`. An `error` result sets exit code 1. Unsupported destinations report `skipped` rather than failing the entire operation. ## `SYSTHEMA_DOCS_URL` Set this environment variable to a docs site's base URL to configure another instance. The command strips trailing slashes and appends `/mcp`; supply the base URL, not the MCP endpoint. ```bash SYSTHEMA_DOCS_URL=http://localhost:3516 systhema mcp add docs --agent codex --scope project ``` The override applies when adding, including additions through `create` and `skills install`. `list` reports stored URLs; `remove` removes the named entry regardless of its URL. ## Connecting during setup ```bash systhema create my-site --template next --mcp --skill-agents codex,cursor systhema skills install --agent codex --scope project --mcp ``` `create --mcp` connects the server at project scope for the chosen skill agents, falling back to `agents` if none were chosen. `--no-mcp` skips it. Without either flag, interactive creation asks; `--yes` and noninteractive creation skip MCP by default. `skills install --mcp` connects the server for the same agents and scopes as the skill installation. Without the flag, interactive installation asks, except with JSON output; noninteractive installation skips it. Its JSON result includes an `mcp` result array when configuration runs. ## A separate server for Payload sites `systhema-docs` serves documentation only. A separate `systhema-site` MCP server inside Payload sites, for site content, users and health, is planned. There is no `site` target in this command yet. ## Related - [Docs for AI agents](https://docs.systhema.app/fr/getting-started/ai-agents.md) - [Agent skills](https://docs.systhema.app/fr/cli/skills.md)