systhema mcp

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.

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 docsLink to this section

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.

--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 filesLink to this section

Project paths are relative to the detected project root; user paths are relative to your home directory.

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 listLink to this section

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 docsLink to this section

systhema mcp remove docs --agent claude,codex,cursor --scope project,user

Accepts --agent <ids>, --scope <scopes>, --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 resultsLink to this section

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_URLLink to this section

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.

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 setupLink to this section

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 sitesLink to this section

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.

RelatedLink to this section

• Docs for AI agents
• Agent skills