// Documentation

Connect your AI tools to ArtifactBridge

// Start here

MCP server URL

https://app.artifactbridge.com/mcp

Browser assistants

Runs in a tab. Nothing to install.

Local tools

Runs on your computer. Set up from the terminal.

The desktop app is optional. It sets up your local tools and stays in your menubar. Install the desktop app ↗

Browser assistants

These run in a browser tab and reach ArtifactBridge from the vendor's cloud, so there is nothing to install. Most ask for the MCP server URL, then sign you in; ChatGPT uses its official app instead. Several need an administrator to add the connector, noted in each section. Your workspace's app permissions still apply.

Assistants assume production unless you or an explicit target specify otherwise. They verify workspace access, but do not ask you to confirm production after a successful connection. Existing approval requirements still apply. Self-hosted or on another deployment? Copy that deployment's endpoint from Settings → Connect AI tools instead.

Claude

Official steps: Anthropic ↗

Claude on claude.ai and Claude Desktop both use these Customize → Connectors steps. Claude Code is the local CLI under Claude Code.

  1. 01

    Open Customize → Connectors

  2. 02

    Select + then Add custom connector

  3. 03

    Paste the URL below, select Add, then sign in when Claude asks

    MCP server URL

    https://app.artifactbridge.com/mcp

    Paste it where Claude asks for a custom MCP server.

  4. 04

    Set tool permissions (optional)

    If Tool permissions is available for the ArtifactBridge connector, open the connector, then Tool permissions. Tools are grouped, for example read-only versus write or delete. Set read-only tools to Always allow so Claude can look up documents without asking each time. Keep write, delete, and other consequential tools on Needs approval. Blocked stops Claude from using that tool.

    On Team and Enterprise, an owner can set these levels for everyone, and members cannot override them. Anthropic documents these labels in Use connectors to extend Claude's capabilities ↗.

What Always allow does in a signed-in session

Always allow skips Claude's prompt for that tool. Your ArtifactBridge workspace permissions still follow the account you signed in with, and source systems such as Google Docs or Notion keep their own. Signing in also means the decisions run as you: when Claude calls a decision tool such as artifactbridge_accept_proposal, ArtifactBridge records the accept as your decision, and with Always allow Claude does not ask first. The same covers rejecting or applying proposals, redline decisions, and accepting import plans. Keep those tools on Needs approval unless you mean Claude to decide as you.

Any plan. A free account holds one custom connector. On Team and Enterprise an owner adds it first in Organization settings → Connectors.

↑ All tools

ChatGPT

Official listing: OpenAI ↗
  1. 01

    Open the official ArtifactBridge app using the link below

  2. 02

    Connect ArtifactBridge and sign in when ChatGPT asks

    When prompted, choose the target workspace.

  3. 03

    Select Try in chat to start using ArtifactBridge

    Taking the product tour? Clear any prefilled example and paste the same tour prompt into that chat. If you stay in the original chat, say Continue.

The official ArtifactBridge app connects to production and cannot be repointed. This guide does not document an alternate-deployment ChatGPT route. For a preview or self-hosted deployment, use a documented host that accepts your endpoint instead. Your workspace's app permissions still apply.

Open the ArtifactBridge app in ChatGPT ↗

↑ All tools

Gemini

Official steps: Google ↗
  1. 01

    Open business.gemini.google → Settings & help → Manage team → Connected apps

  2. 02

    Select Add MCP Server and paste the URL below

  3. 03

    Enable the connection; it starts disabled

MCP server URL

https://app.artifactbridge.com/mcp

Paste it where Gemini asks for a custom MCP server.

Gemini Enterprise only, and only an administrator. The consumer Gemini app has no field for a custom MCP server.

↑ All tools

Grok

Official steps: xAI ↗
  1. 01

    Open grok.com/connectors

  2. 02

    Select New Connector, then Custom

  3. 03

    Paste the URL below, then sign in when Grok asks

MCP server URL

https://app.artifactbridge.com/mcp

Paste it where Grok asks for a custom MCP server.

xAI documents custom MCP connectors for Business and Enterprise. A team admin provisions the connector before members use it.

↑ All tools

Perplexity

Official steps: Perplexity ↗
  1. 01

    Open Settings → Connectors and select + Custom connector

  2. 02

    Choose Remote, then name it and paste the URL below

  3. 03

    Set Authentication to OAuth 2.0 and Transport to Streamable HTTP, acknowledge the warning, then Add and sign in

