---
title: Build on Org and teams
description: Read and manage the organisation's teams, subteams and team members from code or an agent, over REST or MCP, with the same rules as Settings, Teams.
section: developers
order: 150
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/org/mcp.ts, services/nodejs-cloud/lib/org/teams.ts, services/nodejs-cloud/contracts/org-teams.ts, services/nodejs-cloud/contracts/org-teams-v1.schema.json, services/nodejs-cloud/lib/mcp/rest.ts]
features: []
---

An org has one tree of teams and subteams, shared by Tasks, Notes, People, Calendar and the other products. Each team
has members (people `user:<id>` and agents `agent:<id>`) with a team role, `admin` or `member`. Everything
**Settings → Teams** does is also an `org_team_*` MCP tool and a REST route under `/api/v1/org/teams`. Each tool calls
the same functions as the console, so the permission checks, the Tasks and Notes mirrors and the audit rows are the
same, with your credential as the actor.

The model itself (subteams, membership that flows down, private teams, teams synced from your identity provider) is
described in [Teams, subteams and roles](/docs/cloud/teams.md). This page covers calling it.

## What you can build {#build}

- **Teams from your HR system or org chart.** Create a team for each department (`POST /api/v1/org/teams`), nest
  subteams with `parentId`, and move them when the org chart changes (`POST /api/v1/org/teams/{teamId}/move`).
- **Onboarding and offboarding.** Add a new hire to their team (`org_team_member_add`) and take a leaver out of every
  team (`org_team_member_remove`). Members of a team are members of its subteams too, so one add is usually enough.
- **Team pickers in your own app.** Read the tree you are allowed to see (`GET /api/v1/org/teams`) and use a team's
  `id` when you create work in Tasks, Notes or Calendar.
- **An access review.** List each team's members with the ones they inherit from teams above
  (`GET /api/v1/org/teams/{teamId}/members?inherited=true`) and compare them with your directory.
- **A service agent that runs its own team.** Bind a team key to a service agent, make that agent a team admin, and
  let it manage that team and its subteams without a person's key.

## At a glance {#glance}

Generated from the code on every docs build.

| | |
|---|---|
| MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/org`, server name `venom-org` |
| Connect | `claude mcp add --transport http venom-org https://cloud.usevenom.dev/workspace/mcp/org` |
| MCP tools | 10 (3 read, 7 write) |
| OAuth scopes | `org:read` `org:write` |
| REST twin | 10 routes under `https://cloud.usevenom.dev/api/v1` |
| Webhook events | `org.team.created`, `org.team.updated`, `org.team.archived`, `org.team.member_added`, `org.team.member_removed` |

## Authentication and scopes {#scopes}

Who you act as depends on the credential:

- A **personal API key** acts as its member (`user:<id>`) with their org role. Org owners and admins manage every
  team. Anyone else manages only the teams they are an admin of, and their subteams. Everyone reads the teams that
  are not private, plus the private teams they are in. A read-only personal key only reads. If the member has left the
  org, the key is refused.
- A **team key bound to a service agent** acts as that agent (`agent:<id>`). It has no org role, so it manages only
  the teams the agent is an admin of. Its reads follow the same visibility rules.
- A **team key with no agent bound** has no member at all. It reads the teams that are not private and is refused
  every change.
- An **OAuth app** acts as the member who connected it. It needs `org:read` to use the tools at all and `org:write`
  to change anything, on top of that member's rights.

Some refusals come from the team, not the credential: a team that syncs from your identity provider refuses member
changes, a team keeps at least one admin once it has one, and a team cannot move under itself or one of its
subteams. A private team you may not see answers "No such team", the same as a missing one.

Over REST a refusal is `403`, a missing team `404`, a bad field `400`. Over MCP the tool returns an error with the
reason in words. See [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md).

## Worked example {#example}

Create a Platform subteam under Engineering and add a new hire to it as a member:

```bash
# Find Engineering's id in the tree
curl "$VENOM_CLOUD/api/v1/org/teams" -H "Authorization: Bearer $VENOM_API_KEY"

# Make the subteam (you become its first admin)
curl -X POST "$VENOM_CLOUD/api/v1/org/teams" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name": "Platform", "key": "PLAT", "parentId": "<engineering-team-id>", "description": "Build, deploy and runtime"}'

# Add a person to it
curl -X POST "$VENOM_CLOUD/api/v1/org/teams/<platform-team-id>/members" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"member": "user:<member-id>", "role": "member"}'
```

A person's id is their `clerk_user_id` from `admin_member_list`; an agent is `agent:<agent id>`. The same two changes over MCP, from any
client connected to `/workspace/mcp/org`:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "org_team_create",
              "arguments": { "name": "Platform", "key": "PLAT", "parentId": "<engineering-team-id>", "description": "Build, deploy and runtime" } } }
