Xito › Documentation

Xito Documentation

Complete reference for MCP tools, resources, data model, configuration, and deployment of Xito — AI-powered user lifecycle automation for Office 365.

Overview

Xito is an AI-powered service that autonomously syncs EmployWise HRMS with Azure AD / Microsoft 365. It uses an agentic pipeline of 8 sequential AI tools that perceive, reason, decide, and act on your identity data.

The application exposes its capabilities as MCP (Model Context Protocol) tools and resources, enabling any AI assistant — Copilot, ChatGPT, Claude, Cursor — to query your identity data and trigger lifecycle actions.

🛈
Xito maintains two local database snapshots — ad_users (from Azure AD) and hr_ms_employees (from EmployWise) — and compares them to detect drift, then applies corrections to Azure AD.

Architecture

Xito follows a snapshot → compare → act → log cycle:

┌─────────────────┐         ┌──────────────────┐
│  EmployWise     │────────▶│                  │
│  HRMS API       │         │    Xito        │
└─────────────────┘         │    AI Agents     │
                            │                  │──────▶  Audit Logs
┌─────────────────┐         │   (8 Tools)      │──────▶  Teams Alerts
│  Microsoft      │◀───────▶│                  │
│  Graph API      │         └──────────────────┘
└─────────────────┘
        │
        ▼
┌─────────────────┐
│  Azure AD       │
│  Microsoft 365  │
└─────────────────┘

Configuration

Environment Variables

VariableRequiredDescriptionDefault
ms_graph_tenant_idYesAzure AD tenant (directory) ID—
ms_graph_client_idYesApp registration client ID—
ms_graph_client_secretYesApp registration client secret—
EMPLOYWISE_API_KEYYesEmployWise API key—
EMPLOYWISE_API_URLYesEmployWise employee export endpoint—
AD_DISABLE_AFTER_EXIT_DAYSNoGrace period (days) after exit date before leaver cleanup7
TEAMS_WEBHOOK_URLNoMicrosoft Teams incoming webhook URL for failure alerts—

Customer Filters

Per-tenant filtering is configured in the Xito configuration panel:

{
    "customer-filters": {
        "YOUR-TENANT-ID-GUID": {
            "include_domains":             ["yourcompany.com"],
            "exclude_employment_statuses": ["Alumni"],
            "exclude_emp_codes":           ["51530"]
        }
    }
}
FilterTypeBehavior
include_domainsarrayOnly import employees whose email domain is in this list
exclude_employment_statusesarraySkip employees with these employment statuses
exclude_emp_codesarraySkip specific employee codes

Quick Start

# 1. Deploy Xito to your environment
xito:install

# 2. Configure credentials
xito:configure --setup
# Provide Azure AD and EmployWise credentials

# 3. Initialize the data store
xito:init

# 4. Run the full AI pipeline
xito:run_pipeline

# 5. Or trigger individual AI agents
xito:sync_ad_users
xito:sync_hrms
xito:update_fields

MCP Tools

Xito exposes 8 tools via the Model Context Protocol. Each tool can be invoked by any MCP-compatible client (Cursor, Claude Desktop, Copilot Studio, or custom agents).

💡
Tools are the actions Xito can perform. Resources (next section) are the data Xito can expose for reading.

sync_ad_users

Available

Fetches all users from Azure AD via Microsoft Graph API and stores them in the local AD snapshot, creating or updating each record as needed.

MCP Invocation

xito:sync_ad_users

Graph API Call

MethodEndpoint
GET/v1.0/users?$select=id,displayName,givenName,surname,mail,userPrincipalName,accountEnabled,department,jobTitle,mobilePhone,officeLocation,city,employeeId,employeeHireDate,employeeLeaveDateTime&$expand=manager($select=displayName,userPrincipalName,mail)&$top=500

Fields Captured

Graph FieldLocal ColumnDescription
iduser_idAzure AD object ID (primary key)
employeeIdemp_codeEmployee code from HR
accountEnabledaccount_enabledWhether account is active
givenNamefirst_nameFirst name
surnamelast_nameLast name
displayNamedisplay_nameFull display name
userPrincipalNameemailUPN / email
departmentdepartmentDepartment
jobTitledesignationJob title
officeLocationbase_locationOffice location
mobilePhonemobile_numberMobile number
manager.displayNamereporting_managerManager name
manager.userPrincipalNamereporting_manager_emailManager email
employeeHireDatedate_of_joiningHire date
employeeLeaveDateTimedate_of_exitLeave/exit date

sync_hrms_employees

Available

Fetches all employees from EmployWise API, applies customer-specific filters, stores in the HRMS snapshot, and auto-links to AD accounts by email match.

MCP Invocation

xito:sync_hrms

API Call

MethodEndpoint
GET{EMPLOYWISE_API_URL}?api_key={key}&data_type=0

Fields Captured

