@beyondidentity/mcp

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

Quick Start

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.

Environment Variables

Variable	Required	Default	Description
API_KEY	Yes	—	Beyond Identity API key (JWT). Obtained from the admin console under Settings > API Access.
REGION	No	US	US or EU. Determines the API base URL.
BASE_URL	No	(computed from platform + region)	Override the API host. Use for non-production environments (e.g. staging, local mock). When set, takes precedence over REGION.

How It Works

Platform Detection

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.

Tool Discovery

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).

Automatic Parameter Injection

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.

Error Handling

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.

Available Tools

Secure Access (v1) — 104 tools

Tenants (2)

Tool	Description
get_tenant	Retrieve an existing tenant
update_tenant	Patch a tenant

Realms (5)

Tool	Description
list_realms	List realms for a tenant
create_realm	Create a new realm
get_realm	Retrieve an existing realm
update_realm	Patch a realm
delete_realm	Delete a realm

Groups (9)

Tool	Description
list_groups	List groups for a realm
create_group	Create a new group
get_group	Retrieve an existing group
update_group	Patch a group
delete_group	Delete a group
add_group_members	Add members to a group
delete_group_members	Delete members from a group
list_group_members	List members for a group
list_group_roles	List role memberships for a group

Identities (8)

Tool	Description
list_identities	List identities for a realm
create_identity	Create a new identity
get_identity	Retrieve an existing identity
update_identity	Patch an identity
delete_identity	Delete an identity
batch_delete_identities	Batch delete identities
list_identity_groups	List group memberships for an identity
list_identity_roles	List role memberships for an identity

Roles (11)

Tool	Description
list_roles	List roles for a resource server
create_role	Create a new role
get_role	Retrieve an existing role
update_role	Patch a role
delete_role	Delete a role
add_role_members	Assign members to a role
delete_role_members	Unassign members from a role
list_role_members	List members for a role
add_role_scopes	Assign scopes to a role
delete_role_scopes	Unassign scopes from a role
list_role_scopes	List scopes for a role

Credentials (3)

Tool	Description
list_credentials	List credentials for an identity
get_credential	Retrieve an existing credential
revoke_credential	Revoke a credential

Credential Binding Jobs (7)

Tool	Description
list_credential_binding_jobs	List credential binding jobs for an identity
create_credential_binding_job	Create a new credential binding job
get_credential_binding_job	Retrieve an existing credential binding job
set_credential_binding_job_revoked	Revoke an active credential binding job
create_batch_credential_binding_job	Create a new batch credential binding job
get_batch_credential_binding_job	Retrieve an existing batch credential binding job
list_batch_credential_binding_job_results	List results of a batch credential binding job

Themes (4)

Tool	Description
create_theme	Create a new theme
get_active_theme	Get the active theme
get_theme	Retrieve an existing theme
update_theme	Patch a theme

Applications (5)

Tool	Description
list_applications	List applications for a realm
create_application	Create a new application
get_application	Retrieve an existing application
update_application	Patch an application
delete_application	Delete an application

Authenticator Configurations (5)

Tool	Description
list_authenticator_configs	List authenticator configurations for a realm
create_authenticator_config	Create a new authenticator configuration
get_authenticator_config	Retrieve an existing authenticator configuration
update_authenticator_config	Patch an authenticator configuration
delete_authenticator_config	Delete an authenticator configuration

Resource Servers (5)

Tool	Description
list_resource_servers	List resource servers for a realm
create_resource_server	Create a new resource server
get_resource_server	Retrieve an existing resource server
update_resource_server	Patch a resource server
delete_resource_server	Delete a resource server

Tokens (2)

Tool	Description
list_tokens	List tokens
revoke_token	Revoke a token

SSO Configs (17)

