Skip to main content

NetSuite HCM MCP Server

Create a powerful Model Context Protocol (MCP) server for NetSuite Human Capital Management (HCM) in minutes with our AI Gateway. This guide walks you through setting up seamless HR integration with workforce management and instant OAuth authentication.

About NetSuite HCM API​

NetSuite HCM (SuitePeople) provides a comprehensive suite of HR capabilities including employee management, payroll, benefits administration, talent management, and workforce analytics. The API enables deep integration with all aspects of human capital management.

Key Capabilities​

  • Employee Management: Complete employee lifecycle
  • Payroll Processing: Integrated payroll management
  • Benefits Administration: Benefits enrollment and tracking
  • Time & Attendance: Time tracking and scheduling
  • Talent Management: Performance and development
  • Recruitment: Applicant tracking system
  • Compliance: HR compliance management
  • Analytics: Workforce insights and reporting

API Features​

  • Employee API: Employee data management
  • Payroll API: Payroll processing
  • Time API: Time and attendance
  • OAuth 2.0: Secure authentication
  • Benefits API: Benefits administration
  • Workflow API: HR processes
  • Custom Fields: Extensible data
  • Real-time Sync: Data synchronization

What You Can Do with NetSuite HCM MCP Server​

The MCP server transforms NetSuite HCM API into a natural language interface, enabling AI agents to:

Employee Management​

  • Employee Records

    • "Create new employee profile"
    • "Update employee information"
    • "Track employment history"
    • "Manage organizational structure"

  • Onboarding

    • "Start onboarding process"
    • "Assign onboarding tasks"
    • "Track completion status"
    • "Generate welcome packets"

  • Offboarding

    • "Initiate termination process"
    • "Calculate final pay"
    • "Manage exit interviews"
    • "Handle asset returns"

Payroll Management​

  • Payroll Processing

    • "Run payroll for period"
    • "Calculate gross wages"
    • "Process deductions"
    • "Generate pay stubs"

  • Tax Management

    • "Calculate payroll taxes"
    • "File tax returns"
    • "Manage withholdings"
    • "Track tax liabilities"

  • Compensation

    • "Process salary changes"
    • "Calculate bonuses"
    • "Manage commissions"
    • "Track compensation history"

Time & Attendance​

  • Time Tracking

    • "Record time entries"
    • "Approve timesheets"
    • "Track overtime"
    • "Monitor attendance"

  • Leave Management

    • "Process leave requests"
    • "Track PTO balances"
    • "Manage sick leave"
    • "Handle FMLA requests"

  • Scheduling

    • "Create work schedules"
    • "Manage shift assignments"
    • "Track coverage"
    • "Handle shift swaps"

Performance Management​

  • Reviews

    • "Schedule performance reviews"
    • "Track goals and objectives"
    • "Record feedback"
    • "Calculate ratings"

  • Development

    • "Create development plans"
    • "Track training completion"
    • "Manage certifications"
    • "Monitor skill gaps"

  • Succession Planning

    • "Identify key positions"
    • "Track succession candidates"
    • "Assess readiness"
    • "Plan transitions"

Benefits Administration​

  • Enrollment

    • "Manage open enrollment"
    • "Process benefit elections"
    • "Calculate contributions"
    • "Generate confirmations"

  • Benefits Tracking

    • "Monitor benefit usage"
    • "Track costs"
    • "Manage dependents"
    • "Process life events"

  • Compliance

    • "Track ACA compliance"
    • "Generate 1095 forms"
    • "Monitor eligibility"
    • "File required reports"

Recruitment​

  • Job Postings

    • "Create job requisitions"
    • "Post to job boards"
    • "Track applications"
    • "Screen candidates"

  • Applicant Tracking

    • "Manage candidate pipeline"
    • "Schedule interviews"
    • "Track feedback"
    • "Process offers"

  • Onboarding Prep

    • "Initiate background checks"
    • "Send offer letters"
    • "Collect documents"
    • "Prepare workspace"

