Model Context Protocol (MCP)

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 Name	Description
`identity_list_integrations`	Get integrations for a specific identity service
`identity_list_users`	Browse users with comprehensive filtering and pagination
`identity_get_user_details`	Retrieve detailed user information with expandable resources
`identity_list_groups`	Browse and search groups with filtering options
`identity_get_group_details`	Retrieve comprehensive group information
`identity_list_group_members`	Browse members of a specific group
`identity_get_group_member_details`	Retrieve detailed member information
`identity_list_user_sessions`	List active and historical sessions for a user
`identity_get_session_details`	Retrieve detailed session information

Tool Reference

Service Discovery Tools

identity_list_connectors

Get list of available identity services

Parameters:

None

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

Example Response:

[
  {"name": "azure_ad"},
  {"name": "okta"},
  {"name": "active_directory"},
  {"name": "google_workspace"}
]

identity_list_integrations

Get integrations for a specific identity service

Parameters:

service (string, required): Name of the service (e.g., "azure_ad", "okta")

Returns: List of integrations available for the specified service

Example Response:

[
  {
    "id": "integration-123",
    "name": "Production Azure AD"
  },
  {
    "id": "integration-456",
    "name": "Development Okta"
  }
]

User Management Tools

identity_list_users

Browse users with comprehensive filtering options and pagination

Parameters:

integration_id (string, required): Unique identifier for the integration

Returns: Paginated list of users

Example Response:

{
  "status": "success",
  "message": "Retrieved 15 users",
  "data": {
    "users": [
      {
        "id": "user-123",
        "username": "john.doe",
        "email": "john.doe@company.com",
        "firstName": "John",
        "lastName": "Doe",
        "fullName": "John Doe",
        "status": "ACTIVE",
        "mfaStatus": "Enabled",
        "type": "User",
        "domain": "company.com",
        "account": {
          "name": "john.doe",
          "type": "Domain",
          "uid": "S-1-5-21-123456789"
        },
        "ldapPerson": {
          "ldapDn": "CN=John Doe,OU=Users,DC=company,DC=com",
          "employeeUid": "EMP001",
          "jobTitle": "Senior Developer",
          "department": "Engineering",
          "manager": {
            "id": "user-456",
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "jane.smith@company.com"
          },
          "hireTimeDt": "2020-03-15T00:00:00Z",
          "lastLoginTimeDt": "2024-11-05T09:30:00Z"
        },
        "groups": [
          {
            "id": "group-789",
            "name": "Engineering Team",
            "type": "Security",
            "privileges": ["read", "write"]
          }
        ],
        "devices": [
          {
            "uid": "device-001",
            "name": "LAPTOP-JOHN",
            "type": "Laptop",
            "os": {
              "name": "Windows 11",
              "version": "22H2",
              "type": "Windows"
            },
            "isManaged": true,
            "isCompliant": true,
            "lastSeenTimeDt": "2024-11-05T08:00:00Z"
          }
        ],
        "location": {
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "countryCode": "US",
          "isTrustedLocation": true
        },
        "createdAt": "2020-03-15T10:00:00Z",
        "updatedAt": "2024-11-05T09:30:00Z"
      }
    ],
    "pagination": {
      "total": 15,
      "offset": 0,
      "limit": 20
    },
    "total_count": 15
  }
}

identity_get_user_details

Get detailed information about a specific user with expandable resources

Parameters:

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

