MCP Technical details

This page is for the people who set up and support Darwinium Portal MCP: IT, security, and technically minded analysts. For the day-to-day guide, see the MCP overview

1. Architecture

Architecture: Claude client, portal-mcp server, Chrome extension and portal tab all on your machine; only the portal tab talks to Darwinium

Everything in the chain runs on the user's machine:

The Claude client (Claude Desktop or Claude Code) launches portal-mcp as an ordinary stdio MCP server and calls its three tools.
portal-mcp binds a WebSocket on 127.0.0.1:9224. That is a loopback address, so nothing outside the machine can reach it. Every connection is authenticated with a 64-character token generated locally on first launch.
The Chrome extension connects to that WebSocket from its service worker and forwards commands into the portal tab as in-page custom events. Its host permissions are locked to https://*.darwinium.com/* and Darwinium's internal test domain. The release build fails if that set widens.
The portal tab publishes a set of page commands. When Claude runs one, the page executes it using the user's normal authenticated session, exactly as if they had clicked the button.

The MCP server exposes exactly three tools. The real capability surface is the list of page commands the portal publishes, which changes depending on the page. Claude discovers that list at the start of each conversation and after each navigation.

Request flow: Claude calls get_page_commands, then run_page_command; the portal tab fetches data over your session and returns it

One client at a time. Only one process can hold port 9224. If Claude Desktop and Claude Code both run the server, the second one reports that another copy owns the bridge and takes over automatically when the first exits.

2. Requirements

Google Chrome 116 or newer. The service worker keeps its WebSocket alive using behaviour introduced in 116. Other Chromium browsers are not officially supported in this release.
A Darwinium portal login at https://portal.darwinium.com.
Claude Desktop or Claude Code. Other stdio MCP clients work but are not covered by the installer.
Node.js 20 or newer, only for the npx path. The .mcpb bundle runs on the Node runtime Claude Desktop ships and needs nothing installed.

3. Install for Claude Desktop

Option A: the `.mcpb` bundle (recommended)

Download DarwiniumPortalMCP-<version>.mcpb from the Releases page. One file covers macOS, Windows and Linux.
Double-click it. Claude Desktop opens on its Extensions screen. Click Install.

On macOS, downloaded files are quarantined and can refuse to open. If double-clicking does nothing:

xattr -dr com.apple.quarantine ~/Downloads/DarwiniumPortalMCP-*.mcpb

Option B: `npx`

Requires Node.js 20 or newer.

npx -y @darwinium/portal-mcp install

The installer:

Writes a per-machine token to the platform app-data directory (0600 on macOS/Linux, ACL-locked on Windows).
Adds a darwinium-portal-mcp entry to claude_desktop_config.json, preserving every other MCP server configured. A .bak is written first.
Extracts a copy of the Chrome extension for the Load Unpacked path.
Prints a 6-digit pairing code and waits for it to be entered in the extension popup.

Restart Claude Desktop afterwards.

Chrome extension

Install from the Chrome Web Store. The listing is unlisted and reachable only by direct link.

Locked-down Chrome (Web Store blocked): load it unpacked.

Run npx -y @darwinium/portal-mcp install, which extracts the extension and prints its path (for example ~/Library/Application Support/darwinium-portal-mcp/extension on macOS).
Open chrome://extensions, turn on Developer mode, click Load unpacked, and select that folder.

Chrome warns about developer-mode extensions on every start. If Load unpacked fails, copy the folder to a path with no spaces and load that instead.

4. Install for Claude Code

Requires Node.js 20 or newer on PATH.

One-line install:

claude mcp add darwinium-portal-mcp -- npx -y @darwinium/portal-mcp serve

Add --scope user to make it available in every project rather than only the current directory.

Or as a plugin, from inside a session:

/plugin marketplace add darwinium-com/portal-mcp
/plugin install portal-mcp@darwinium

Both register the same server. Verify with claude mcp list, or /mcp inside a session, which should show darwinium-portal-mcp with three tools.

