Model Context Protocol (MCP)

Early Access

Try our newest feature! Only available through reach out. Contact us to join the early access program and get priority support.

Unizo offers an MCP server that integrates identity management platforms with any LLM provider supporting the MCP protocol. This enables your AI agent to perform user management operations, analyze access patterns, and automate security workflows across Okta, Auth0, Azure AD, and other identity providers via a single MCP server.

Supported Tools & Use Cases

The following tools are available in the Identity MCP Server:

Tool Summary

Tool Name	Description
`list_services`	Get list of available identity services
`list_integrations`	Get integrations for a specific identity service
`list_users`	Browse and search users with advanced filtering
`get_user_details`	Retrieve comprehensive user information
`list_groups`	Browse and search groups with filtering options
`get_group_details`	Retrieve detailed group information
`list_group_members`	List members of a specific group
`get_group_member_details`	Get detailed information about a group member
`list_user_sessions`	Browse user authentication sessions
`get_session_details`	Retrieve detailed session information

Tool Reference

list_services

Get list of available identity services

Parameters:

None

Returns:
List of available identity services (e.g., Active Directory, Azure AD, LDAP)

Example Response:

[
  {"name": "activedirectory"},
  {"name": "azuread"},
  {"name": "ldap"}
]

list_integrations

Get integrations for a specific identity service

Parameters:

service (string, required): Name of the service (e.g., "activedirectory", "azuread")

Returns:
List of integrations available for the specified service

Example Response:

[
  {
    "id": "integration-123",
    "name": "Company AD Integration"
  }
]

User Management Tools

list_users

Browse and search users with comprehensive filtering options

Parameters:

integration_id (string, required): Unique identifier for the integration
offset (integer, optional): Number of items to skip (default: 0)
limit (integer, optional): Maximum number of items to return (default: 20, max: 100)
sort (string, optional): Sort criteria (e.g., 'lastName,firstName,-createdAt')
status (string, optional): Filter by account status
- Valid values: ACTIVE, INACTIVE, PENDING, SUSPENDED, TERMINATED
mfa_status (string, optional): Filter by MFA status
- Valid values: Enabled, Disabled, Pending, Required
user_type (string, optional): Filter by user type
- Valid values: User, Admin, Service, System, Guest
search (string, optional): Search users by name, email, or username (min 3 chars)
domain (string, optional): Filter users by authentication domain
has_devices (boolean, optional): Filter users who have registered devices
last_login_days (integer, optional): Filter users who logged in within specified days

Returns:
Paginated list of users with filtering applied

Example Response:

{
  "status": "success",
  "message": "Retrieved 25 users",
  "data": {
    "users": [
      {
        "id": "user-123",
        "username": "john.doe",
        "email": "john.doe@company.com",
        "firstName": "John",
        "lastName": "Doe",
        "status": "ACTIVE",
        "mfaStatus": "Enabled",
        "type": "User"
      }
    ],
    "pagination": {
      "total": 250,
      "offset": 0,
      "limit": 20
    },
    "total_count": 250
  }
}

get_user_details

Get detailed information about a specific user

Parameters:

integration_id (string, required): Unique identifier for the integration
user_id (string, required): Unique identifier of the user
expand (array[string], optional): List of resources to expand (Valid values: groups, devices, manager, sessions, all)

Returns:
Comprehensive user information including expanded resources

Example Response:

{
  "status": "success",
  "message": "Retrieved user details for user-123",
  "data": {
    "user": {
      "id": "user-123",
      "username": "john.doe",
      "email": "john.doe@company.com",
      "firstName": "John",
      "lastName": "Doe",
      "mfaStatus": "Enabled",
      "mfaMethods": [
        {
          "type": "TOTP",
          "isDefault": true,
          "isVerified": true
        }
      ],
      "groups": [
        {
          "id": "group-456",
          "name": "Engineering Team",
          "type": "Security"
        }
      ],
      "devices": [
        {
          "uid": "device-789",
          "name": "MacBook Pro",
          "type": "Laptop",
          "isManaged": true,
          "isCompliant": true
        }
      ]
    },
    "expanded": ["groups", "devices"]
  }
}

Group Management Tools

list_groups

Browse and search groups with filtering options

Parameters:

integration_id (string, required): Unique identifier for the integration
offset (integer, optional): Number of items to skip (default: 0)
limit (integer, optional): Maximum number of items to return (default: 20, max: 100)
sort (string, optional): Sort criteria (e.g., 'name,-createdAt')
group_type (string, optional): Filter by group type (Valid values: Security, Distribution, Universal, Mail_Enabled, Role_Based)
status (string, optional): Filter by group status (Valid values: ACTIVE, INACTIVE, PENDING, ARCHIVED)
search (string, optional): Search groups by name or description (min 3 chars)
has_members (boolean, optional): Filter groups with members
parent_group_id (string, optional): Filter by parent group

Returns:
Paginated list of groups with filtering applied

get_group_details

Get detailed information about a specific group

Parameters:

integration_id (string, required): Unique identifier for the integration
group_id (string, required): Unique identifier of the group
expand (array[string], optional): List of resources to expand (Valid values: members, owners, parentGroups, childGroups, all)