Returns: Comprehensive user information

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",
      "fullName": "John Doe",
      "status": "ACTIVE",
      "mfaStatus": "Enabled",
      "hasMfa": true,
      "mfaMethods": [
        {
          "type": "TOTP",
          "isDefault": true,
          "isVerified": true,
          "lastUsed": "2024-11-05T09:30:00Z"
        },
        {
          "type": "SMS",
          "isDefault": false,
          "isVerified": true,
          "phoneNumber": "+1-555-0123"
        }
      ],
      "type": "User",
      "domain": "company.com",
      "account": {
        "name": "john.doe",
        "type": "Domain",
        "uid": "S-1-5-21-123456789",
        "labels": ["employee", "full-time"]
      },
      "ldapPerson": {
        "ldapDn": "CN=John Doe,OU=Users,DC=company,DC=com",
        "ldapCn": "John Doe",
        "employeeUid": "EMP001",
        "givenName": "John",
        "surname": "Doe",
        "jobTitle": "Senior Developer",
        "department": "Engineering",
        "costCenter": "CC-ENG-001",
        "officeLocation": "Building A, Floor 3",
        "manager": {
          "id": "user-456",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@company.com"
        },
        "hireTimeDt": "2020-03-15T00:00:00Z",
        "lastLoginTimeDt": "2024-11-05T09:30:00Z",
        "emailAddrs": ["john.doe@company.com", "j.doe@company.com"]
      },
      "groups": [
        {
          "id": "group-789",
          "uid": "GRP-789",
          "name": "Engineering Team",
          "type": "Security",
          "privileges": ["read", "write", "deploy"]
        },
        {
          "id": "group-012",
          "uid": "GRP-012",
          "name": "Developers",
          "type": "Distribution",
          "privileges": ["read"]
        }
      ],
      "devices": [
        {
          "uid": "device-001",
          "name": "LAPTOP-JOHN",
          "hostname": "laptop-john.company.com",
          "type": "Laptop",
          "isManaged": true,
          "isCompliant": true,
          "isPersonal": false,
          "isTrusted": true,
          "os": {
            "name": "Windows 11",
            "version": "22H2",
            "build": "22621.2715",
            "type": "Windows"
          },
          "macAddresses": ["00:1B:44:11:3A:B7"],
          "ipAddresses": ["192.168.1.100"],
          "lastSeenTimeDt": "2024-11-05T08:00:00Z",
          "serialNumber": "SN123456789",
          "model": "ThinkPad X1 Carbon",
          "manufacturer": "Lenovo",
          "networkStatus": "Connected"
        }
      ],
      "location": {
        "city": "San Francisco",
        "state": "California",
        "country": "United States",
        "countryCode": "US",
        "continent": "North America",
        "timezone": "America/Los_Angeles",
        "lat": 37.7749,
        "long": -122.4194,
        "isTrustedLocation": true,
        "building": "HQ Building A",
        "floor": "3",
        "isp": "Company ISP"
      },
      "authorizations": [
        {
          "decision": "ALLOW",
          "policy": {
            "uid": "policy-001",
            "name": "Standard User Access",
            "version": "1.0",
            "isApplied": true
          }
        }
      ],
      "idp": {
        "name": "Azure AD",
        "uid": "idp-azure-001",
        "type": "OIDC",
        "syncEnabled": true,
        "lastSyncTime": "2024-11-05T06:00:00Z",
        "syncStatus": "success"
      },
      "org": {
        "name": "Company Inc.",
        "uid": "org-001",
        "ouName": "Engineering",
        "ouUid": "ou-eng-001"
      },
      "privileges": ["user.read", "user.write", "file.read"],
      "labels": ["employee", "engineering", "full-time"],
      "createdAt": "2020-03-15T10:00:00Z",
      "updatedAt": "2024-11-05T09:30:00Z",
      "createdBy": {
        "id": "admin-001",
        "firstName": "Admin",
        "lastName": "User"
      },
      "lastUpdatedBy": {
        "id": "admin-001",
        "firstName": "Admin",
        "lastName": "User"
      }
    },
    "expanded": ["groups", "devices", "manager"]
  }
}

Group Management Tools

identity_list_groups

Browse and search groups with filtering options and pagination

Parameters:

integration_id (string, required): Unique identifier for the integration

Returns: Paginated list of groups

Example Response:

{
  "status": "success",
  "message": "Retrieved 8 groups",
  "data": {
    "groups": [
      {
        "id": "group-123",
        "uid": "GRP-123",
        "name": "Engineering Team",
        "displayName": "Engineering Team",
        "description": "All engineering staff members",
        "type": "Security",
        "domain": "company.com",
        "dn": "CN=Engineering Team,OU=Groups,DC=company,DC=com",
        "email": "engineering@company.com",
        "status": "ACTIVE",
        "privileges": ["read", "write", "deploy"],
        "memberCount": 25,
        "members": [
          {
            "id": "user-123",
            "type": "user",
            "name": "John Doe",
            "email": "john.doe@company.com",
            "status": "active"
          }
        ],
        "owners": [
          {
            "id": "user-456",
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "jane.smith@company.com"
          }
        ],
        "parentGroups": [
          {
            "id": "group-999",
            "name": "All Staff",
            "type": "Universal"
          }
        ],
        "org": {
          "name": "Company Inc.",
          "uid": "org-001",
          "ouName": "Engineering",
          "ouUid": "ou-eng-001"
        },
        "labels": ["department", "technical"],
        "createdAt": "2020-01-01T10:00:00Z",
        "updatedAt": "2024-11-05T10:00:00Z",
        "createdBy": {
          "id": "admin-001",
          "firstName": "Admin",
          "lastName": "User"
        }
      }
    ],
    "pagination": {
      "total": 8,
      "offset": 0,
      "limit": 20
    },
    "total_count": 8
  }
}