Tool	Description
list_sso_configs	List SSO configs for a realm
create_sso_config	Create a new SSO config
get_sso_config	Retrieve an existing SSO config
update_sso_config	Update an SSO config
delete_sso_config	Delete an SSO config
add_identities_to_sso_config	Associate identities with an SSO config
delete_identities_from_sso_config	Delete identities from an SSO config
list_identities_for_sso_config	List identities associated with an SSO config
identity_to_sso_config_check	Check if an identity is assigned to an SSO config
list_sso_configs_for_identity	List SSO configs associated with an identity
add_groups_to_sso_config	Associate groups with an SSO config
delete_groups_from_sso_config	Delete groups from an SSO config
list_groups_for_sso_config	List groups associated with an SSO config
list_sso_configs_for_group	List SSO configs associated with a group
sso_is_group_assigned	Check if groups are associated with an SSO config
application_id_to_sso_config_id	Get the SSO config ID for an application
test_sso_config	Test an SSO config

Identity Providers (5)

Tool	Description
list_identity_providers	List identity providers by realm
create_identity_provider	Create a new identity provider
get_identity_provider	Retrieve an identity provider
update_identity_provider	Update an identity provider
delete_identity_provider	Delete an identity provider

Launch Mechanisms (2)

Tool	Description
get_flow_type_config	Get flow type configuration
update_flow_type_config	Update flow type configuration

SCIM (14)

Tool	Description
scim_list_users	List all SCIM users
scim_create_user	Create a new SCIM user
scim_get_user	Retrieve an existing SCIM user
scim_replace_user	Replace a SCIM user
scim_update_user	Patch a SCIM user
scim_delete_user	Delete a SCIM user
scim_list_groups	List all SCIM groups
scim_create_group	Create a new SCIM group
scim_get_group	Retrieve an existing SCIM group
scim_update_group	Patch a SCIM group
scim_delete_group	Delete a SCIM group
list_resource_types	List all SCIM resource types
list_schemas	List all SCIM schemas
get_service_provider_config	Retrieve the SCIM service provider configuration

Secure Workforce (v0) — 35 tools

Groups (8)

Tool	Description
list_groups	List all groups for a tenant
create_group	Create a new group
get_groups	Retrieve an existing group
update_group	Patch a group
delete_group	Delete a group
list_group_users	List all users for a group
add_group_users	Add users to a group
delete_group_users	Delete users from a group

Users (6)

Tool	Description
list_users	List all users for a tenant
create_user	Create a new user
get_user	Retrieve an existing user
update_user	Update a user
delete_user	Delete a user
list_user_groups	List all groups for a user

Binding Jobs (2)

Tool	Description
create_binding_job	Create a new credential binding job
get_binding_job	Get a credential binding job

Passkeys (4)

Tool	Description
list_passkeys	List passkeys
delete_passkey	Delete a passkey
list_passkey_tags	List passkey tags
set_passkey_tags	Set passkey tags

Certificate Authority (1)

Tool	Description
retire_tenant_issuer	Retire the intermediate tenant certificate

SCIM (14)

Tool	Description
scim_list_users	List all SCIM users
scim_create_user	Create a new SCIM user
scim_get_user	Retrieve an existing SCIM user
scim_replace_user	Replace a SCIM user
scim_update_user	Patch a SCIM user
scim_delete_user	Delete a SCIM user
scim_list_groups	List all SCIM groups
scim_create_group	Create a new SCIM group
scim_get_group	Retrieve an existing SCIM group
scim_update_group	Patch a SCIM group
scim_delete_group	Delete a SCIM group
list_resource_types	List all SCIM resource types
list_schemas	List all SCIM schemas
get_service_provider_config	Retrieve the SCIM service provider configuration

Project Architecture

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)

Code Generation

All tool definitions and HTTP handlers are auto-generated from the OpenAPI specifications. The generator (scripts/generate.ts) does the following:

1. Parses both YAML specs and dereferences all $ref pointers
2. Extracts every operation (path + HTTP method + operationId)
3. Converts each operationId to a snake_case tool name
4. Builds Zod input schemas from the OpenAPI request parameters and body definitions
5. Generates tool handler functions that call the ApiClient with the correct method, path, and parameters
6. Annotates read-only tools (GET) and destructive tools (DELETE) for MCP clients that surface this information

To regenerate after spec changes:

npm run generate

The generated files are committed to the repository so consumers don't need to run the generator themselves.

HTTP Client

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

Development

# 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 start

API Documentation

• Secure Access (v1) API Reference
• Secure Workforce (v0) API Reference

Local Development MCP Config

To 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"
      }
    }
  }
}