EmployWise FieldLocal ColumnDescription
emp_codeemp_codeEmployee code (primary key)
fnamefirst_nameFirst name
lnamelast_nameLast name
user_namedisplay_nameDisplay name
emailemailEmail address
budepartmentBusiness unit
designdesignationDesignation
locationbase_locationBase location
mobile_nomobile_numberMobile number
sup_namereporting_managerSupervisor name
supervisor_emailreporting_manager_emailSupervisor email
statusemployment_statusEmployment status
dojdate_of_joiningDate of joining
last_working_datedate_of_exitLast working date

Post-Sync: AD Linking

After import, the agent identifies unlinked HRMS employees, matches them to AD users by email, and populates the link automatically.

update_user_fields

Available

Compares 10 fields between HRMS and AD for every linked employee. Only updates fields that actually differ — one operation per user.

MCP Invocation

xito:update_fields

Graph API Call

MethodEndpointPayload
PATCH/v1.0/users/{userId}Only changed fields

Field Mapping (10 Fields)

Graph API FieldHRMS SourceAD Source
employeeIdemp_codeemp_code
givenNamefirst_namefirst_name
surnamelast_namelast_name
displayNamedisplay_namedisplay_name
departmentdepartmentdepartment
jobTitledesignationdesignation
officeLocationbase_locationbase_location
mobilePhonemobile_numbermobile_number
employeeHireDatedate_of_joiningdate_of_joining
employeeLeaveDateTimedate_of_exitdate_of_exit

update_managers

Available

Compares reporting manager emails between HRMS and AD. Sets, changes, or removes the manager reference in Azure AD.

MCP Invocation

xito:update_managers

Graph API Calls

ScenarioMethodEndpoint
Get current managerGET/v1.0/users/{userId}/manager?$select=userPrincipalName
Set / change managerPUT/v1.0/users/{userId}/manager/$ref
Remove managerDELETE/v1.0/users/{userId}/manager/$ref

Decision Logic

HRMS ManagerAD ManagerAction
boss@co.com(none)PUT — set manager
newboss@co.comoldboss@co.comPUT — change manager
(empty)boss@co.comDELETE — remove manager
boss@co.comboss@co.comSkip — no change

disable_leaver_accounts

Available

Finds HRMS employees whose exit date falls within the configured grace window and disables their Azure AD account.

MCP Invocation

xito:disable_accounts

Leaver Detection Logic

cutoff = today - grace_period_days
criteria: exit_date within grace window AND linked to AD account

Graph API Call

MethodEndpointPayload
PATCH/v1.0/users/{userId}{"accountEnabled": false}
🛈
Skips users already disabled. Also updates the local AD snapshot after disabling to keep state consistent.

cancel_licenses

Available

Retrieves all M365 license SKUs for each leaver and removes them, freeing up license seats.

MCP Invocation

xito:cancel_licenses

Graph API Calls

StepMethodEndpoint
Get licensesGET/v1.0/users/{userId}/licenseDetails
Remove licensePOST/v1.0/users/{userId}/assignLicense

Remove License Payload

{
    "addLicenses": [],
    "removeLicenses": ["<skuId>"]
}

remove_from_groups

Available

Removes leavers from all manually-assigned Azure AD groups. Dynamic groups are automatically detected and skipped.

MCP Invocation

xito:remove_groups

Graph API Calls

StepMethodEndpoint
Get membershipsGET/v1.0/users/{userId}/memberOf/microsoft.graph.group?$select=id,displayName,membershipRuleProcessingState
Remove from groupDELETE/v1.0/groups/{groupId}/members/{userId}/$ref
⚠️
Dynamic groups are automatically detected and skipped — Azure manages those memberships based on rules.

run_full_pipeline

Available

Orchestrates all 8 AI agents in sequence. If one agent fails, the pipeline continues to the next (resilient by design).

MCP Invocation

xito:run_pipeline

Execution Order

OrderToolPhase
1sync_ad_usersSync
2sync_hrms_employeesSync
3update_user_fieldsUpdate
4update_managersUpdate
5disable_leaver_accountsCleanup
6cancel_licensesCleanup
7remove_from_groupsCleanup
8sync_ad_usersRefresh

MCP Resources

Resources are read-only data endpoints that MCP clients can query to inspect the current state of Xito's data.

xito://ad_users

Coming Soon

Exposes the local Azure AD user snapshot. Query by email, department, account status, or date range.

xito://hr_ms_employees

Coming Soon

Exposes the local HRMS employee snapshot. Filter by emp_code, department, employment status, or exit date.

xito://execution_logs

Coming Soon

Exposes command execution logs — one record per pipeline run with start/end times, status, and summary.

xito://command_logs

Coming Soon

Exposes per-user operation logs with full JSON payloads — every field change, license cancellation, and group removal.

Data Model

Xito uses 4 data stores. Two for data snapshots and two for audit logging.