identity_get_group_details

Get detailed information about a specific group with expandable resources

Parameters:

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

Returns: Comprehensive group information

Example Response:

{
  "status": "success",
  "message": "Retrieved group details for group-123",
  "data": {
    "group": {
      "id": "group-123",
      "uid": "GRP-123",
      "name": "Engineering Team",
      "displayName": "Engineering Team",
      "description": "All engineering staff members",
      "type": "Security",
      "domain": "company.com",
      "dn": "CN=Engineering Team,OU=Groups,DC=company,DC=com",
      "email": "engineering@company.com",
      "status": "ACTIVE",
      "privileges": ["read", "write", "deploy", "admin"],
      "memberCount": 25,
      "members": [
        {
          "id": "user-123",
          "type": "user",
          "name": "John Doe",
          "email": "john.doe@company.com",
          "status": "active"
        },
        {
          "id": "user-456",
          "type": "user",
          "name": "Jane Smith",
          "email": "jane.smith@company.com",
          "status": "active"
        }
      ],
      "owners": [
        {
          "id": "user-789",
          "firstName": "Alice",
          "lastName": "Johnson",
          "email": "alice.johnson@company.com"
        }
      ],
      "managedBy": {
        "id": "user-789",
        "firstName": "Alice",
        "lastName": "Johnson"
      },
      "parentGroups": [
        {
          "id": "group-999",
          "uid": "GRP-999",
          "name": "All Staff",
          "displayName": "All Staff Members",
          "type": "Universal"
        }
      ],
      "childGroups": [
        {
          "id": "group-234",
          "uid": "GRP-234",
          "name": "Backend Developers",
          "type": "Security"
        },
        {
          "id": "group-345",
          "uid": "GRP-345",
          "name": "Frontend Developers",
          "type": "Security"
        }
      ],
      "org": {
        "name": "Company Inc.",
        "uid": "org-001",
        "ouName": "Engineering",
        "ouUid": "ou-eng-001"
      },
      "attributes": {
        "costCenter": "CC-ENG-001",
        "location": "Building A"
      },
      "labels": ["department", "technical", "critical"],
      "lifecycle": {
        "expirationTime": "2025-12-31T23:59:59Z",
        "renewalRequired": true,
        "lastReviewedTime": "2024-10-01T10:00:00Z",
        "nextReviewTime": "2025-01-01T10:00:00Z",
        "reviewCycle": "quarterly"
      },
      "idp": {
        "name": "Azure AD",
        "uid": "idp-azure-001",
        "type": "OIDC",
        "syncEnabled": true,
        "lastSyncTime": "2024-11-05T06:00:00Z",
        "syncStatus": "success"
      },
      "createdAt": "2020-01-01T10:00:00Z",
      "updatedAt": "2024-11-05T10:00:00Z",
      "createdBy": {
        "id": "admin-001",
        "firstName": "Admin",
        "lastName": "User"
      },
      "lastUpdatedBy": {
        "id": "admin-002",
        "firstName": "Manager",
        "lastName": "User"
      }
    },
    "expanded": ["members", "owners", "parentGroups", "childGroups"]
  }
}

Group Member Management Tools

identity_list_group_members

List members of a specific group with filtering and pagination

Parameters:

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

Returns: Paginated list of group members

Example Response:

