Team Collaboration on a Shared Model

This guide walks through a complete multi-analyst workflow: adding teammates to a model, working on separate scenario branches, and merging reviewed changes into the main branch.

Prerequisites

A Bridge Town model with at least one model script
Owner role on the model (required to manage collaborators)
Teammates’ email addresses
An active Pro subscription (required to invite new collaborators)

Step 1 — Invite collaborators

You can invite someone to a model directly, or add them to the workspace first and then grant model access. Both paths use MCP tools with worked examples below.

Model invites

Ask Claude to invite your teammates, or call invite_model_collaborator directly.

{
  "name": "invite_model_collaborator",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "email": "colleague@example.com",
    "role": "editor"
  }
}

What happens next depends on whether the invitee is already in your workspace:

Existing workspace member — access is granted immediately. The colleague can start working right away. workspace_invite will be "already_active".
New to the workspace — a pending model grant and workspace invitation are created. The invitee receives a workspace invite email. When they sign up, both grants activate automatically. workspace_invite will be "created".

Invited collaborators appear in list_model_collaborators. Pending entries have pending: true and no user_id.

Workspace invites

If you want a teammate to join your workspace before assigning them to models, use invite_workspace_member:

{
  "name": "invite_workspace_member",
  "arguments": {
    "email": "colleague@example.com",
    "role": "member"
  }
}

Workspace roles define the tenant-level boundary:

Workspace role	What they can do
`member`	Access models they are explicitly granted to; create their own models
`admin`	Everything a member can do plus manage workspace settings, billing, and invite other admins
`owner`	Full control including deleting the workspace

A workspace invite does not grant model access automatically. After the user accepts the workspace invite, an owner or editor must still call invite_model_collaborator to give them access to specific models.

Roles

Role	What they can do
`viewer`	Read models, branches, pull requests, and history
`editor`	Everything above plus create branches, models, and pull requests
`owner`	Everything above plus manage collaborators, merge PRs, publish templates

Step 2 — Work on a scenario branch

Each analyst works on their own branch to avoid conflicts on main.

{
  "name": "create_branch",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "branch_name": "feature/updated-assumptions",
    "base_branch": "main"
  }
}

On the branch, make model changes with patch_file or update_file. Run the model with run(scope='model', mode='sync') to validate the changes.

Step 3 — Open a pull request

When the branch is ready for review, open a pull request.

{
  "name": "create_pull_request",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "title": "Update Q2 growth assumptions",
    "head_branch": "feature/updated-assumptions",
    "body": "Changed YoY growth from 15% to 18% based on pipeline data. Run outputs attached."
  }
}

The PR is now visible to all model collaborators via list_pull_requests.

Step 4 — Review the pull request

A collaborator with at least Editor role reviews the PR.

{
  "name": "get_pull_request",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "pull_request_id": 1
  }
}

The response includes diff (the model code changes) and approvals (list of reviewers who have approved).

To approve:

{
  "name": "review_pull_request",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "pull_request_id": 1,
    "event": "approve",
    "body": "Assumptions look right — growth rate is in line with pipeline. LGTM."
  }
}

To request changes instead of approving, use event: "request_changes". To leave a neutral comment without blocking or approving, use event: "comment".

Step 5 — Merge the pull request

Once the PR has at least one approval, an Owner can merge it.

{
  "name": "merge_pull_request",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "pull_request_id": 1,
    "style": "squash"
  }
}

Merge styles:

merge — merge commit preserving full branch history (default)
squash — squash all commits into one clean commit on main
rebase — rebase head branch commits onto base branch

After merging, the head branch can be deleted with delete_branch.

Step 6 — View model activity

Collaboration events such as grants, PR opens, reviews, and merges are recorded as activity events. They appear in the activity feed of anyone who follows the acting user. Open /dashboard in the web app, or call GET /api/feed, to see activity from people you follow.

GET /api/feed returns two separate sections:

items — reverse-chronological activity events from users you follow.
notifications — undismissed invite notifications for workspace or model invites sent to you. Each notification includes a cta_url link to accept the invite or open the model.

To dismiss an invite notification once you have acted on it, call DELETE /api/notifications/{notification_id}.

Managing collaborators

Change a role

{
  "name": "change_collaborator_role",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "target_user_id": "uuid-of-collaborator",
    "role": "viewer"
  }
}

Use list_model_collaborators to find the user_id of the collaborator you want to update.

Remove a collaborator

{
  "name": "remove_model_collaborator",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "target_user_id": "uuid-of-collaborator"
  }
}

To cancel a pending invite before the invitee signs up, use the grant_id returned when you invited them:

{
  "name": "cancel_model_invite",
  "arguments": {
    "model_name": "q2-revenue-forecast",
    "invite_id": "grant-id-from-invite-response"
  }
}

Reusing models as templates

If your team has built a model that others should be able to start from, publish it as an internal template in the web app or through the Admin and Security API/CLI. Template governance is outside MCP.

Any workspace member can then create a new, independent model from the template:

{
  "name": "create_model_from_template",
  "arguments": {
    "template_model_name": "standard-lbo-model",
    "new_model_name": "deal-alpha-lbo",
    "description": "Deal Alpha acquisition model"
  }
}

The new model is independent — changes to it do not affect the template, and changes to the template do not affect existing clones. The template_source field in the response records provenance.

Notifications

In-app invite notifications

When you are invited to a workspace or model, an in-app notification appears on your /dashboard page under the notifications section. Each notification shows the workspace or model name, your intended role, and a link (cta_url) to accept the invite or open the model. Notifications remain visible until you dismiss them using DELETE /api/notifications/{notification_id}.

In-app notifications are created when:

A workspace owner invites you by email and you already have a Bridge Town account.
A model owner grants you model access (active grant for workspace members, or pending grant for registered users who are not yet workspace members).

Email notifications

Bridge Town also sends email notifications for key events:

Workspace invite — invitees receive a signup/login link by email when a workspace invite is created.
Model access granted — active collaborators receive an email when they are granted model access.
Review requested — when a new pull request is opened, all model collaborators (except the PR author) receive a notification.
PR merged — the PR author receives a notification when their pull request is merged.

Email notifications are sent to the invitee’s registered address.

What’s not supported yet

Direct git clone of a model’s Git repository
SSH access or personal access tokens for local Git operations

All collaboration is handled through the MCP tools and the Bridge Town web UI.