hr_ms_employees
HRMS snapshot from EmployWise
idbigintPK
emp_codestringUNIQUE
ad_user_idstring nullable
first_namestring nullable
last_namestring nullable
display_namestring nullable
emailstringINDEX
departmentstringINDEX
designationstring nullable
base_locationstring nullable
mobile_numberstring nullable
reporting_managerstring nullable
reporting_manager_emailstring nullable
employment_statusstring nullable
date_of_joiningdate nullable
date_of_exitdate nullable
ad_users
Azure AD snapshot from Microsoft Graph
idbigintPK
user_idstringUNIQUE
customer_reference_idstring nullable
emp_codestring nullable
account_enabledboolean
first_namestring nullable
last_namestring nullable
display_namestring nullable
emailstringINDEX
departmentstringINDEX
designationstring nullable
base_locationstring nullable
mobile_numberstring nullable
reporting_managerstring nullable
reporting_manager_emailstring nullable
date_of_joiningdate nullable
date_of_exitdate nullable
command_execution_logs
One row per tool/command run
idbigintPK
commandstring
start_timetimestamp
end_timetimestamp nullable
statusstring (running|success|partial_success|failed|skipped)
descriptiontext nullable
error_messagetext nullable
command_logs
Per-user operation log with JSON payload
idbigintPK
commandstringINDEX
command_execution_log_idbigint FK
operationstringINDEX
descriptiontext nullable
datajson nullable
statusstringINDEX
error_messagetext nullable

Operation Types in command_logs

OperationGenerated ByDescription
UPDATE_USER_FIELDSupdate_user_fieldsAD attribute patched from HRMS data
UPDATE_USER_MANAGERupdate_managersManager set, changed, or removed
DISABLE_USERdisable_leaver_accountsAD account disabled
CANCEL_LICENSEcancel_licensesM365 license SKU removed
REMOVE_FROM_GROUPremove_from_groupsUser removed from AD group

Microsoft Graph API Endpoints

Complete list of every Microsoft Graph endpoint Xito calls:

Authentication

MethodEndpointPurpose
POSThttps://login.microsoftonline.com/{tenant}/oauth2/v2.0/tokenObtain OAuth2 access token

User Operations

MethodEndpointUsed By
GET/v1.0/users?$select=...&$expand=manager&$top=500sync_ad_users
PATCH/v1.0/users/{userId}update_user_fields, disable_leaver_accounts

Manager Operations

MethodEndpointUsed By
GET/v1.0/users/{userId}/manager?$select=userPrincipalNameupdate_managers
PUT/v1.0/users/{userId}/manager/$refupdate_managers
DELETE/v1.0/users/{userId}/manager/$refupdate_managers

License Operations

MethodEndpointUsed By
GET/v1.0/users/{userId}/licenseDetailscancel_licenses
POST/v1.0/users/{userId}/assignLicensecancel_licenses

Group Operations

MethodEndpointUsed By
GET/v1.0/users/{userId}/memberOf/microsoft.graph.group?$select=...remove_from_groups
DELETE/v1.0/groups/{groupId}/members/{userId}/$refremove_from_groups

Required Permissions

The following Microsoft Graph Application permissions are required on the Azure AD app registration:

PermissionTypeUsed For
User.ReadWrite.AllApplicationRead users, update profiles, disable accounts
Directory.ReadWrite.AllApplicationManage manager relationships
Group.ReadWrite.AllApplicationRead group memberships, remove members
Organization.Read.AllApplicationRead license assignment details

Authentication

Xito uses the OAuth2 Client Credentials flow — no user interaction required.

POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded

client_id={ms_graph_client_id}
&scope=https://graph.microsoft.com/.default
&client_secret={ms_graph_client_secret}
&grant_type=client_credentials

The returned access_token is used as a Bearer token for all subsequent Graph API calls. Tokens are short-lived and never persisted to disk or database.

Error Handling

LevelBehavior
Pipelinerun_pipeline isolates each agent. One failure doesn't block the rest — the pipeline continues.
AgentEach AI agent processes users in batches. Per-user errors are caught and logged; processing continues.
APIHTTP errors and response parsing errors are caught and surfaced in the operation audit logs.
NotificationOn agent-level failure, a formatted alert is sent to the Teams webhook with agent name, error, and timestamp.

Status Values

StatusMeaning
runningAI agent is currently executing
successCompleted with zero errors
partial_successCompleted but some per-user operations failed
failedAgent-level failure
skippedAgent skipped due to invalid configuration

Teams Notifications

When an AI agent fails, Xito sends a formatted message to the configured Microsoft Teams incoming webhook:

┌───────────────────────────────────────┐
│  Agent        │  disable_accounts    │
│  Status       │  Failed              │
│  Message      │  HTTP Error: 403     │
│  Executed at  │  Feb 7, 2026         │
└───────────────────────────────────────┘

Configure the Teams webhook URL in the Xito settings to enable alerts. If not configured, notifications are silently skipped.

Scheduling

Configure Xito to run the AI pipeline on a regular interval using the built-in scheduler:

# Enable automated pipeline every 30 minutes
xito:schedule --interval=30m

# Or trigger manually at any time
xito:run_pipeline

You can also trigger individual AI agents for troubleshooting:

xito:sync_ad_users          # Just sync AD
xito:sync_hrms              # Just sync HRMS
xito:update_fields          # Just update fields
xito:disable_accounts       # Just disable leavers

© 2026 xito.co.in · AI-Powered Identity Lifecycle Automation · Home · Workflow