HR Analytics​

  • Workforce Analytics

    • "Headcount reporting"
    • "Turnover analysis"
    • "Diversity metrics"
    • "Cost per employee"

  • Compensation Analysis

    • "Salary benchmarking"
    • "Pay equity analysis"
    • "Total rewards reporting"
    • "Budget forecasting"

  • Compliance Reporting

    • "EEO reporting"
    • "OSHA compliance"
    • "Labor law compliance"
    • "Audit trails"

HR Workflows​

  • Approval Processes

    • "Route approvals"
    • "Track status"
    • "Send reminders"
    • "Escalate delays"

  • Document Management

    • "Store employee documents"
    • "Manage versions"
    • "Track signatures"
    • "Ensure compliance"

  • Communication

    • "Send notifications"
    • "Broadcast announcements"
    • "Survey employees"
    • "Collect feedback"

Prerequisites​

  • Access to Cequence AI Gateway
  • NetSuite account with HCM/SuitePeople
  • API access enabled
  • HR administrator permissions

Step 1: Configure NetSuite HCM Access​

1.1 Enable HCM Features​

  1. Go to Setup > Company > Enable Features
  2. Under Employees tab, enable:
    • Human Resources Management
    • Payroll
    • Time Tracking
    • Advanced Benefits

1.2 Create HCM Integration​

  1. Navigate to Setup > Integration > Manage Integrations
  2. Create new integration:
    • Name: "AI Gateway HCM Integration"
    • OAuth 2.0: Enabled
    • Employee Access: Yes

1.3 Configure Permissions​

Required permissions:

  • Employees: Full
  • Payroll: Process
  • Time Tracking: Full
  • Benefits: Admin

1.4 Save Credentials​

Record:

  • Client ID
  • Client Secret
  • Account ID

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find NetSuite HCM API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: https://{accountId}.suitetalk.api.netsuite.com
  2. Select endpoints:
    • Employee endpoints
    • Payroll endpoints
    • Time endpoints
    • Benefits endpoints
  3. Click Next

Step 6: MCP Server Configuration​

  1. Name: "NetSuite HCM"
  2. Description: "Human capital management"
  3. Configure production mode
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: OAuth 2.0
  2. Configure OAuth URLs
  3. Enter credentials
  4. Set refresh token

Available NetSuite HCM API Scopes​

Employee Management​

  • Employee Data

    • Employee records
    • Personal information
    • Employment details
    • Organizational data

  • HR Processes

    • Onboarding
    • Transfers
    • Promotions
    • Terminations

Payroll & Compensation​

  • Payroll Processing

    • Payroll runs
    • Pay calculations
    • Deductions
    • Tax filing

  • Compensation

    • Salary management
    • Bonus processing
    • Commission calculation
    • Benefits costs

Time & Benefits​

  • Time Management

    • Time entry
    • Approval workflows
    • Leave management
    • Scheduling

  • Benefits Admin

    • Enrollment
    • Life events
    • Carrier feeds
    • Compliance

For HR Managers:

Employees (Full)
Time Tracking (Approve)
Benefits (Read)
Reports (Full)

For Payroll Admins:

Employees (Read)
Payroll (Full)
Time Tracking (Read)
Tax Filing (Full)

Step 8-10: Complete Setup​

Configure security, choose deployment, and deploy.

Using Your NetSuite HCM MCP Server​

With Claude Desktop​

{
  "servers": {
    "netsuite-hcm": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "oauth2",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "account_id": "your-account-id"
      }
    }
  }
}

Natural Language Commands​

  • "Show me all employees in the Engineering department"
  • "Process payroll for the current period"
  • "What's John Smith's PTO balance?"
  • "Generate headcount report by department"
  • "Start onboarding for new hire Jane Doe"

API Integration Example​

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    accountId: 'your-account-id'
  }
});

// Employee management
const newEmployee = await mcpClient.netsuite.hcm.createEmployee({
  firstName: 'Jane',
  lastName: 'Smith',
  email: 'jane.smith@company.com',
  hireDate: '2025-02-01',
  department: 'Engineering',
  jobTitle: 'Senior Software Engineer',
  manager: 'john.doe@company.com',
  salary: 120000,
  location: 'San Francisco',
  employmentType: 'Full-Time'
});

console.log(`Created employee: ${newEmployee.employeeId}`);