{
  "status": "success",
  "message": "Retrieved 12 members for group group-123",
  "data": {
    "members": [
      {
        "id": "member-001",
        "type": "user",
        "status": "active",
        "joinedAt": "2023-06-15T10:00:00Z",
        "expiresAt": null,
        "addedBy": {
          "id": "admin-001",
          "firstName": "Admin",
          "lastName": "User"
        },
        "user": {
          "id": "user-123",
          "username": "john.doe",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@company.com"
        },
        "membershipType": "Direct",
        "privileges": ["read", "write"]
      },
      {
        "id": "member-002",
        "type": "group",
        "status": "active",
        "joinedAt": "2023-07-01T10:00:00Z",
        "group": {
          "id": "group-456",
          "uid": "GRP-456",
          "name": "Junior Developers",
          "displayName": "Junior Developers",
          "type": "Security"
        },
        "membershipType": "Direct"
      },
      {
        "id": "member-003",
        "type": "servicePrincipal",
        "status": "active",
        "joinedAt": "2023-08-10T10:00:00Z",
        "servicePrincipal": {
          "id": "sp-789",
          "name": "CI/CD Pipeline",
          "appId": "app-12345",
          "description": "Automated deployment service"
        },
        "membershipType": "Direct",
        "privileges": ["deploy", "read"]
      }
    ],
    "pagination": {
      "total": 12,
      "offset": 0,
      "limit": 20
    },
    "group_id": "group-123",
    "total_count": 12
  }
}

identity_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: Comprehensive member information

Example Response:

{
  "status": "success",
  "message": "Retrieved member details for member-001",
  "data": {
    "member": {
      "id": "member-001",
      "type": "user",
      "status": "active",
      "joinedAt": "2023-06-15T10:00:00Z",
      "expiresAt": null,
      "addedBy": {
        "id": "admin-001",
        "uid": "ADM-001",
        "username": "admin",
        "firstName": "Admin",
        "lastName": "User",
        "email": "admin@company.com"
      },
      "user": {
        "id": "user-123",
        "uid": "USR-123",
        "username": "john.doe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@company.com",
        "href": "/api/v1/identity/users/user-123"
      },
      "membershipType": "Direct",
      "inheritedFrom": null,
      "privileges": ["read", "write", "delete"]
    },
    "group_id": "group-123"
  }
}

Session Management Tools

identity_list_user_sessions

List active and historical sessions for a specific user

Parameters:

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

Returns: Paginated list of user sessions

Example Response:

{
  "status": "success",
  "message": "Retrieved 3 sessions for user user-123",
  "data": {
    "sessions": [
      {
        "uid": "session-001",
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "userId": "user-123",
        "isMfa": true,
        "mfaMethod": "TOTP",
        "authenticationMethod": "SSO",
        "isRemote": false,
        "isVpn": false,
        "createdTimeDt": "2024-11-05T09:00:00Z",
        "expirationTimeDt": "2024-11-05T17:00:00Z",
        "lastActivityTime": "2024-11-05T14:30:00Z",
        "status": "active",
        "terminal": "LAPTOP-JOHN",
        "issuer": "Azure AD",
        "credentialUid": "cred-123",
        "device": {
          "uid": "device-001",
          "hostname": "laptop-john.company.com",
          "ip": "192.168.1.100",
          "mac": "00:1B:44:11:3A:B7",
          "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
          "os": {
            "name": "Windows 11",
            "version": "22H2",
            "build": "22621.2715",
            "type": "Windows"
          },
          "browser": {
            "name": "Chrome",
            "version": "119.0.0.0"
          }
        },
        "location": {
          "ip": "192.168.1.100",
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "countryCode": "US",
          "lat": 37.7749,
          "long": -122.4194,
          "isp": "Company ISP",
          "org": "Company Inc.",
          "isTrustedLocation": true
        },
        "protocol": "HTTPS",
        "application": "Office 365",
        "sessionFlags": ["trusted_device", "corporate_network"]
      },
      {
        "uid": "session-002",
        "userId": "user-123",
        "isMfa": true,
        "mfaMethod": "SMS",
        "authenticationMethod": "Password",
        "isRemote": true,
        "isVpn": true,
        "createdTimeDt": "2024-11-04T15:00:00Z",
        "expirationTimeDt": "2024-11-04T23:00:00Z",
        "lastActivityTime": "2024-11-04T22:45:00Z",
        "status": "expired",
        "expirationReason": "Session timeout",
        "device": {
          "uid": "device-002",
          "hostname": "iphone-john",
          "ip": "10.0.0.50",
          "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
          "os": {
            "name": "iOS",
            "version": "17.0",
            "type": "iOS"
          }
        },
        "location": {
          "ip": "203.0.113.45",
          "city": "Los Angeles",
          "state": "California",
          "country": "United States",
          "countryCode": "US",
          "isTrustedLocation": false
        },
        "protocol": "HTTPS",
        "application": "VPN Client"
      }
    ],
    "pagination": {
      "total": 3,
      "offset": 0,
      "limit": 20
    },
    "user_id": "user-123",
    "total_count": 3
  }
}

