Sophia Stack X

AI agents

Sophia Stack X is built for AI assistants to work on as well as people. An agent learns the system from one plain text reference, then works through MCP tools that check every change like an admin form would.

Connect an agent

On the computer where the install lives:

sophia mcp

This runs an MCP server over standard input and output. Point your assistant's MCP settings at that command, run from the install's folder. In Claude Code, for example, add it to the project's .mcp.json.

Remotely, an agent can use POST /api/v1/mcp with Authorization: Bearer <token>. The token is a site API key with the "mcp" scope, made under API by a site admin. Remote access is bound to that token's site. Tools that touch the server's own files or the whole install are left out.

The tools

  • Read first: docs
  • Content: sites, collections, blocks, entries, entry_get, entry_save, entry_delete
  • Structure: menus, menu_item_save, menu_item_delete, modules, module_save, module_delete
  • Media: media_list, media_upload, media_alt
  • App data: models, records, record_get, record_save, record_delete
  • People: accounts, account_update
  • Extensions: extension_new, extension_check, extension_enable, ext_settings, ext_settings_save, schema
  • Design: style_get, style_set, the same colors, fonts and sizes as the Design screen, checked before anything saves
  • Check and ship: page_preview, publish_preview, publish, releases, rollback
  • SEO: seo_audit, seo_changes, seo_change_decide
  • Shop: orders, order_get, order_action
  • Moving in and the install: import_site, backup, backups, audit_log, mail_outbox

How agents stay safe

  • Every write is checked against the same rules as the admin forms and logged as mcp.<tool> in the audit log.
  • Entry saves are drafts unless the agent sets a state. Saving an existing entry only changes the fields sent.
  • page_preview shows one page with drafts included, and publish_preview is a dry run of a publish. rollback undoes a publish.
  • Remote agents are limited to one site.

The reference

The whole system fits in one text file that an agent reads before it starts: reference.txt. It is the same text sophia docs prints. The project also carries an AGENTS.md with the working rules: read the docs, prefer an extension over changing the core, check with sophia check --json, and never invent facts in client content.