AI and help

MCP and AI clients

Connect Claude, Codex, GitHub Copilot or another MCP client to Archibara with a personal key, so an AI assistant can read and carefully update the same model you see.

Archibara has a built-in server for the Model Context Protocol (MCP). An AI client connected to it works on the semantic model itself, not on screenshots: it can list your workspaces, inspect objects, views and records, validate the model, and, with an Editor key, change it. Changes appear in every open browser right away, and every change is checked against your role and the model's rules and recorded in the activity log.

The endpoint

Setting	Value
Endpoint	`https://app.archibara.com/mcp`
Transport	Streamable HTTP
Authentication	`Authorization: Bearer <YOUR_KEY>` with a personal MCP key

Select MCP in the app header or the workspace toolbar to open the MCP page. Its Connection tab shows the endpoint and ready-made setup for each client, Keys manages your keys, and Reference lists every tool, resource and prompt.

Create a personal key

Open the MCP page's Keys tab, or select My MCP keys in the profile menu.
Under Create a key, give it a Name that says where it is used, such as "Claude Code on my laptop".
Under Workspace, choose All my workspaces or one workspace.
Under Access, choose Viewer (read only) or Editor (read and change). You can only choose Editor if you are an Editor or Administrator yourself.
Under Expires after, choose 7, 30 or 90 days. Keys for a Free team last at most 7 days.
Select Create key, then Copy key and store it somewhere safe, such as a password manager.

Keys start with arb_mcp_ and are shown only once. After you create one, the setup on the Connection tab contains it, ready to copy. Your keys lists your keys with when they were created, when they expire and when they were last used; Revoke key cuts a key off immediately.

A key for All my workspaces also reaches workspaces you join later, with your role in each.

Connect a client

Replace <YOUR_KEY> with your key, or copy the filled-in setup from the Connection tab. Never commit a key to a repository.

Claude Code

claude mcp add --transport http archibara https://app.archibara.com/mcp --header "Authorization: Bearer <YOUR_KEY>"

Then run /mcp in Claude Code to check the connection.

Codex

Add the server to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.archibara]
url = "https://app.archibara.com/mcp"
bearer_token_env_var = "ARCHIBARA_MCP_TOKEN"

Codex reads the key from an environment variable, so set it where Codex starts:

export ARCHIBARA_MCP_TOKEN="<YOUR_KEY>"

Codex Desktop, the Codex CLI and the IDE extension share this configuration.

VS Code with GitHub Copilot

Save this as .vscode/mcp.json. VS Code asks for the key when the server first starts and stores it outside the file. Then use Copilot Chat in Agent mode.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "archibara-mcp-key",
      "description": "Archibara MCP key",
      "password": true
    }
  ],
  "servers": {
    "archibara": {
      "type": "http",
      "url": "https://app.archibara.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:archibara-mcp-key}"
      }
    }
  }
}

Claude Desktop

Claude Desktop connects through the third-party mcp-remote bridge, which needs Node.js 18 or newer. Merge this entry into claude_desktop_config.json and fully restart Claude Desktop:

{
  "mcpServers": {
    "archibara": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://app.archibara.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_KEY>"
      }
    }
  }
}

Other clients

Clients that support Streamable HTTP with custom headers usually accept this shape; some call the top-level key servers:

{
  "mcpServers": {
    "archibara": {
      "type": "http",
      "url": "https://app.archibara.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_KEY>"
      }
    }
  }
}

What an AI client can do

The Reference tab lists every tool with a short description and whether it reads or writes. In groups:

Orientation: modeling_guide explains the modelling rules, allowed values and the recommended workflow; workspace_list, workspace_get and workspace_inspect find a workspace and read a complete, AI-oriented summary of it.
Reading the model: model_get, view_list, view_get, boundary_list and record_list read objects, connections, views, groups and records; model_validate runs the same validation as the Issues panel; explore_dependencies follows connections up to 20 hops.
Changing the model: model_preview_operations runs a batch of changes through the real rules and rolls it back; model_apply_operations applies up to 500 operations as one change. Single-item tools create, update and delete objects, connections, groups, views and records, place objects on views, save layouts and run auto layout. workspace_update changes a workspace's name, description, validation mode, catalogs and flows.
History and export: snapshot_list and snapshot_create; export_json, export_drawio and export_mermaid.

Resources expose the same information for reading: the modelling guide, the workspace list, and each workspace with its inspection packet, model, views, single views and records. Six prompts start common tasks: Review architecture, Create presales architecture, Identify architecture risks, Identify unknowns, Review security and Review scalability.

Some actions stay in the app and are never offered to personal keys: creating or deleting workspaces, importing whole workspaces and restoring snapshots.

Point the assistant at something

Right-click a card or connection and select Copy reference for agent, or use Copy view reference in the view menu or Copy context for AI in the workspace menu. Paste the copied line into your prompt; the assistant resolves it to the exact object with reference_resolve, together with useful surrounding context.

Safety

Your keys, your rights. A key never has more access than you: every call uses the lower of the key's role and your current role in the target workspace, checked again on each call. If you lose access to a workspace, your keys lose it too.
Read-only keys stay read-only. A Viewer key is offered only reading tools.
No silent overwrites. Write tools accept the model revision the assistant last read. When it is given and someone has changed the same items since, the write is rejected and the assistant has to read the model again.
Preview first. The modelling guide tells assistants to try changes to several items with model_preview_operations, which checks them against the real rules without saving anything, before applying them.
Snapshots. model_apply_operations and catalog changes take an automatic snapshot first, so an Administrator can compare and restore. See History and snapshots.
A visible trail. Activity marks every change made through MCP with the source MCP and the name of the key's owner followed by "(MCP)".
Control. Revoke a key at any time. Workspace Administrators can see and revoke the keys that reach their workspace on Team access, Members' MCP keys.

MCP use counts towards the team's plan: reads and writes per month, and requests per minute for each key. The pricing page lists the allowances.

Troubleshooting

The client says the server needs authentication: check that the key is complete, has not expired and is sent as Authorization: Bearer followed by the key.
The client lists no write tools: the key has Viewer access. Create an Editor key if you need changes.
A call is refused for a workspace: the key is scoped to another workspace, you no longer have access to that one, or your role there is Viewer and the call would change something.
Start a new session with workspace_list, then workspace_inspect, to give the assistant its bearings.

View as Markdown