Team Collaboration on a Shared Project

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

Prerequisites

• A Bridge Town project with at least one model
• Owner role on the project (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 project directly, or add them to the workspace first and then grant project access. Both paths use MCP tools with worked examples below.

Project invites

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

{
  "name": "invite_project_collaborator",
  "arguments": {
    "project_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 project 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_project_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 projects, 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 projects they are explicitly granted to; create their own projects
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 project access automatically. After the user accepts the workspace invite, an owner or editor must still call invite_project_collaborator to give them access to specific projects.

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": {
    "project_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='project', 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": {
    "project_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 project 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": {
    "project_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": {
    "project_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".

Approval requirement

A pull request requires at least one approval from a collaborator other than the PR author before it can be merged. The PR author’s own approval does not count.

Step 5 — Merge the pull request

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

{
  "name": "merge_pull_request",
  "arguments": {
    "project_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 project 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.

Legacy redirect

The old /feed path still redirects to /dashboard for compatibility, but /dashboard is the current canonical location.

GET /api/feed returns two separate sections:

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

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": {
    "project_name": "q2-revenue-forecast",
    "target_user_id": "uuid-of-collaborator",
    "role": "viewer"
  }
}

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

Remove a collaborator

{
  "name": "remove_project_collaborator",
  "arguments": {
    "project_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_project_invite",
  "arguments": {
    "project_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.

{
  "name": "publish_project_template",
  "arguments": {
    "project_name": "standard-lbo-model",
    "template_description": "Standard LBO deal model with sensitivity tables"
  }
}

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

{
  "name": "create_project_from_template",
  "arguments": {
    "template_project_name": "standard-lbo-model",
    "new_project_name": "deal-alpha-lbo",
    "description": "Deal Alpha acquisition model"
  }
}

The new project 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.

Private collaboration vs. templates

Private collaboration (via invite_project_collaborator) gives named teammates ongoing shared access to the same project — all edits are live.

Templates (via create_project_from_template) create independent copies that start from the template snapshot. There is no ongoing link between the template and the clone.

Notifications

In-app invite notifications

When you are invited to a workspace or project, an in-app notification appears on your /dashboard page under the notifications section. Each notification shows the workspace or project name, your intended role, and a link (cta_url) to accept the invite or open the project. 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 project owner grants you project 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.
• Project access granted — active collaborators receive an email when they are granted project access.
• Review requested — when a new pull request is opened, all project 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 project repositories
• SSH access or personal access tokens for local Git operations

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