```

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "org_team_member_add",
              "arguments": { "teamId": "<platform-team-id>", "member": "user:<member-id>", "role": "member" } } }
```

Tools answer in compact markdown by default. Pass `"format": "json"` for the structured answer (the team, or the
team's direct members after a member change). Adding someone who is already in the team changes their role instead.

## Events {#events}

5 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)).

| Event | When |
|---|---|
| `org.team.created` | A team was created in the organisation (shared by Tasks, Chat, Notes and People): id, key, name, parent, whether it is private, and who. |
| `org.team.updated` | A team's name, key, parent, privacy or description changed: the team as it is now, and who. |
| `org.team.archived` | A team was archived (or restored: `archived` false), and who did it. |
| `org.team.member_added` | A person or agent joined a team: the team, the member's id, their role in it, and who added them. |
| `org.team.member_removed` | A person or agent left a team: the team, the member's id and who removed them. |

Every team change is in the org's audit log with the credential as actor: `org.team.created`, `org.team.updated`,
`org.team.moved`, `org.team.archived`, `org.team.unarchived`, `org.team.member_added`, `org.team.role_changed`,
`org.team.member_removed`, `org.team.left` and `org.team.synced` (a SCIM group sync). A caller that may read the audit
log can follow them with `admin_audit_list` and the action prefix `org.team`
(`GET /api/v1/admin/audit?action=org.team`); see [Build on Admin and the mesh](/docs/developers/admin.md).

## REST routes {#rest}

The REST twin: 10 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)).

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/org/teams` | The organisation's teams as a tree | `org_team_list` |
| POST | `/api/v1/org/teams` | Create a team, or a subteam with parentId | `org_team_create` |
| GET | `/api/v1/org/teams/{teamId}` | A team with its place in the tree, subteams and members | `org_team_get` |
| PATCH | `/api/v1/org/teams/{teamId}` | Rename a team, or change its description, key or private flag | `org_team_update` |
| POST | `/api/v1/org/teams/{teamId}/move` | Put a team under another team, or at the top with parentId null | `org_team_move` |
| POST | `/api/v1/org/teams/{teamId}/archive` | Archive a team, or bring it back with archived false | `org_team_archive` |
| GET | `/api/v1/org/teams/{teamId}/members` | A team's members, with those inherited from the teams above | `org_team_members` |
| POST | `/api/v1/org/teams/{teamId}/members` | Add a person (user:<id>) or an agent (agent:<id>) to a team | `org_team_member_add` |
| PATCH | `/api/v1/org/teams/{teamId}/members/{member}` | Make a team member an admin or a member | `org_team_member_role` |
| DELETE | `/api/v1/org/teams/{teamId}/members/{member}` | Take a person or agent out of a team | `org_team_member_remove` |

## MCP tools {#tools}

10 tools: 3 read, 7 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP.

| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
| `org_team_archive` | Archive a team | write | `org:write` | `POST /api/v1/org/teams/{teamId}/archive` |
| `org_team_create` | Create a team | write | `org:write` | `POST /api/v1/org/teams` |
| `org_team_get` | Read a team | read | `org:read` | `GET /api/v1/org/teams/{teamId}` |
| `org_team_list` | List the organisation's teams | read | `org:read` | `GET /api/v1/org/teams` |
| `org_team_member_add` | Add a member to a team | write | `org:write` | `POST /api/v1/org/teams/{teamId}/members` |
| `org_team_member_remove` | Remove a member from a team | write (destructive) | `org:write` | `DELETE /api/v1/org/teams/{teamId}/members/{member}` |
| `org_team_member_role` | Change a member's team role | write | `org:write` | `PATCH /api/v1/org/teams/{teamId}/members/{member}` |
| `org_team_members` | List a team's members | read | `org:read` | `GET /api/v1/org/teams/{teamId}/members` |
| `org_team_move` | Move a team | write | `org:write` | `POST /api/v1/org/teams/{teamId}/move` |
| `org_team_update` | Rename or change a team | write | `org:write` | `PATCH /api/v1/org/teams/{teamId}` |

Linking a SCIM group to a team is an admin tool, not an `org_team_*` one: `admin_sso_group_list` and
`admin_sso_group_team_set`, owners only ([Teams from your identity provider](/docs/cloud/teams.md)).

## Related {#related}

- [Teams, subteams and roles](/docs/cloud/teams.md): the model, org roles per product, private and synced teams.
- [Build on Admin and the mesh](/docs/developers/admin.md): members, invitations and the rest of the org's settings.
- [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md).