Then install the Chrome extension and pair, as in the sections above and below.

5. Running Claude through Amazon Bedrock with Guardrails

Portal data that Claude reads is sent to whichever AI service runs Claude for you. Darwinium recommends that organisations run Claude through Amazon Bedrock, with Amazon Bedrock Guardrails enabled. That keeps model traffic inside your own AWS account under your existing governance, and lets you filter or mask sensitive information in both what analysts ask and what Claude returns.

Amazon Bedrock Guardrails provides configurable safeguards across foundation models, including content filters, denied topics, word filters, and sensitive information filters that block or mask personally identifiable information such as names, addresses and account numbers in prompts and responses.

Which client to use. Claude Code supports Amazon Bedrock natively, so it is the client to standardise on for a Bedrock-only policy. Claude Desktop connects to Anthropic's own service and does not offer a Bedrock option.

Configuring Claude Code for Bedrock. Follow Anthropic's guide, Claude Code on Amazon Bedrock. In outline:

Enable Anthropic models in your AWS account from the Bedrock model catalog, and grant the IAM permissions listed in that guide.
Run claude, choose 3rd-party platform → Amazon Bedrock at the login prompt, and follow the wizard. Or set it manually:
```
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
```
Pin model versions before rolling out to a team.

Attaching a Guardrail. Create a Guardrail in the Bedrock console, publish a version, then add its headers to the Claude Code settings file:

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"
  }
}

Enable cross-Region inference on the Guardrail if you use cross-Region inference profiles.

The Darwinium Portal MCP server itself is unaffected by this choice. It sits between Claude and your browser and never sees which provider Claude is talking to.

Links

Claude Code on Amazon Bedrock, including the Guardrails section: https://code.claude.com/docs/en/amazon-bedrock
Amazon Bedrock Guardrails: https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html
Amazon Bedrock Guardrails product page: https://aws.amazon.com/bedrock/guardrails/
Claude on Amazon Bedrock: https://aws.amazon.com/bedrock/anthropic/
Anthropic's Bedrock reference: https://docs.claude.com/en/api/claude-on-amazon-bedrock

6. Pairing

The extension and the server are introduced once, using a locally generated token. Two delivery paths exist.

Ask Claude (.mcpb and claude mcp add installs). The server embeds the token in its MCP initialize instructions, so with the portal tab open the user starts a brand-new chat, asks "What is my Darwinium pairing token?", copies the 64-character token, clicks the portal tab, clicks the extension icon, pastes it, and clicks Save & Connect. It must be a new chat, because the token is delivered when a conversation opens.

6-digit code (npx install and rotate-token). The installer prints a boxed 6-digit code and opens a 60-second pairing window. The user types the six digits into the popup. Three attempts are allowed; press Enter at the prompt for a fresh code.

In both cases the extension binds to whichever tab is in front when Save & Connect is clicked. The popup then shows Connected with the tab URL, and the portal's title bar shows MCP Connected while the bridge is up. The portal also suspends its idle logout while connected.

7. Check your setup

npx -y @darwinium/portal-mcp doctor

Check	What it means
`binary.present`	The server is on disk and executable.
`token.mode`	Token file is mode `0600` (macOS/Linux).
`token.parent.mode`	Token's parent directory is mode `0700` (macOS/Linux).
`token.acl`	Token file ACL is locked (Windows only).
`config.desktop.entry`	Claude Desktop is registered, via `.mcpb` or a config entry.
`config.code.marketplace`	Claude Code plugin present. Warn-only.
`extension.reachable`	The extension's WebSocket accepted the token within 5 seconds.
`port.9224.bindable`	`127.0.0.1:9224` is free.
`git.token-tree-warning`	Warns if the token file sits inside a git working tree.

port.9224.bindable and extension.reachable show a cross on a healthy machine while Claude Desktop is running, because Claude Desktop itself holds the port and the live server. Quit Claude Desktop before treating them as faults.