MCP server URL

https://app.artifactbridge.com/mcp

Paste it where Perplexity asks for a custom MCP server.

Pro, Max, and Enterprise. In an organization an admin decides whether members may add their own.

↑ All tools

Le Chat

Official steps: Mistral ↗
  1. 01

    Open Connectors and select Add connector

  2. 02

    Switch to the custom MCP connector tab

  3. 03

    Name it, paste the URL below, then select Connect

MCP server URL

https://app.artifactbridge.com/mcp

Paste it where Le Chat asks for a custom MCP server.

An administrator adds the connector. On a personal plan the account owner is the administrator.

↑ All tools

Microsoft Copilot

Official steps: Microsoft ↗
  1. 01

    In the Microsoft 365 admin center, an administrator opens Copilot → Connectors and creates a custom connector

  2. 02

    Under Connect to MCP server, they enter the Base URL below and the authentication they set up

  3. 03

    After rollout, Copilot calls the server's tools from chat

MCP server URL

https://app.artifactbridge.com/mcp

Paste it where the connector asks for a custom MCP server.

Microsoft 365 Copilot. Copilot chat has no dialog for a pasted MCP server URL, so this is an administrator task.

↑ All tools

Local tools

These run on your computer or a remote machine. Add the server from the tool's command line or config file, then sign in; no desktop app is needed. Each command below carries the endpoint. Copy commands one at a time; some tools start sign-in as soon as you add the server.

Or let the desktop app do it: it finds the supported tools on this computer (Claude Code, Codex, Grok, OpenCode, and Hermes), sets each one up after you review the plan, and stays in your menubar. If you have it, skip to Did it work?

Claude Code

Official steps: Anthropic ↗