// Start onboarding
const onboarding = await mcpClient.netsuite.hcm.startOnboarding({
  employeeId: newEmployee.employeeId,
  template: 'engineering_onboarding',
  tasks: [
    {
      name: 'IT Setup',
      assignee: 'it@company.com',
      dueDate: '2025-01-28'
    },
    {
      name: 'Benefits Enrollment',
      assignee: 'hr@company.com',
      dueDate: '2025-02-01'
    },
    {
      name: 'Team Introduction',
      assignee: newEmployee.manager,
      dueDate: '2025-02-01'
    }
  ]
});

// Payroll processing
const payrollPeriod = await mcpClient.netsuite.hcm.getCurrentPayPeriod();
console.log(`\nProcessing payroll for: ${payrollPeriod.startDate} to ${payrollPeriod.endDate}`);

const payrollRun = await mcpClient.netsuite.hcm.runPayroll({
  payPeriod: payrollPeriod.id,
  employeeGroups: ['all'],
  includeBonus: true,
  processTaxes: true
});

console.log(`Payroll Summary:`);
console.log(`Total Employees: ${payrollRun.employeeCount}`);
console.log(`Gross Wages: $${payrollRun.grossWages.toLocaleString()}`);
console.log(`Total Deductions: $${payrollRun.totalDeductions.toLocaleString()}`);
console.log(`Net Pay: $${payrollRun.netPay.toLocaleString()}`);
console.log(`Employer Taxes: $${payrollRun.employerTaxes.toLocaleString()}`);

// Time and attendance
const timeEntry = await mcpClient.netsuite.hcm.submitTimeEntry({
  employee: 'john.doe@company.com',
  date: '2025-01-20',
  hours: {
    regular: 8,
    overtime: 2
  },
  project: 'CLIENT-001',
  notes: 'Worked late on deployment'
});

// Approve timesheet
const pendingTimesheets = await mcpClient.netsuite.hcm.getPendingTimesheets({
  approver: 'current',
  period: 'currentWeek'
});

for (const timesheet of pendingTimesheets) {
  console.log(`\nReviewing timesheet for ${timesheet.employeeName}`);
  console.log(`Total Hours: ${timesheet.totalHours}`);
  console.log(`Overtime: ${timesheet.overtimeHours}`);
  
  if (timesheet.totalHours <= 50) {
    await mcpClient.netsuite.hcm.approveTimesheet({
      timesheetId: timesheet.id,
      comments: 'Approved'
    });
  }
}

// Leave management
const leaveRequest = await mcpClient.netsuite.hcm.requestTimeOff({
  employee: 'jane.smith@company.com',
  type: 'PTO',
  startDate: '2025-03-15',
  endDate: '2025-03-22',
  reason: 'Family vacation',
  coverageNotes: 'John will cover urgent issues'
});

// Check PTO balance
const ptoBalance = await mcpClient.netsuite.hcm.getLeaveBalance({
  employee: 'jane.smith@company.com',
  leaveTypes: ['PTO', 'Sick', 'Personal']
});

console.log('\nLeave Balances:');
for (const balance of ptoBalance) {
  console.log(`${balance.type}: ${balance.available} days`);
  console.log(`  Accrued: ${balance.accrued}`);
  console.log(`  Used: ${balance.used}`);
  console.log(`  Pending: ${balance.pending}`);
}

// Performance management
const performanceReview = await mcpClient.netsuite.hcm.createPerformanceReview({
  employee: 'john.doe@company.com',
  reviewer: 'jane.manager@company.com',
  period: '2024-Annual',
  template: 'engineering_annual_review',
  dueDate: '2025-02-15'
});

// Set goals
const goals = await mcpClient.netsuite.hcm.setEmployeeGoals({
  employee: 'john.doe@company.com',
  year: 2025,
  goals: [
    {
      title: 'Complete AWS Certification',
      category: 'Professional Development',
      weight: 20,
      dueDate: '2025-06-30'
    },
    {
      title: 'Lead Migration Project',
      category: 'Project Delivery',
      weight: 40,
      dueDate: '2025-09-30'
    }
  ]
});