For a support ticket:

npx -y @darwinium/portal-mcp doctor --json > doctor-output.json

8. The three MCP tools

Tool	What it does
`get_page_commands`	Read-only. Lists the page commands the active portal tab publishes, with descriptions and argument schemas. Claude calls this first and after navigating.
`run_page_command`	Runs one named page command with arguments. Optional `expected_page_id` rejects the call if the page changed. Not read-only: the command surface includes label, dashboard and workflow writes.
`get_context`	Read-only. Returns Darwinium's query-writing instructions plus the current page's context: attribute contexts, step names, signal and feature names for the workspace. Capped at 50 KB with lower-priority fields dropped first.

The surface is fixed at three because Claude Desktop and Claude Code cache the tool list and do not honour change notifications. Dynamic discovery underneath a stable surface is the design that survives that.

Commands that return a screenshot come back as an image block, so Claude can look at the result rather than describe it.

9. Page command reference

Commands are grouped by where they are available. Descriptions are condensed from the portal's own command registry.

Available on every page

Command	Purpose
`searchAttributes`	Search the attribute catalog by name, description or value. Returns syntax, type, examples and possible values.
`getDarwiniumQueryContext`	Attribute contexts, step names, feature, signal and journey names, and per-journey feature explanations.
`listStepNames`	The journey vocabulary for this instance: step, journey, feature, signal and model names, event types.
`validateAndCountEvents`	Syntax-check a query and return the count of matching events over the last 30 days.
`runTopXQuery`	Top-N breakdowns. The engine behind Top X cards; the arguments map onto card settings.
`runAggregateStat`	A single aggregate (count distinct, sum, avg, quantile) over events.
`runAttributeFlowQuery`	How events flow between attribute values, the engine behind Attribute Flow (Sankey) cards.
`runSignalTriggerRateQuery`	One row per journey, step and signal with trigger count, rate, and previous-period comparison.
`probeAttributeCoverage`	Whether an attribute is actually populated, and its most common values.
`getQuantileDistribution`	The population distribution behind a feature or numeric attribute, with values at each percentile.
`getJourneyMetadata`	The compiled policy for a journey: steps, features, models, signals with scores and conditions, version-pinned by commit hash.
`listLabelCatalog`	Every label with category and disposition, plus label contexts grouped by group.
`findLabels`	Current labels on identifiers (device, IP, email, login), filtered by expression, label names, categories or contexts.
`addLabel`	Attach a label to identifiers. Writes durable state read by rules at decision time.
`removeLabel`	Tombstone a label by UUID. Writes durable state.
`captureScreenshot`	Screenshot the board, a card by title, or any element.
`openDashboards`, `openInvestigations`, `openWorkflows`, `openLabels`	Navigate. `openInvestigations` can preload a query and date range.
`runInvestigationQuery`	Navigate to Investigations, preload a query, and execute it.

Dashboards page

Command	Purpose
`listSpaces`	Spaces and their boards, with whether the session can save to each.
`getBoard`	Panels, cards with addressing, and the current time range.
`listAvailableCardTypes`	Component names a card may use, and which need settings.
`verifyDashboardState`	Re-read a space from the server and compare with the tab.
`createSpace`, `upsertBoard`, `renameBoard`, `deleteBoard`	Space and board management. Deletes require the title to be confirmed.
`addCard`, `updateCard`, `deleteCard`, `moveCard`	Card management. Settings are validated on write.
`addPanel`, `deletePanel`, `addTab`, `deleteTab`, `setPanelLayout`	Side panels, tabs and grid templates.

Investigations

