Skip to content

Portal MCP Server

The Portal MCP Server lets an AI coding assistant, such as Claude Code or Codex, build and edit your portal's content conversationally. Instead of hand-building a chart block by block, an admin can describe what they want: "add a revenue-by-region chart to the sales page," or at scale, "delete every block tagged 'deprecated.'"

MCP (Model Context Protocol) is an open standard for connecting AI assistants to tools and data. Every Portal install ships its own MCP server; you connect your AI assistant to it using the zportal plugin (see Connect an AI assistant to Portal MCP).

Security model

The AI assistant acts as you, the signed-in admin, through the same caller-identity model as the rest of Portal. It is bounded by your existing permissions, and there is no service account involved anywhere in the connection. Two admins connected to the same portal each see and can change only what their own permissions allow, exactly as if they were using the Portal UI directly.

What it can do

Connected, the assistant works with your portal's pages, blocks, queries, data sources, and themes:

  • Inspect. List and open any of them, and trace what depends on what: a block's query, that query's data source, and the data source's credential, or everything that uses a given query. It can also diagnose problems, such as why a page shows nothing or why a block is broken.
  • Explore your data. Before it builds, it looks at your real data instead of guessing: a data source's columns, types, row count, and sample rows. It can run saved queries, and run read-only SQL against a stored database connection to try a statement before saving it as a data source.
  • Create. Build new data sources, queries, blocks (charts, tables, filters, HTML), themes, and pages, then place blocks on a page and set their size and position for each screen size. It can also connect filters and charts so that clicking one filters the others.
  • Modify. Change existing content in place, such as fixing a chart, restyling a theme, or rearranging a page, and leave everything it was not asked to touch as it was.
  • Delete. Remove content after checking what else uses it. See Safety.
  • Check its work. It validates every change before saving it. When the assistant has a browser available, it also opens the page to check the result; otherwise it tells you the page was not checked visually and what to look at.

Backups and undo

  • Backups, when you ask. The assistant can take a full backup of your portal and list the existing ones by time, Portal version, and size. It takes a backup only when you ask for one, because each backup archives the whole instance and is kept until someone deletes it. Restoring from a backup is a step a portal admin takes on the Backups page; the assistant does not restore on its own.
  • Undo, one change at a time. Portal records every change to pages, blocks, themes, queries, and data sources as a change set, one per save, whether the change was made in the Portal interface or by the assistant. The assistant can show what a change set altered and undo it, taking the affected content back to the state it was in immediately before that change, not to some other point in your portal's history. Undoing a delete also restores the item's user group access.
  • Redo by undoing the undo. An undo is itself recorded as a change set, so if you change your mind, you ask the assistant to undo the undo.
  • Undo checks for later work. If someone has changed the same content since the change you want to undo, Portal refuses the undo. The assistant then shows you what the later change did and asks before overwriting it. Overwritten work stays in the history and can be brought back the same way.

Undo is available only through the assistant; the Portal interface has no undo button. Portal keeps the newest 1,000 changes for each item, and the history never stores credentials.

Safety

  • Validation before writing. Every change is checked against Portal's content rules before it is saved.
  • Deletes take two steps. Before deleting anything, the assistant first asks Portal what else uses the item and what will stop working, and only then deletes it.

Current limits

  • One editor at a time. A portal can be edited by a person in the Portal UI or by the AI assistant, not both at once.
  • One Portal version per session. If you manage several portals through the same AI assistant session, they must all be on the same Portal version.

To connect your AI assistant, see Connect an AI assistant to Portal MCP.