Skip to content

Connect an AI Assistant to Portal MCP

This walks through connecting an AI coding assistant to your portal's MCP server.

Prerequisites

  • Portal 1.21.0 or later
  • Admin access to the portal
  • Claude Code v2.1.224 or later installed (or Codex — see the note under Step 2). If you use the Claude desktop app, work in its Code view, not Chat: the plugin and its commands are available only in Claude Code.
  • Node.js 18 or later, installed and on your PATH. The plugin runs its local MCP server with node.

Step 1: Create an API key

  1. Open the admin console and go to Access > API Keys.
  2. Click New API Key. Leave User set to yourself, and give the key a Name, such as Claude Code - laptop.
  3. Click Create, then copy the key immediately. It is shown only once, and Portal does not store it in a form you can retrieve later.

The assistant acts as the user the key belongs to, with that user's permissions. See API Keys.

Step 2: Install the zportal plugin

The install takes two commands: one adds Zuar's plugin marketplace (the list of plugins Zuar publishes), and one installs the zportal plugin from it. How you run them depends on where you use Claude Code.

In the desktop app, typing /plugin opens the plugin manager instead of running the command, and the plugin manager has no field for adding a marketplace by URL. Ask Claude to run the install commands for you instead.

  1. Open a session in the Code view.

  2. Paste this request and send it:

    Install the zportal Claude Code plugin by running these two commands:
claude plugin marketplace add https://raw.githubusercontent.com/zuarbase/zuar-portal-mcp-plugin/main/marketplace.json
claude plugin install zportal@zuar-portal

  3. Approve the commands when Claude asks to run them. Claude reports when the plugin is installed.

  4. Type /reload-plugins in the prompt box, or start a new session. Claude cannot run this one for you.

You can also run the same two claude plugin commands yourself in a terminal. Plugins installed this way are shared by the desktop app, the terminal, and the VS Code extension on the same computer.

In a Claude Code session:

/plugin marketplace add https://raw.githubusercontent.com/zuarbase/zuar-portal-mcp-plugin/main/marketplace.json
/plugin install zportal@zuar-portal

The second command opens the plugin's details. Choose to install it for your user account.

Then run /reload-plugins, or start a new session.

To confirm the install, type /zportal in the prompt box. The plugin's commands, including /zportal:connect, appear in the list.

Note

Codex cannot refresh MCP tools mid-session, so it uses a standalone downloaded bundle instead of the plugin flow above. See the zuar-portal-mcp-plugin repository for the current Codex setup.

Step 3: Connect to your portal

Run /zportal:connect with your portal's URL and a short name (alias) for it:

/zportal:connect https://your-brand.zuarbase.net your-portal-nickname

You use the alias to refer to this portal in later requests. The command opens a small local form in your browser where you paste the API key from Step 1. The key is entered directly into that form, so it never passes through the conversation with the AI assistant.

Step 4: Verify the connection

Ask the assistant something simple, like "what pages does this portal have?" A working connection returns a real answer from your portal's content.

Step 5: Try it

Ask for a change in plain language, for example:

Add a revenue-by-region chart to the sales page.

The assistant profiles the relevant data, builds the chart, and validates it before saving.

Validation confirms that the content is configured correctly, but not how the page looks. When the assistant can open your portal in a browser, it views each page it builds or edits and fixes what displays wrong before it reports the work as done. Without a browser, it validates the content and tells you the page was not checked visually.

To give the assistant a browser, use the Claude in Chrome extension:

  1. Install the Claude in Chrome extension in Google Chrome, Microsoft Edge, or another Chromium-based browser.
  2. Start Claude Code with claude --chrome, or run /chrome in a session and select Enabled by default. When it is connected, /chrome shows Status: Enabled.
  3. In that browser, sign in to your portal. The assistant opens pages in your signed-in browser session.

If a page shows different data to different users, sign in as a user who should see that page rather than as an admin.

Claude in Chrome requires a Claude Pro, Max, Team, or Enterprise plan, with Claude Code signed in through /login. It is not available when Claude Code uses an API key or runs through Amazon Bedrock, Google Cloud, or Microsoft Foundry, and it is not supported in Windows Subsystem for Linux (WSL). See Use Claude Code with Chrome.

Managing multiple portals

Repeat Step 3 for each additional portal, giving each one its own alias. All portals connected in the same session must be running the same Portal version — see Portal MCP Server.