Returns:
Comprehensive group information including expanded resources

list_group_members

List members of a specific group

Parameters:

integration_id (string, required): Unique identifier for the integration
group_id (string, required): Unique identifier of the group
offset (integer, optional): Number of items to skip (default: 0)
limit (integer, optional): Maximum number of items to return (default: 20, max: 100)
member_type (string, optional): Filter by member type (Valid values: user, group, servicePrincipal)
status (string, optional): Filter by membership status (Valid values: active, pending, suspended, expired)
search (string, optional): Search members by name or email

Returns:
Paginated list of group members

Example Response:

{
  "status": "success",
  "message": "Retrieved 15 members for group group-456",
  "data": {
    "members": [
      {
        "id": "user-123",
        "type": "user",
        "name": "John Doe",
        "email": "john.doe@company.com",
        "status": "active",
        "joinedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 15,
      "offset": 0,
      "limit": 20
    },
    "group_id": "group-456",
    "total_count": 15
  }
}

get_group_member_details

Get detailed information about a specific group member

Parameters:

integration_id (string, required): Unique identifier for the integration
group_id (string, required): Unique identifier of the group
member_id (string, required): Unique identifier of the member

Returns:
Detailed member information including membership metadata

Session Management Tools

list_user_sessions

List authentication sessions for a specific user

Parameters:

integration_id (string, required): Unique identifier for the integration
user_id (string, required): Unique identifier of the user
status (string, optional): Filter sessions by status (default: "active", Valid values: active, expired, revoked, suspended, all)
offset (integer, optional): Number of items to skip (default: 0)
limit (integer, optional): Maximum number of items to return (default: 20, max: 100)
from_date (string, optional): Filter sessions created after this date (ISO format)
to_date (string, optional): Filter sessions created before this date (ISO format)

Returns:
Paginated list of user sessions

Example Response:

{
  "status": "success",
  "message": "Retrieved 3 sessions for user user-123",
  "data": {
    "sessions": [
      {
        "uid": "session-789",
        "userId": "user-123",
        "status": "active",
        "isMfa": true,
        "mfaMethod": "TOTP",
        "authenticationMethod": "SSO",
        "createdTimeDt": "2024-09-02T08:00:00Z",
        "expirationTimeDt": "2024-09-02T16:00:00Z",
        "device": {
          "name": "MacBook Pro",
          "type": "Laptop",
          "os": {
            "name": "macOS",
            "version": "14.5"
          }
        },
        "location": {
          "city": "San Francisco",
          "country": "United States",
          "isTrustedLocation": true
        }
      }
    ],
    "pagination": {
      "total": 3,
      "offset": 0,
      "limit": 20
    },
    "user_id": "user-123",
    "total_count": 3
  }
}

get_session_details

Get detailed information about a specific authentication session

Parameters:

integration_id (string, required): Unique identifier for the integration
user_id (string, required): Unique identifier of the user
session_id (string, required): Unique identifier of the session

Returns:
Comprehensive session information including device and location details

Installation

Prerequisites

A Unizo API key
An active Identity integration (Office 365, Google Workspace, OKTA, Microsoft Entra ID, Ping, Auth0)
Node.js v20 or higher

MCP Configuration

Here is an example configuration for setting up the Unizo Identity MCP server:

{
  "mcpServers": {
    "unizo-identity": {
        "command": "npx",
      "args": [
        "mcp-remote",
        "http://api.unizo.ai/mcp/identity",
        "--allow-http",
        "--header",
        "apikey:${UNIZO_API_KEY}"
      ],
      "env": {
        "UNIZO_API_KEY": "your_api_key"
      }
    }
  }
}

Client Setup

For detailed setup instructions with specific AI clients:

Environment Variables

The following environment variables are required:

UNIZO_API_KEY: Your Unizo API key Your Unizo API key

Error Handling

All tools return errors in a consistent format:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User 'john.doe@example.com' not found"
  }
}

Common error codes:

INTEGRATION_NOT_FOUND: Invalid identity provider integration ID
USER_NOT_FOUND: User not found or inaccessible
GROUP_NOT_FOUND: Group ID not found
PERMISSION_DENIED: Access to the requested resource is denied
RATE_LIMIT_EXCEEDED: API quota exceeded
UNAUTHORIZED: Invalid API key or insufficient permissions

Early Access

Supported Tools & Use Cases​

Tool Summary

Tool Reference​

list_services​

list_integrations​

User Management Tools​

list_users​

get_user_details​

Group Management Tools​

list_groups​

get_group_details​

list_group_members​

get_group_member_details​

Session Management Tools​

list_user_sessions​

get_session_details​

Installation​

Prerequisites​

MCP Configuration​

Client Setup​

Environment Variables​

Error Handling​

Related Resources​

Supported Tools & Use Cases

Tool Reference

list_services

list_integrations

User Management Tools

list_users

get_user_details

Group Management Tools

list_groups

get_group_details

list_group_members

get_group_member_details

Session Management Tools

list_user_sessions

get_session_details

Installation

Prerequisites

MCP Configuration

Client Setup

Environment Variables

Error Handling

Related Resources