Claude in a browser tab or Claude Desktop uses the Claude connector steps. This section is the local CLI on your computer.

  1. 01 / ADD

    Add the server before you start Claude Code

    Run this once in your terminal, not inside a Claude Code conversation. --scope user makes the server available in every project; without it, Claude Code loads the server only in the folder you ran the command from.

    claude mcp add --transport http --scope user artifact-bridge https://app.artifactbridge.com/mcp

    Replace the endpoint if your deployment is self-hosted.

    Claude Code connects its servers when it starts. If Claude Code was already open, exit it, then run claude --continue to pick up the same conversation.

  2. 02 / SIGN IN

    Sign in

    In Claude Code, run /mcp, select artifact-bridge, and sign in in the browser.

  3. 03 / CHECK

    Check it worked

    Start a new conversation and send the check prompt under Did it work?

  4. 04 / GATEWAY

    Using a gateway or a custom base URL? Turn on tool search

    This step applies only when Claude Code reaches the model through a gateway or proxy, that is, when ANTHROPIC_BASE_URL is set. On the Anthropic API, tool search is on by default, so you can skip this step.

    Without tool search, Claude Code sends every ArtifactBridge tool definition to the model with every request, and these definitions use a large share of the context. With tool search, the model receives a short list of tool names first and loads the full definition of a tool only when it needs it. This makes each request much smaller.

    Set ENABLE_TOOL_SEARCH=true (or auto) before you start Claude Code. Export it in your shell, or add it under the env key of ~/.claude/settings.json so that it applies to every session.

    ~/.claude/settings.json

    {
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

    Merge the env key into your existing settings file, then start Claude Code.

Or let the desktop app do this for you: install the desktop app.

↑ All tools

Codex

Official steps: OpenAI ↗
  1. 01 / ADD

    Add the server

    Run this once in the shell you use Codex from.

    codex mcp add artifact-bridge --url https://app.artifactbridge.com/mcp

    Replace the endpoint if your deployment is self-hosted.

  2. 02 / SIGN IN

    Sign in

    If the add command already started sign-in, finish that flow. Otherwise, run this command if you still need to sign in. For a remote machine without a browser, use Codex over SSH below.

    codex mcp login artifact-bridge

    Sign in with your ArtifactBridge account and choose a workspace.

  3. 03 / CHECK

    Check it worked

    Start a new conversation and send the check prompt under Did it work?

  4. 04 / MODEL

    Using a custom or unlisted model? Expect the full catalog

    Codex decides how it loads MCP tools from the metadata of the model you configure. The models in Codex's own model list carry this metadata, and Codex then loads an ArtifactBridge tool definition only when the model needs that tool. A custom provider with a model slug that Codex does not know has no metadata. Codex then sends every ArtifactBridge tool definition to the model with every request. To avoid it, use a model that has Codex model metadata.

Or let the desktop app do this for you: install the desktop app.

↑ All tools

Codex over SSH or on a headless machine

If Codex reports Browser launch failed, use your local browser to sign in. Choose the SSH tunnel below, or send the failed browser callback with curl.

The browser returns to a loopback callback address after sign-in. On your laptop, 127.0.0.1 means your laptop, not the remote machine running Codex. An SSH tunnel forwards that callback to Codex without exposing the port publicly.

  1. Keep the remote login process running. If codex mcp add already displayed an authorization link, use that flow; do not start a second login. If it exited or timed out, run codex mcp login artifact-bridge on the remote machine and use the new link.

  2. Find redirect_uri in the current authorization link. For a callback such as http://127.0.0.1:43123/callback, the port is 43123. The value may be URL-encoded, with %3A for : and %2F for /. Use the port from your current link, not this example. Do not change the authorization URL or its callback address.

  3. In a separate terminal on the computer with your browser, run the command below. Replace both PORT values with that callback port and YOUR_SSH_HOST with the SSH destination you use to reach the machine running Codex. This command applies to a 127.0.0.1 callback.

    Run on the computer with your browser

    ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:PORT:127.0.0.1:PORT YOUR_SSH_HOST

    Replace PORT and YOUR_SSH_HOST before running. Keep this terminal open until sign-in finishes.

    A connected tunnel normally waits without output. If SSH reports a port or forwarding error, resolve it before opening the link; do not substitute a different local port.

  4. Open the current authorization link in your local browser, sign in, and choose your workspace. Wait for the remote Codex command to confirm authentication. Then close the tunnel with Ctrl+C and use Did it work? to verify an authenticated read from the intended workspace. An added server or a browser success page alone does not prove the connection works.

If Codex runs inside a container, the tunnel must reach the callback listener inside that container. Forwarding to the host alone may not reach it. Use your environment's private port-forwarding support or ask its administrator; do not expose the callback on a public interface.

Alternative: send the callback with curl

You can finish sign-in without an SSH tunnel if you have a second terminal in the same machine or container as Codex. Keep the original login process running.

  1. Open the authorization link in your local browser and complete sign-in. When the browser cannot reach the loopback callback, copy the full URL from its address bar, including the query string. Use the failed callback URL, not the original authorization link.

  2. Check that the callback host, port, and path match the redirect_uri for this pending login. In the second remote terminal, run:

    curl -q --config -

    At curl's waiting input, enter the following line, replacing the placeholder with the full callback URL inside the quotes. Press Enter, then Ctrl+D.

    url = "PASTE_FULL_CALLBACK_URL_HERE"

    This sends the callback to Codex. Reading it from standard input keeps the URL out of shell history and command-line arguments; it can still appear in terminal scrollback or recordings.

  3. Wait for the original Codex login command to confirm authentication, then verify an authenticated read using Did it work?. If the login expired or exited, start a new login and use its new authorization link. Do not reuse an old callback.

Do not paste authorization links, callback URLs, codes, or tokens into an AI conversation or a support ticket. Keep them in your own browser and terminal.

↑ Codex setup

Grok Build

Official steps: xAI ↗
  1. 01 / ADD

    Add the server

    Run this once in the shell you use Grok Build from.

    grok mcp add --transport http artifact-bridge https://app.artifactbridge.com/mcp

    Replace the endpoint if your deployment is self-hosted.

  2. 02 / SIGN IN

    Sign in

    Complete the browser sign-in when Grok asks. Grok handles the OAuth flow.

  3. 03 / CHECK

    Check it worked

    Start a new conversation and send the check prompt under Did it work?

Or let the desktop app do this for you: install the desktop app.

↑ All tools

OpenCode

Official steps: OpenCode ↗
  1. 01 / ADD

    Add the server to your config

    OpenCode reads remote servers from opencode.json. Add this entry under mcp (the URL is already in it).

    opencode.json

    "artifact-bridge": {
  "type": "remote",
  "url": "https://app.artifactbridge.com/mcp",
  "enabled": true
}

    Replace the URL if your deployment is self-hosted.

  2. 02 / SIGN IN

    Sign in

    Run this to complete the browser OAuth flow.

    opencode mcp auth artifact-bridge

    Opens a browser window to sign in and choose a workspace.

  3. 03 / CHECK

    Check it worked

    Start a new conversation and send the check prompt under Did it work?

Or let the desktop app do this for you: install the desktop app.

↑ All tools

Hermes

Official steps: Nous Research ↗
  1. 01 / ADD

    Add the server

    Run this on the machine and profile that runs Hermes.

    hermes mcp add artifact-bridge --url https://app.artifactbridge.com/mcp --auth oauth

    Replace the endpoint if your deployment is self-hosted. --auth oauth tells Hermes to sign in through your browser.

  2. 02 / SIGN IN

    Sign in

    Run this to complete the browser sign-in, then run /reload-mcp in an open conversation to load the tools.

    hermes mcp login artifact-bridge

    Sign in with your ArtifactBridge account and choose a workspace.

  3. 03 / CHECK

    Check it worked

    Start a new conversation and send the check prompt under Did it work?

Or let the desktop app do this for you: install the desktop app.

To let your whole workspace hand Room tasks to a Hermes agent, see Connect Hermes as a shared agent. That setup uses A2A and a plugin, not this sign-in.

↑ All tools

Gemini CLI

Official steps: Google ↗
  1. 01 / ADD

    Add the server

    Run this once in the shell you use Gemini CLI from.

    gemini mcp add --transport http artifact-bridge https://app.artifactbridge.com/mcp

    Replace the endpoint if your deployment is self-hosted.

  2. 02 / SIGN IN

    Sign in

    In the Gemini CLI session, run /mcp auth artifact-bridge and sign in in the browser. Use /mcp to check the server's status.

  3. 03 / CHECK

    Check it worked

    Start a new conversation and send the check prompt under Did it work?

The desktop app does not set up Gemini CLI. Add it with the command above.

↑ All tools

Any other MCP client

Using a tool that is not listed above? Most MCP clients read a mcpServers map. Paste this config; it names the same endpoint and carries no token, and the client signs you in on first connect. Change the name or URL if your deployment is self-hosted.

mcpServers config

{
  "mcpServers": {
    "artifact-bridge": {
      "type": "http",
      "url": "https://app.artifactbridge.com/mcp"
    }
  }
}

Paste it into the client's MCP config file.

Cursor reads this map from its mcp.json file. On first connect, Cursor registers itself and opens the sign-in page in your browser.

↑ All tools

Connect an external A2A service

A workspace member can register an external agent that speaks the A2A protocol over HTTPS (JSON-RPC binding) in Settings → Agent Sharing (the in-product name for the feature the API and configuration keys call Agent Gateway). ArtifactBridge validates the service's Agent Card and endpoint before it publishes the service, keeps a sanitized copy of the card, and issues the service one credential. The service uses that credential only to obtain short-lived access for a specific delegated task. If the service needs its own bearer token, ArtifactBridge stores it encrypted and never shows it again.

Register a service

  1. Open Settings → Agent SharingSelect Add agent.
  2. Describe the agentEnter an agent name (the name it appears under in Rooms), the Agent Card URL (the agent's HTTPS origin on a public host, such as https://agent.example.com/; ArtifactBridge reads the card from .well-known/agent-card.json under it), the authentication the endpoint needs, and the concurrency limit. The default is 1; extra requests queue.
  3. Validate and publishSelect Validate & publish. If the card is unreachable or requires an unsupported feature, the URL field shows the reason and you can retry.
  4. Hand the credential to the runtimeCopy the service credential and the bootstrap URL from the one-time reveal and give them to the runtime that operates the service. The credential is shown once. The runtime presents it at the bootstrap URL, with the delegation locator it receives in each A2A request, to obtain a short-lived credential scoped to that one task.

What the runtime must do

Registering the Agent Card does not configure the runtime. For each delegated task the runtime, outside the model, must:

  1. Read the locatorEach A2A request carries a delegation locator in its request metadata (artifactbridge.delegation: the delegation id, the execution generation, and the bootstrap URL). The locator identifies the task; it grants nothing, and it is untrusted input from whoever sent the message.
  2. Bootstrap at the configured URL onlyKeep the bootstrap URL from the enrollment reveal in the runtime's configuration next to the service credential. Send the locator's delegation id and generation to that configured URL with the service credential as the bearer, over HTTPS, without following redirects. Ignore a locator whose bootstrap URL is not exactly the configured one: it is not a delegation from your ArtifactBridge, and the service credential must never be sent anywhere else. The reply is a short-lived credential, the task's scope, and the tools URL, which must be on the same origin as the bootstrap URL. Renew the credential the same way before it expires while the task legitimately runs on.
  3. Mount the tools for this task onlyConnect the tools URL as an MCP server with that credential as the bearer, isolated per task. The server exposes the delegation tools and the familiar ArtifactBridge tool names (join, read events, publish, upload an image, read, list and search documents, create, propose) restricted to that task's Room and scope. Every call is attributed to the shared agent. A posted event is not completion: the agent completes the A2A task, and its summary becomes the one task result, linked to what it posted.
  4. Discard the credentialWhen the task completes or is cancelled, drop the credential. ArtifactBridge revokes it on its side at completion, cancellation, disablement, Room closure, and every new execution generation.

Do not connect the same agent to /mcp with a personal token for the Rooms it serves as a shared agent. A personal connection acts as a second identity, and a task result it posts is a duplicate that never completes the delegation. Delegations to shared agents are executed by ArtifactBridge over A2A; they do not appear in any personal agent's action items or wakes. A runtime that cannot perform these steps cannot act inside a delegation; its A2A replies still complete the task. The repository ships a dependency-free reference implementation of steps 1, 2, and 4 (src/agent-gateway/runtime-bootstrap.ts) exercised by the reference agent in the test suite.

Running Hermes Agent? Use the ArtifactBridge plugin for Hermes instead of building these steps yourself. See Connect Hermes as a shared agent.

Manage a service

  • Every member sees the catalog with workspace-level counts (limit, running, queued). Private Room titles, briefs, and document contents are never shown on this page.
  • ArtifactBridge re-reads each service's Agent Card on a schedule. Descriptive changes (name, description, skills) are applied automatically and appear in the change history. A changed endpoint or security requirement is never applied automatically: the service shows Refresh stale with the cached card in use until the owner confirms the change. A service that stops answering shows Unreachable; no new work is sent to it until a later check passes, and queued work waits.
  • The owner who added the agent or a workspace admin can edit the description and concurrency, refresh the card, confirm a changed endpoint or token (running delegations keep the connection they started on), rotate the credential, and disable the service. Other members see View only.
  • Disabling a service blocks new work, cancels queued work, requests cancellation of running work, and posts a system update in each affected Room. Remote cancellation stays requested until the service responds or the five-minute cancellation deadline passes.
  • A published agent appears in a Room under its agent name once it has work there; the Room never shows its owner. Members delegate tasks by @-mentioning the agent in a Room message, or through their connected agent. See Delegate work to an external service.

Server setup

Agent Sharing needs two server settings: PUBLIC_BASE_URL, so the bootstrap and tools URLs given to services are absolute, and AGENT_GATEWAY_SECRET_KEY, a base64 32-byte key that encrypts stored service tokens. Without the key, registering a service that needs a token is refused with a clear message instead of storing the token in plain text. Two managed settings tune the coordinator: AGENT_GATEWAY_STATUS_CHECK_INTERVAL_SECONDS (default 60) sets how often running work is checked at the service, and AGENT_GATEWAY_CANCEL_DEADLINE_SECONDS (default 300) sets how long a cancel request waits for confirmation before it times out.

↑ All tools

Did it work?

If you are taking the Product tour, return to the same conversation and say Continue. If setup opened a new conversation, paste the same starting prompt you used before setup. Your assistant assumes production unless you specified another target, verifies workspace access, then recovers your saved tour progress before working on your private Welcome. Use the general check below when you are not taking the tour.

  1. Start a new conversation in the toolA conversation that was open before you connected does not see the server.
  2. Send the check promptCopy it below.
  3. Read the replyIt names the workspace you chose at sign-in and lists the documents you can open, or reports that the workspace has none yet. Either reply names the workspace, so it confirms the whole path works, even in a brand-new, empty workspace with no documents.

Verify in a new conversation

Read the current ArtifactBridge workspace name and list the documents I can access.

Send it in a new conversation.

What Settings can and cannot tell you

Settings → Connect AI tools shows the most recent request from any connected agent. It does not tell you which tool made it. A recorded request is not proof that the tool you just added connected, so check from that tool. Open Settings → Connect AI tools

↑ All tools

Manage access

Open Settings → Members & access → Access to see every connected tool and revoke one. Revoke the affected access if a device is lost or a tool should no longer connect. Removing a Skill does not revoke a credential. A second tool does not gain broader permission because the first one can read an item; access follows the identity that signed in.

Running without a browser, for example in CI? Use a workspace API token from the same page instead of sign-in, and inject it from a secret store. Never paste a token into a chat.