Tab	Commands
Query	`setQuery`, `runCurrentQuery`, `getCurrentQueryResults`, `getTableData`, `getTableRowCount`, `selectEvents`, `getSelectedColumns`, `selectColumns`, `listGraphNames`, `getGraphDataByName`, `getGraphScreenshotByName`, `getCurrentNodeContext`
Journey	`getTimelineData`, `getTimelineScreenshot`, `selectTimelineEvents`, `updateTimelineSettings`, `getGridScreenshot`, `getTableData`, `getTableRowCount`, `selectEvents`, `getCurrentNodeContext`
Identifier	`getGraphData`, `getGraphScreenshot`, `getGridScreenshot`, `getBoardScreenshot`, `getTimelineScreenshot`, `getTableData`, `getTableRowCount`, `selectEvents`, `getCurrentNodeContext`
Event detail sidebar	`getEventDetail`

Workflows

Command	Purpose
`getWorkspaceFiles`, `getActiveEditor`, `setActiveEditor`	Navigate the policy workspace.
`getContent`, `setContent`	Read and write a file. Writes durable state.
`getCommands`, `executeCommand`	Editor commands.
`getWorkspaceProblems`	Language-server diagnostics. Claude runs this before and after edits.

10. Troubleshooting

Claude says the extension is not connected. Click the toolbar icon. If it shows Disconnected, click Connect with the portal tab in front. After a sleep/wake, auto-reconnect can take up to 30 seconds.

Claude does not know what a pairing token is. Start a brand-new chat. If a new chat still does not know, the server is not registered: check Settings → Extensions in Claude Desktop, or claude mcp list.

The tools vanish, or the server disconnected. Only one client can hold the bridge. Quit every other client, including Claude Code in a terminal, then quit Claude Desktop fully (Claude → Quit) and reopen.

Popup says "Token mismatch". The token was rotated. Click Re-pair and paste the current token.

Popup says "Cannot reach the MCP bridge". The server is not running. Open Claude Desktop or start a Claude Code session, then click Connect.

Claude connects but says the page is not ready. Reload the portal tab.

Port 9224 already in use.

lsof -i :9224                  # macOS / Linux
netstat -ano | findstr :9224   # Windows

It worked yesterday, broken today (npx path). Stale npm cache. npx clear-npx-cache or npm cache clean --force, then re-run doctor.

claude_desktop_config.json is not valid JSON. Fix the syntax or delete the file, then re-run install. The previous config is at claude_desktop_config.json.bak.

Rotating the token.

npx -y @darwinium/portal-mcp rotate-token

The old token stops working immediately and the popup offers Re-pair.

Errors Claude may report

Error	Meaning	Fix
`No tab connected`	Popup shows Disconnected.	Open a portal tab and click Connect.
`Connection lost mid-call`	The extension dropped during the call.	Wait up to 30 seconds and retry.
`Page navigated mid-call`	You navigated during the call.	Retry from the new page.
`Token mismatch`	Extension token differs from the server's.	`rotate-token`, then re-pair.

Send doctor --json output to support@darwinium.com or open an issue at https://github.com/darwinium-com/portal-mcp/issues.

11. Privacy and security

Darwinium collects nothing through this software. No analytics, telemetry, crash reporting, or backend of its own.
No Darwinium credentials are stored. All data access happens inside the portal tab using the user's existing session and permissions.
The only network destination either component opens is ws://127.0.0.1:9224.
Portal data goes to the AI provider, not to Darwinium. See section 5 for keeping that traffic inside your AWS account with Guardrails.
The pairing token authorises only the loopback WebSocket. It is not a Darwinium credential, never appears in any config file, and never leaves the machine. It is stored with owner-only permissions in the app-data directory and in the extension's local storage.
Extension scope is locked to https://*.darwinium.com/* and https://*.int.darwinium.io/*. Other permissions: storage (token and popup history), tabs (which portal tab is active), alarms (keepalive and reconnect), scripting (re-injecting into open portal tabs after an update).
Writes are explicit. Commands that change state are described as such to Claude, which confirms before running them.
Revoke at any time: Disconnect in the popup, remove the extension, or run rotate-token.

Full policy: https://www.darwinium.com/privacy-policy. Product-specific detail: https://github.com/darwinium-com/portal-mcp/blob/main/docs/privacy.md.