github-org-identity MCP tools
Seven tools, registered in
mcp-server/src/index.ts,
implemented in
mcp-server/src/tools/roles.ts.
All operate on GitHub’s organization-roles REST surface
(/orgs/{org}/organization-roles/...). Three are read-only; four mutate
org-wide permissions and share a confirm-echo contract (see below).
Read tools
Section titled “Read tools”list_organization_roles
Section titled “list_organization_roles”List an org’s predefined and custom organization roles.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
Returns an array of { id, name, description, source, baseRole }.
list_role_teams
Section titled “list_role_teams”List the teams holding a given organization role.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
roleId |
number (integer) |
yes |
Returns an array of { slug, name }.
list_role_users
Section titled “list_role_users”List the users holding a given organization role, directly or via team membership.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
roleId |
number (integer) |
yes |
Returns an array of { login, assignment }. assignment is null when the
underlying GitHub API response omits the field (older API responses),
rather than being assumed "direct".
Write tools
Section titled “Write tools”Each write tool mutates org-wide permissions and requires the target
roleId twice, under two different field names: roleId and
confirmRoleId. If the two values don’t match, the call throws
confirmation_mismatch before any GitHub API request is made. See
explanation/org-identity-scope.md
for why this exists.
assign_team_role
Section titled “assign_team_role”Assign an organization role to a team.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
roleId |
number (integer) |
yes |
confirmRoleId |
number (integer) |
yes — must equal roleId |
teamSlug |
string |
yes |
Returns { org, roleId, teamSlug } on success (PUT to
/orgs/{org}/organization-roles/teams/{teamSlug}/{roleId}).
remove_team_role
Section titled “remove_team_role”Remove an organization role from a team.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
roleId |
number (integer) |
yes |
confirmRoleId |
number (integer) |
yes — must equal roleId |
teamSlug |
string |
yes |
Returns { org, roleId, teamSlug } on success (DELETE to
/orgs/{org}/organization-roles/teams/{teamSlug}/{roleId}).
assign_user_role
Section titled “assign_user_role”Assign an organization role to a user.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
roleId |
number (integer) |
yes |
confirmRoleId |
number (integer) |
yes — must equal roleId |
username |
string |
yes |
Returns { org, roleId, username } on success (PUT to
/orgs/{org}/organization-roles/users/{username}/{roleId}).
remove_user_role
Section titled “remove_user_role”Remove an organization role from a user.
| Parameter | Type | Required |
|---|---|---|
org |
string |
yes |
roleId |
number (integer) |
yes |
confirmRoleId |
number (integer) |
yes — must equal roleId |
username |
string |
yes |
Returns { org, roleId, username } on success (DELETE to
/orgs/{org}/organization-roles/users/{username}/{roleId}).
Errors
Section titled “Errors”On failure, a tool returns either a structured OrgIdentityError with one
of four codes — github_api_error (any non-2xx GitHub response, status
included), missing_scope (no resolvable GITHUB_TOKEN/gh auth token),
confirmation_mismatch (write tools only, roleId != confirmRoleId), or
feature_unavailable (the org is on a plan that doesn’t support
organization roles — a GitHub Enterprise Cloud feature — detected by a
plan check that runs before the underlying GitHub API request; an
indeterminate plan, including one the resolved identity can’t read, falls
through to the real endpoint instead of guessing) — or, for an error that
isn’t an OrgIdentityError instance (an unclassified failure that escaped
typing), the generic fallback { error: "github_api_error", message }.