identity_get_session_details

Get detailed information about a specific 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

Example Response:

{
  "status": "success",
  "message": "Retrieved session details for session-001",
  "data": {
    "session": {
      "uid": "session-001",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "isMfa": true,
      "mfaMethod": "TOTP",
      "authenticationMethod": "SSO",
      "isRemote": false,
      "isVpn": false,
      "createdTime": 1730800800,
      "createdTimeDt": "2024-11-05T09:00:00Z",
      "expirationTime": 1730829600,
      "expirationTimeDt": "2024-11-05T17:00:00Z",
      "lastActivityTime": "2024-11-05T14:30:00Z",
      "status": "active",
      "terminal": "LAPTOP-JOHN",
      "issuer": "Azure AD",
      "credentialUid": "cred-123",
      "count": 1,
      "device": {
        "uid": "device-001",
        "hostname": "laptop-john.company.com",
        "ip": "192.168.1.100",
        "mac": "00:1B:44:11:3A:B7",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "os": {
          "name": "Windows 11",
          "version": "22H2",
          "build": "22621.2715",
          "type": "Windows"
        },
        "browser": {
          "name": "Chrome",
          "version": "119.0.0.0",
          "engine": "Blink"
        }
      },
      "location": {
        "ip": "192.168.1.100",
        "city": "San Francisco",
        "state": "California",
        "country": "United States",
        "countryCode": "US",
        "lat": 37.7749,
        "long": -122.4194,
        "isp": "Company ISP",
        "org": "Company Inc.",
        "isTrustedLocation": true
      },
      "protocol": "HTTPS",
      "application": "Office 365",
      "sessionFlags": ["trusted_device", "corporate_network", "mfa_verified"]
    },
    "user_id": "user-123"
  }
}

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": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.unizo.ai/mcp",
        "--header",
        "apikey:${UNIZO_API_KEY}",
        "--header",
        "x-mcp-scopes:identity"
      ],
      "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:

{
  "status": "error",
  "message": "User 'user-999' not found",
  "traceback": "..."
}

Common Error Codes

INTEGRATION_NOT_FOUND: Invalid integration ID
USER_NOT_FOUND: User doesn't exist or no access
GROUP_NOT_FOUND: Group doesn't exist or no access
SESSION_NOT_FOUND: Session doesn't exist
RATE_LIMIT_EXCEEDED: API rate limit reached
UNAUTHORIZED: Invalid credentials or permissions
INVALID_PARAMETER: Invalid parameter value
SEARCH_TOO_SHORT: Search term must be at least 3 characters

Supported Tools & Use Cases​

Tool Reference​

Service Discovery Tools​

identity_list_connectors​

identity_list_integrations​

User Management Tools​

identity_list_users​

identity_get_user_details​

Group Management Tools​

identity_list_groups​

identity_get_group_details​

Group Member Management Tools​

identity_list_group_members​

identity_get_group_member_details​

Session Management Tools​

identity_list_user_sessions​

identity_get_session_details​

Installation​

Prerequisites​

MCP Configuration​

Client Setup​

Environment Variables​

Error Handling​

Common Error Codes​

Related Resources​

Supported Tools & Use Cases

Tool Reference

Service Discovery Tools

identity_list_connectors

identity_list_integrations

User Management Tools

identity_list_users

identity_get_user_details

Group Management Tools

identity_list_groups

identity_get_group_details

Group Member Management Tools

identity_list_group_members

identity_get_group_member_details

Session Management Tools

identity_list_user_sessions

identity_get_session_details

Installation

Prerequisites

MCP Configuration

Client Setup

Environment Variables

Error Handling

Common Error Codes

Related Resources