# 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 ` 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 1. Open the MCP page's **Keys** tab, or select **My MCP keys** in the profile menu. 2. Under **Create a key**, give it a **Name** that says where it is used, such as "Claude Code on my laptop". 3. Under **Workspace**, choose **All my workspaces** or one workspace. 4. Under **Access**, choose **Viewer** (read only) or **Editor** (read and change). You can only choose Editor if you are an Editor or Administrator yourself. 5. Under **Expires after**, choose 7, 30 or 90 days. Keys for a Free team last at most 7 days. 6. 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 `` with your key, or copy the filled-in setup from the **Connection** tab. Never commit a key to a repository. ### Claude Code ```bash claude mcp add --transport http archibara https://app.archibara.com/mcp --header "Authorization: Bearer " ``` 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): ```toml [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: ```bash export ARCHIBARA_MCP_TOKEN="" ``` 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. ```json { "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: ```json { "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 " } } } } ``` ### Other clients Clients that support Streamable HTTP with custom headers usually accept this shape; some call the top-level key `servers`: ```json { "mcpServers": { "archibara": { "type": "http", "url": "https://app.archibara.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ## 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](/docs/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](https://archibara.com/pricing/) 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.