Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@beyondidentity/mcp list all identities in the default realm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that gives AI agents direct access to the Beyond Identity API — no admin panel required. Agents can manage identities, groups, applications, SSO configurations, credentials, and every other Beyond Identity resource through natural tool calls.
The server auto-detects which Beyond Identity platform you're using from your API key and registers the appropriate tools:
Secure Access (v1): 104 tools for the modern platform
Secure Workforce (v0): 35 tools for the legacy platform
Add the server to your MCP client configuration:
{
"mcpServers": {
"beyondidentity": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@beyondidentity/mcp"],
"env": {
"API_KEY": "your-jwt-api-key"
}
}
}
}For EU region tenants:
{
"mcpServers": {
"beyondidentity": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@beyondidentity/mcp"],
"env": {
"API_KEY": "your-jwt-api-key",
"REGION": "EU"
}
}
}
}That's it. The server extracts your tenant ID from the JWT and determines the correct platform and base URL automatically.
Related MCP server: Britive MCP Server
Variable | Required | Default | Description |
| Yes | — | Beyond Identity API key (JWT). Obtained from the admin console under Settings > API Access. |
| No |
|
|
| No | (computed from platform + region) | Override the API host. Use for non-production environments (e.g. staging, local mock). When set, takes precedence over |
The server inspects your JWT at startup to determine which platform to target:
If the token contains a bi_t claim, you're on Secure Access (v1). The bi_t value is your tenant ID, and the server hits api-us.beyondidentity.com or api-eu.beyondidentity.com.
If there is no bi_t claim, the server falls back to the sub claim and targets Secure Workforce (v0) at api.byndid.com or api-eu.byndid.com.
Only one set of tools is registered per session. Agents never see version numbers or need to think about which platform they're on.
With 100+ possible tools, agents need a way to find the right one. The search_tools tool accepts a natural language query and returns the most relevant tools:
search_tools("add a user to a group")
→ add_group_members, create_identity, list_groups, ...It uses keyword matching, synonym expansion (user matches identity, app matches application, cred matches credential/passkey), and CRUD verb detection (create matches POST endpoints, delete matches DELETE endpoints).
On the v1 platform, every API path looks like /v1/tenants/{tenant_id}/realms/{realm_id}/.... The server injects tenant_id automatically from the JWT — agents never provide it. The realm_id is a required parameter on realm-scoped tools; agents call list_realms first to discover available realms.
On v0, paths are simpler (/v2/...) with no tenant or realm in the URL — the token handles tenant scoping.
The server validates your API key at startup with clear messages for common problems:
Not a JWT (wrong segment count)
Corrupted payload (bad base64 or invalid JSON)
Missing expected claims (bi_t or sub)
Invalid region value
At runtime, API errors are returned as structured tool results with HTTP status codes and error details, not thrown as exceptions that crash the conversation.
Tool | Description |
| Retrieve an existing tenant |
| Patch a tenant |
Tool | Description |
| List realms for a tenant |
| Create a new realm |
| Retrieve an existing realm |
| Patch a realm |
| Delete a realm |
Tool | Description |
| List groups for a realm |
| Create a new group |
| Retrieve an existing group |
| Patch a group |
| Delete a group |
| Add members to a group |
| Delete members from a group |
| List members for a group |
| List role memberships for a group |
Tool | Description |
| List identities for a realm |
| Create a new identity |
| Retrieve an existing identity |
| Patch an identity |
| Delete an identity |
| Batch delete identities |
| List group memberships for an identity |
| List role memberships for an identity |
Tool | Description |
| List roles for a resource server |
| Create a new role |
| Retrieve an existing role |
| Patch a role |
| Delete a role |
| Assign members to a role |
| Unassign members from a role |
| List members for a role |
| Assign scopes to a role |
| Unassign scopes from a role |
| List scopes for a role |
Tool | Description |
| List credentials for an identity |
| Retrieve an existing credential |
| Revoke a credential |
Tool | Description |
| List credential binding jobs for an identity |
| Create a new credential binding job |
| Retrieve an existing credential binding job |
| Revoke an active credential binding job |
| Create a new batch credential binding job |
| Retrieve an existing batch credential binding job |
| List results of a batch credential binding job |
Tool | Description |
| Create a new theme |
| Get the active theme |
| Retrieve an existing theme |
| Patch a theme |
Tool | Description |
| List applications for a realm |
| Create a new application |
| Retrieve an existing application |
| Patch an application |
| Delete an application |
Tool | Description |
| List authenticator configurations for a realm |
| Create a new authenticator configuration |
| Retrieve an existing authenticator configuration |
| Patch an authenticator configuration |
| Delete an authenticator configuration |
Tool | Description |
| List resource servers for a realm |
| Create a new resource server |
| Retrieve an existing resource server |
| Patch a resource server |
| Delete a resource server |
Tool | Description |
| List tokens |
| Revoke a token |
Tool | Description |
| List SSO configs for a realm |
| Create a new SSO config |
| Retrieve an existing SSO config |
| Update an SSO config |
| Delete an SSO config |
| Associate identities with an SSO config |
| Delete identities from an SSO config |
| List identities associated with an SSO config |
| Check if an identity is assigned to an SSO config |
| List SSO configs associated with an identity |
| Associate groups with an SSO config |
| Delete groups from an SSO config |
| List groups associated with an SSO config |
| List SSO configs associated with a group |
| Check if groups are associated with an SSO config |
| Get the SSO config ID for an application |
| Test an SSO config |
Tool | Description |
| List identity providers by realm |
| Create a new identity provider |
| Retrieve an identity provider |
| Update an identity provider |
| Delete an identity provider |
Tool | Description |
| Get flow type configuration |
| Update flow type configuration |
Tool | Description |
| List all SCIM users |
| Create a new SCIM user |
| Retrieve an existing SCIM user |
| Replace a SCIM user |
| Patch a SCIM user |
| Delete a SCIM user |
| List all SCIM groups |
| Create a new SCIM group |
| Retrieve an existing SCIM group |
| Patch a SCIM group |
| Delete a SCIM group |
| List all SCIM resource types |
| List all SCIM schemas |
| Retrieve the SCIM service provider configuration |
Tool | Description |
| List all groups for a tenant |
| Create a new group |
| Retrieve an existing group |
| Patch a group |
| Delete a group |
| List all users for a group |
| Add users to a group |
| Delete users from a group |
Tool | Description |
| List all users for a tenant |
| Create a new user |
| Retrieve an existing user |
| Update a user |
| Delete a user |
| List all groups for a user |
Tool | Description |
| Create a new credential binding job |
| Get a credential binding job |
Tool | Description |
| List passkeys |
| Delete a passkey |
| List passkey tags |
| Set passkey tags |
Tool | Description |
| Retire the intermediate tenant certificate |
Tool | Description |
| List all SCIM users |
| Create a new SCIM user |
| Retrieve an existing SCIM user |
| Replace a SCIM user |
| Patch a SCIM user |
| Delete a SCIM user |
| List all SCIM groups |
| Create a new SCIM group |
| Retrieve an existing SCIM group |
| Patch a SCIM group |
| Delete a SCIM group |
| List all SCIM resource types |
| List all SCIM schemas |
| Retrieve the SCIM service provider configuration |
bi-mcp/
├── openapi.yaml # Secure Access (v1) OpenAPI spec
├── openapi-v0.yaml # Secure Workforce (v0) OpenAPI spec
├── package.json
├── tsconfig.json
├── scripts/
│ └── generate.ts # Reads both specs, emits tool code
├── src/
│ ├── index.ts # Entry point — detects platform, registers tools
│ ├── config.ts # JWT validation, platform detection, region routing
│ ├── client.ts # HTTP client with auth and path param injection
│ ├── search.ts # search_tools implementation
│ ├── types.ts # Shared types (Platform, Region, Config, ApiError, ToolMeta)
│ └── generated/ # Auto-generated — do not edit
│ ├── v1-tools.ts # 104 Secure Access tool registrations
│ ├── v1-registry.ts # Tool metadata for v1 search
│ ├── v0-tools.ts # 35 Secure Workforce tool registrations
│ └── v0-registry.ts # Tool metadata for v0 search
└── dist/ # Compiled JS (gitignored)All tool definitions and HTTP handlers are auto-generated from the OpenAPI specifications. The generator (scripts/generate.ts) does the following:
Parses both YAML specs and dereferences all $ref pointers
Extracts every operation (path + HTTP method + operationId)
Converts each operationId to a snake_case tool name
Builds Zod input schemas from the OpenAPI request parameters and body definitions
Generates tool handler functions that call the ApiClient with the correct method, path, and parameters
Annotates read-only tools (GET) and destructive tools (DELETE) for MCP clients that surface this information
To regenerate after spec changes:
npm run generateThe generated files are committed to the repository so consumers don't need to run the generator themselves.
The ApiClient class (src/client.ts) handles:
Bearer token authentication on every request
Path parameter substitution — replaces {tenant_id}, {realm_id}, {identity_id}, etc. in URL templates
Tenant ID injection — on v1, the tenant ID from the JWT is inserted into every path automatically
Query parameter serialization — optional params are omitted, not sent as empty strings
Error normalization — HTTP errors are caught and returned as structured ApiError objects with status code, error code, and message
# Install dependencies
npm install --ignore-scripts
# Download fresh OpenAPI specs
curl -s https://developer.beyondidentity.com/api/v1/openapi.yaml -o openapi.yaml
curl -s https://docs.beyondidentity.com/api/v0/openapi.yaml -o openapi-v0.yaml
# Regenerate tool code from specs.
# Internally runs scripts/patch-spec.ts first, which applies known local
# workarounds for confirmed bugs in the upstream specs (e.g. SCIM body
# wrapping, /scim/v2/Groups/ trailing slash). The patch list lives in
# scripts/spec-patches.ts and is idempotent — re-running is safe.
npm run generate
# Type-check
npx tsc --noEmit
# Full build (generate + compile)
npm run build
# Run in development mode
API_KEY="your-key" npm run dev
# Run compiled build
API_KEY="your-key" npm startTo use a local clone of this repo instead of the published npm package, point your MCP client at the TypeScript source directly:
{
"mcpServers": {
"beyondidentity": {
"type": "stdio",
"command": "npx",
"args": ["tsx", "/path/to/bi-mcp/src/index.ts"],
"env": {
"API_KEY": "your-jwt-api-key"
}
}
}
}This runs the server from source via tsx — no build step required. Changes to src/ take effect immediately on the next MCP session. To point at a non-production environment, add BASE_URL:
{
"mcpServers": {
"beyondidentity": {
"type": "stdio",
"command": "npx",
"args": ["tsx", "/path/to/bi-mcp/src/index.ts"],
"env": {
"API_KEY": "your-jwt-api-key",
"BASE_URL": "http://localhost:8021"
}
}
}
}Add 1–1000 users to a group. Provide an array of user IDs. Requires the group to exist (use list_groups or create_group first). All-or-nothing: if any user ID is invalid, the entire operation fails.
Inputs: group_id (required), id, user_ids.
Create a credential binding job to provision a new passkey for a user. Specify the user_id and delivery method. The binding link is sent to the user or returned directly depending on the delivery method. Use list_users to find the user_id first.
Inputs: binding_job (required), ttl_seconds.
Create a new group. Requires display_name. Optionally include a description. Returns the new group with an auto-generated id. The group starts empty — use add_group_users to add members.
Inputs: group (required).
Create a new user. Requires email, user_name, and display_name. Both email and username must be unique within the tenant (409 if duplicate). Returns the new user with an auto-generated id.
Inputs: user (required).
Permanently delete a group. The group must have NO members or the request fails with 409. Remove all members with delete_group_users first. This cannot be undone.
Inputs: group_id (required).
Remove 1–1000 users from a group. Provide an array of user IDs. All-or-nothing: if any user ID is invalid, the entire operation fails.
Inputs: group_id (required), id, user_ids.
Permanently delete a passkey by passkey_id. The user will no longer be able to authenticate with this passkey. This cannot be undone. Use list_passkeys to find passkey_ids.
Inputs: passkey_id (required).
Permanently delete a user. Removes the user from all group memberships. This cannot be undone.
Inputs: user_id (required).
Retrieve the status of a credential binding job by binding_job_id. Shows the current state of the passkey provisioning process (e.g. link sent, completed, expired, failed).
Inputs: binding_job_id (required).
Retrieve a specific group by group_id. Returns the group object including display_name, description, and timestamps. Use list_groups to discover group_ids.
Inputs: group_id (required).
Get the SCIM service provider configuration describing server capabilities: authentication, filtering, patch support, and max results (1000). This is a fixed server-capability endpoint.
Inputs: no named parameters.
Retrieve a specific user by user_id. Returns the full user object including email, username, display_name, status, and timestamps. Use list_users to discover user_ids.
Inputs: user_id (required).
List all groups for the tenant. Returns group objects with pagination (page_size, skip, filter, order_by). Groups are logical collections of users used for access control and organizational purposes.
Inputs: skip, filter, order_by, page_size.
List all users that are members of a group. Returns full user objects with pagination. Requires group_id — use list_groups to discover groups.
Inputs: group_id (required), skip, filter, order_by, +1 more.
List all passkeys across the tenant. Returns passkey objects with state, type, and associated user info. Supports pagination and filtering. Passkeys are the cryptographic credentials users use to authenticate.
Inputs: skip, filter, order_by, page_size.
List all tags associated with a passkey. Tags are key-value metadata attached to passkeys for organizational purposes. Requires passkey_id — use list_passkeys to discover passkeys.
Inputs: passkey_id (required).
List SCIM resource types supported by this server (User and Group). Returns metadata describing schemas, endpoints, and supported operations. This is a fixed server-capability endpoint.
Inputs: no named parameters.
List all SCIM schemas supported by this server, including core schemas and Beyond Identity extensions. This is a fixed server-capability endpoint.
Inputs: no named parameters.
List all groups a user belongs to. Returns full group objects with pagination. Requires user_id — use list_users to find users.
Inputs: user_id (required), skip, page_size.
List all users for the tenant. Returns user objects with pagination (page_size, skip, filter, order_by). Supports filtering by email, username, and other attributes.
Inputs: skip, filter, order_by, page_size.
Retire the intermediate tenant certificate used for device credential signing. This is a sensitive operation — once retired, the old certificate can no longer issue new credentials. Existing credentials signed by the old certificate remain valid until they expire.
Inputs: body.
Create a group via SCIM. Requires displayName. Cannot use reserved permission group names. Optionally include members and description. All member IDs must reference existing users.
Inputs: schemas (required), displayName (required), members, urn_scim_schemas_extension_byndid_1.0_Group.
Create a user via SCIM. Requires externalId, userName, displayName, active, name (givenName, familyName), and emails (at least one primary). On conflict (duplicate externalId/userName), the existing user is reactivated instead of failing.
Inputs: active (required), emails (required), schemas (required), userName (required), +4 more.
Delete a SCIM group. Cannot delete reserved permission groups. Automatically removes the group from all member users.
Inputs: group_id (required).
Delete a SCIM user. Removes the user from all groups. May be soft or hard delete depending on configuration.
Inputs: user_id (required).
Retrieve a specific SCIM group by group_id. Returns the full SCIM Group resource including members array.
Inputs: group_id (required).
Retrieve a specific SCIM user by user_id. Returns the full SCIM User resource with all attributes.
Inputs: user_id (required).
List groups via the SCIM v2.0 protocol. Returns Group resources with displayName, externalId, members array, and Beyond Identity extensions. Permission groups cannot be created or modified via SCIM.
Inputs: count, filter, startIndex.
List users via the SCIM v2.0 protocol. Supports SCIM filtering syntax and pagination (startIndex, count). Max 1000 results per page. Returns SCIM User resources with standard and extension attributes.
Inputs: count, filter, startIndex.
Replace a SCIM user entirely (PUT semantics). All required fields must be provided — this is not a partial update. Uses ETag-based optimistic locking to prevent concurrent update conflicts.
Inputs: schemas (required), user_id (required), meta, name, +6 more.
Partially update a SCIM group via PATCH operations. Supports adding/removing members subject to a max batch size limit.
Inputs: schemas (required), group_id (required), Operations (required).
Partially update a SCIM user via PATCH operations (add, remove, replace). Operations are executed in order. Supports optimistic locking via version headers.
Inputs: schemas (required), user_id (required), Operations (required).
Search all available Beyond Identity API tools by keyword or natural language query. Use this to discover which tools are available for a task. Example queries: 'add user to group', 'list applications', 'manage SSO'.
Inputs: query (required).
Set tags on a passkey, replacing all existing tags. Tags are key-value metadata. Uses PUT semantics — provide the complete set of desired tags; any existing tags not included will be removed.
Inputs: tags (required), passkey_id (required).
Update attributes of a group (display_name, description). Uses PATCH semantics — omitted fields unchanged. Returns the updated group object.
Inputs: group (required), group_id (required).
Update attributes of a user. Uses PATCH semantics — omitted fields unchanged. Returns 409 if updated email or username conflicts with an existing user.
Inputs: user (required), user_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 36 tools
The tool set contains many overlapping operations: users can be managed via native tools (create_user, update_user, delete_user) or SCIM tools (scim_create_user, scim_update_user, scim_delete_user); similarly for groups. An agent cannot easily tell when to use one versus the other, and there is no guidance in the descriptions. This creates significant ambiguity and risk of misselection.
Most tools follow a verb_noun pattern (e.g., create_user, list_groups), but there are several deviations: some use get_ instead of list_ (get_groups, get_user), and the SCIM tools are prefixed with scim_ while others are not. Also, 'add_group_users' and 'delete_group_users' are less predictable. The mix of prefixes and inconsistent use of get/list reduces consistency.
With 36 tools, the set is quite large and includes a duplicate SCIM and native API for similar operations, which bloats the surface. However, the domain (identity management with users, groups, passkeys, SCIM) is broad enough that many tools are justified. It borderline exceeds a manageable count, but each tool has a clear purpose.
The surface covers core CRUD for users, groups, passkeys, and SCIM resources, but there are notable gaps: no tool to update a passkey (e.g., rename or change state), no tool to manage applications or SSO connections despite being mentioned in search examples ('list applications', 'manage SSO'). Also, there is no explicit tool for listing or managing passkey bindings beyond creation and status retrieval. These gaps could hinder some workflows.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
Give your AI hands. Identity, credential vault, and API gateway for autonomous agents.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
