> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Portal MCP Server

> Let Claude and other MCP clients read, edit, validate, and preview your portals through the Model Context Protocol.

The **Portal MCP server** lets an AI assistant work on your portals directly — list them, read and edit their files, validate the changes, and deploy a preview URL you can review before anything reaches customers.

It is a **separate connector** from the [Statisfy MCP server](/admin/mcp_server), which exposes customer-intelligence data and is read-only. The two do not share access: a customer-data connection cannot edit portals, and this connection cannot read customer data.

<Warning>
  Portals are an Alpha feature. The tool set and behaviour described here may change.
</Warning>

<Note>
  Going live is always a human action in Portal Studio. The assistant can build and deploy a **preview**, but it cannot publish to your live customer site.
</Note>

### What you can do

Ask your assistant in plain language — it selects the tools itself:

* *"List my portals."*
* *"In the Acme portal, show me `src/App.tsx`."*
* *"Change the welcome heading on the Acme portal and give me a preview link."*
* *"Validate my draft before I save it."*

### Prerequisites

* A portal you've already created (see [Creating a Portal](/portals/creating_a_portal))
* An MCP-aware client (Claude, Claude Code, or another client that supports remote MCP servers)
* An active session at [app.statisfy.com](https://app.statisfy.com) for the authorization step

### Connecting

Statisfy implements the standard MCP authorization spec (OAuth 2.1 + PKCE) with RFC 7591 Dynamic Client Registration. You do not mint or paste an API key — the connection is created by completing an OAuth flow from inside your client.

1. Sign in to [app.statisfy.com](https://app.statisfy.com) so you have an active session.

2. In your client, add a custom connector pointing at:

   ```
   https://api.statisfy.com/mcp/portal
   ```

3. Click **Connect**. Your browser opens Statisfy and asks you to authorize.

4. Review the request and click **Authorize**.

The connector requests exactly one permission, `mcp:portal:write`. Statisfy advertises that scope on this endpoint specifically, so a well-behaved client asks for portal access and nothing else.

<Tip>
  You authorize once per client. Re-authorize if you switch devices, change roles, or revoke the connection. To review or disconnect a client, go to **Admin → Settings → MCP Connections**.
</Tip>

### How a change reaches a preview

The assistant follows a fixed path, and each step is a separate tool so you can stop at any point:

1. **Pick the portal.** It lists your portals and confirms which one you mean by name and URL. It will not assume, even if you only have one.
2. **Read.** It lists files and reads the ones it needs.
3. **Edit the draft.** Writes go to your **draft**, not the live site. Each write replaces a whole file.
4. **Validate.** A dry run of the save checks, committing nothing.
5. **Save.** Runs the validation gate, commits the draft, and starts a build.
6. **Build.** The assistant polls until the build reports `built` — or `failed`, with the error to fix.
7. **Deploy a preview.** A real deploy to a preview URL. The assistant shares the link.
8. **You go live** — in Portal Studio, yourself.

<Note>
  Edits are made against a specific commit. If the portal changed underneath (you edited it in Portal Studio at the same time, for example), the write is rejected rather than silently overwriting your work.
</Note>

### Available tools

| Tool                         | What it does                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `portal_list`                | Lists your portals: id, name, status, live URL, last updated.                |
| `portal_list_files`          | Lists file paths in a portal, including binary assets.                       |
| `portal_read_file`           | Reads one text file. Refuses binary files.                                   |
| `portal_write_file`          | Writes a whole file into the draft, creating it (and any folders) if needed. |
| `portal_save`                | Runs the validation gate, commits the draft, starts a build.                 |
| `portal_build_status`        | Polls a build: `building`, `built`, or `failed` with the error.              |
| `portal_deploy_preview`      | Deploys a built commit to its preview URL.                                   |
| `portal_preview_status`      | Polls a deploy and returns the preview URL once ready.                       |
| `portal_validate`            | Dry-runs the save checks against the current draft. Commits nothing.         |
| `portal_guide`               | Returns the authoring rules and the configuration schema.                    |
| `portal_list_workers`        | Lists active digital workers, for config that references one.                |
| `portal_list_account_fields` | Lists account fields (standard and custom) you can surface in a portal.      |

Only `portal_write_file`, `portal_save`, and `portal_deploy_preview` change anything. The rest are reads.

### Permissions and scope

* Every tool is scoped to **your organization**. The assistant can only reach portals belonging to the account you authorized with.
* This connector cannot read customer-intelligence data. It has no account, contact, or opportunity tools at all.
* The customer-data connector cannot edit portals. The two permissions are separate and are checked on every call.

<Note>
  That separation is deliberate. Portal content can contain text from outside your organization, so the portal connector is kept away from your customer data entirely.
</Note>

### Troubleshooting

<Accordion title="The client says it can't authorize, or the browser never opens">
  Make sure you are signed in at [app.statisfy.com](https://app.statisfy.com) first, then click **Connect** again. The authorization step needs an active session.
</Accordion>

<Accordion title="A write was rejected because the portal changed">
  Someone (or you, in Portal Studio) edited the portal after the assistant read the file. Ask it to re-read the file and reapply the change.
</Accordion>

<Accordion title="The build failed">
  `portal_build_status` returns the error. Ask the assistant to fix it and save again — a failed build never reaches a preview or the live site.
</Accordion>

<Accordion title="The assistant can't see a portal I own">
  Portals are scoped to the organization you authorized with. If you belong to more than one, re-authorize from the correct account.
</Accordion>

### Related

<Card title="Building & Publishing" href="/portals/building_and_publishing">
  Portal Studio, drafts and versions, previewing, and going live.
</Card>

<Card title="Statisfy MCP Server" href="/admin/mcp_server">
  The read-only customer-data connector, and how to manage MCP connections.
</Card>