// Benefits enrollment
const openEnrollment = await mcpClient.netsuite.hcm.startOpenEnrollment({
  period: '2025',
  startDate: '2024-11-01',
  endDate: '2024-11-30',
  eligibleEmployees: 'all',
  benefitPlans: [
    'medical_ppo',
    'medical_hdhp',
    'dental',
    'vision',
    '401k',
    'life_insurance'
  ]
});

// Process benefit election
const benefitElection = await mcpClient.netsuite.hcm.processBenefitElection({
  employee: 'jane.smith@company.com',
  elections: [
    {
      plan: 'medical_ppo',
      coverage: 'employee_spouse',
      dependents: []
    },
    {
      plan: 'dental',
      coverage: 'employee_spouse'
    },
    {
      plan: '401k',
      contribution: {
        type: 'percentage',
        amount: 6
      }
    }
  ]
});

// HR analytics
const workforceAnalytics = await mcpClient.netsuite.hcm.getWorkforceAnalytics({
  metrics: [
    'headcount',
    'turnover',
    'averageTenure',
    'diversityMetrics',
    'compensationRatios'
  ],
  groupBy: ['department', 'location', 'jobLevel'],
  period: 'ytd'
});

console.log('\nWorkforce Analytics:');
console.log(`Total Headcount: ${workforceAnalytics.headcount}`);
console.log(`Turnover Rate: ${workforceAnalytics.turnoverRate}%`);
console.log(`Average Tenure: ${workforceAnalytics.averageTenure} years`);

// Compensation analysis
const compAnalysis = await mcpClient.netsuite.hcm.runCompensationAnalysis({
  analysisType: 'pay_equity',
  factors: ['gender', 'ethnicity', 'jobLevel', 'tenure'],
  adjustForPerformance: true
});

if (compAnalysis.inequities.length > 0) {
  console.log('\nPay Equity Issues Found:');
  for (const issue of compAnalysis.inequities) {
    console.log(`${issue.group}: ${issue.gapPercentage}% below market`);
    console.log(`  Affected Employees: ${issue.employeeCount}`);
    console.log(`  Recommended Adjustment: $${issue.totalAdjustment.toLocaleString()}`);
  }
}

// Compliance reporting
const complianceReports = await mcpClient.netsuite.hcm.generateComplianceReports({
  reports: ['EEO-1', 'ACA-1095', 'OSHA-300'],
  year: 2024,
  includeNarrative: true
});

// Real-time HR monitoring
const hrMonitor = await mcpClient.netsuite.hcm.startMonitoring({
  events: [
    'employeeTermination',
    'overtimeThreshold',
    'benefitEnrollment',
    'complianceDeadline'
  ],
  notifications: {
    channels: ['email', 'dashboard'],
    recipients: ['hr@company.com']
  }
});

hrMonitor.on('event', async (event) => {
  console.log(`HR Event: ${event.type}`);
  console.log(`Details: ${JSON.stringify(event.data)}`);
  
  if (event.type === 'employeeTermination') {
    await initiateOffboarding(event.data.employeeId);
  }
});

Common Use Cases​

Employee Lifecycle​

  • Recruitment and hiring
  • Onboarding automation
  • Performance management
  • Offboarding processes

Payroll & Compensation​

  • Payroll processing
  • Tax compliance
  • Benefits administration
  • Compensation planning

Time Management​

  • Time tracking
  • Leave management
  • Scheduling
  • Overtime monitoring

HR Analytics​

  • Workforce planning
  • Turnover analysis
  • Compensation benchmarking
  • Diversity reporting

Security Best Practices​

  1. Data Protection:

    • Encrypt sensitive data
    • PII access controls
    • Audit trails
    • GDPR compliance

  2. Access Control:

    • Role-based permissions
    • Manager hierarchies
    • Self-service limits
    • IP restrictions

  3. Compliance:

    • Regular audits
    • Policy enforcement
    • Document retention
    • Privacy controls

Troubleshooting​

Common Issues​

  1. Payroll Errors

    • Verify time entries
    • Check deductions
    • Review tax tables
    • Validate calculations

  2. Integration Issues

    • Sync employee data
    • Map custom fields
    • Check workflows
    • Review permissions

  3. Compliance Problems

    • Update regulations
    • Check report formats
    • Verify calculations
    • Review deadlines

Getting Help​