# Teams and Access Control

Teams group members of an MCP Gateway project and let you assign each Virtual
MCP server to one or more teams. A team has a name, an icon, and a list of
members with roles. A team can also have **sub-teams**, which form a tree the
project owner can use to mirror an organizational structure.

This page covers how teams are modeled, how to create and manage them in the
portal, and how to assign teams to a Virtual MCP server.

:::note

Teams provide the grouping and Virtual MCP assignment surface that gateway
admins use to plan access. **Runtime enforcement of team membership at the OAuth
layer is a near-term roadmap item.** Today, the gateway accepts any
authenticated user; you can scope each Virtual MCP to one or more teams in the
Portal in preparation for RBAC enforcement, but the gateway does not block users
from teams that aren't assigned. For tool-level curation today, configure a
[capability filter](./capability-filtering.mdx) on the route.

:::

## The team model

Each team in an MCP Gateway project has:

- **Name** — the label shown in the team tree and in the Teams selector on each
  Virtual MCP card.
- **Icon** — a visual marker chosen from the icon picker, useful for telling
  teams apart at a glance.
- **Parent team (optional)** — when set, the team is a sub-team rendered
  underneath its parent in the team tree. Sub-teams can themselves have
  sub-teams; there's no hard cap on depth.
- **Members** — project users who belong to the team, each with a role.

The team tree, the roles, and the team-to-Virtual-MCP assignments all live on
the project. They're scoped to a single MCP Gateway project; teams aren't shared
across projects.

## Roles

A team member is assigned exactly one of three roles:

| Role        | Intended access to assigned Virtual MCPs | Can manage the team |
| ----------- | :--------------------------------------: | :-----------------: |
| `admin`     |                   Yes                    |         Yes         |
| `member`    |                   Yes                    |         No          |
| `no-access` |                    No                    |         No          |

The `developer` role used elsewhere in Zuplo isn't surfaced in MCP Gateway team
UIs. Members invited or assigned through the team flow only see admin, member,
and no-access as options.

Project admins inherit `admin` on every team in the project and can't be demoted
from a team's role selector.

The "intended access" column above describes the planned RBAC model. Enforcement
at the gateway runtime is on the near-term roadmap.

## Create a team

Open [**MCP Teams**](https://portal.zuplo.com/+/account/project/mcp/teams) in
the Zuplo Portal. From there:

1. Click **Create Team** at the top of the team list. If the project doesn't
   have any teams yet, the empty state shows **"Let's create your first team"**
   with the same button as the primary CTA.
2. In the **Create MCP Team** dialog, pick an icon and enter a **Team Name**.
3. Click **Create**.

The new team appears in the team tree on the left and its detail page opens on
the right.

### Sub-teams

To create a team underneath an existing team:

1. Open the parent team's detail page.
2. Click **Create Sub-Team** in the top-right.
3. Pick an icon, enter a name, and click **Create**.

The sub-team appears nested beneath the parent in the team tree. Sub-teams
behave identically to top-level teams — they have their own members, their own
roles, and their own Virtual MCP assignments. Membership and assignments do not
inherit between parent and sub-team; treat the relationship as a visual
grouping, not an inheritance.

## Add members to a team

On a team's detail page, the **Members** tab shows everyone in the project who
has any role on this team (anything other than `no-access`).

To add a new member:

1. Click **Add member**.
2. Enter the user's email and pick a role (`admin` or `member`).
3. Click **Send invite**.

The invite grants the user access to the account and project, then assigns them
to the team with the chosen role. They appear in the member list once they
accept.

To change an existing member's role, use the role selector next to their name.
Project-level admins are inherited as `admin` and can't be changed from this
view; remove them as a project admin first if you need to scope them down.

To remove a member from the team, set their role to **No access**. That removes
the team assignment but leaves their project membership intact.

## Assign a team to a Virtual MCP server

Today, **assign teams from the Virtual MCP side**. A per-team Virtual MCP view
is coming.

To grant a team access to a Virtual MCP server:

1. Open
   [**MCP Virtual MCP**](https://portal.zuplo.com/+/account/project/mcp/virtual-mcp)
   in the Zuplo Portal.
2. Find the Virtual MCP card and click the **Teams** chip in its footer (labeled
   **"N Teams"** when teams are already assigned or **"No Teams"** when none
   are).
3. In the **Teams** popover, check the teams that should have access. Indented
   entries are sub-teams.
4. Click **Save**.

The checked teams are the set of teams that will be allowed to connect to the
Virtual MCP once team-based enforcement ships. For now, treat the assignment as
the source of truth your admins use to plan access — gate runtime tool exposure
with a [capability filter](./capability-filtering.mdx) on the route until then.

If the project doesn't have any teams yet, the popover shows **"No team created
yet. Create your first team to get started."** with a link to the team list.
Create the team first, then come back to assign it.

:::note

The Team detail page also exposes a **Virtual MCPs** tab. That tab is a
placeholder in the current release. Use the Virtual MCP → Teams flow above until
the per-team view ships.

:::

## Edit or delete a team

On a team's detail page, open the **Settings** tab. From here:

- Rename the team in the **Name** field and click **Save**.
- Delete the team using the **Delete Team** card at the bottom. Deleting the
  team removes its membership assignments and any links to Virtual MCP servers;
  project users are not removed from the project.

To change a team's icon, click the icon at the top of the team detail page and
pick a new one. Changes are saved immediately.

## Team copy that doesn't apply

A few strings on the Teams pages are leftovers from the related AI Gateway
product and don't describe MCP Gateway behavior:

- The empty-state team list mentions **"custom quotas and budgets"**. MCP
  Gateway teams **do not enforce quotas, budgets, or usage limits today**. Teams
  are an access-control grouping. For rate limiting, pair the gateway with the
  [`rate-limit-inbound`](../policies/rate-limit-inbound.mdx) policy on the
  route.
- The delete-team confirmation mentions **"apps"**. MCP Gateway has no apps
  concept. Deleting a team removes the team and its Virtual MCP assignments
  only.

Both messages will be updated as the product matures. Until then, treat the
described features as not implemented for MCP Gateway.

## How teams compose

A typical MCP Gateway project ends up with a small team tree that mirrors the
shape of the organization. For example:

```text
Acme Engineering
├── Backend
├── Frontend
└── Platform
    ├── Infrastructure
    └── Developer Experience
Acme Finance
Acme Operations
```

Each team gets its own slice of the Virtual MCP catalog. Backend and Frontend
might share access to a Linear Virtual MCP; only Platform → Infrastructure gets
access to the Grafana Virtual MCP; Finance gets exclusive access to a QuickBooks
Virtual MCP.

Plan team-to-Virtual-MCP assignments as a union: a user who is a `member` of any
team assigned to a Virtual MCP will be allowed to connect once runtime
enforcement ships. There's no allow vs. deny precedence.

## Reference

- [Virtual MCP Servers](./virtual-mcp-servers.mdx) — how Virtual MCPs are
  configured and where the per-VMCP Teams popover lives.
- [Origin MCP Servers](./origin-mcp-servers.mdx) — the upstream servers Virtual
  MCPs proxy to.
- For account-wide member management (the people who can be invited to teams at
  all), open
  [**Account Settings → Members**](https://portal.zuplo.com/+/account/settings/members)
  in the Zuplo Portal.