Skip to main content
Glama
SF Assistant MCP Server

SF Assistant MCP Server

SF Assistant MCP Server

MCP (Model Context Protocol) server for SAP SuccessFactors. Provides 52 tools across 15 categories that let an MCP client (Claude Code, Claude Desktop, etc.) query SF live data, generate business rules, validate imports, run analytics, compare instances, audit data, build cutover checklists, and populate client workbooks — all against a real SF tenant via OData v2.

Default tenant: This project ships configured against the VPMC Sandbox tenant (VPMCSandbox company ID on api8preview.sapsf.com). Every credential in the .env.example below is meant for that tenant — for any other tenant ask the functional lead for the right OIDC client and IAS host.

Built with FastMCP (Python) and httpx for async OData calls.


Prerequisites

  • Python 3.10+

  • uv package manager

  • Credentials for the VPMC Sandbox tenant (or whichever tenant you target):

    • SF user with OData API permissions

    • OIDC client registered in IAS with an SF dependency

  • An MCP client to consume the server (Claude Code, Claude Desktop, etc.)


Related MCP server: Happy MCP Server

Quick Start

# 1. Clone the monorepo and enter this project
git clone https://github.com/VeritasPrime/Jose_Avengers.git
cd Jose_Avengers/sf-mcp-server

# 2. Install dependencies
uv sync

# 3. Configure credentials
cp .env.example .env       # then edit .env with the values below

# 4. Run the MCP server (stdio transport, default)
uv run python main.py

# Or run with SSE transport
MCP_TRANSPORT=sse uv run python main.py

Environment Variables (VPMC Sandbox)

The server reads credentials from .env at the project root. Every variable below is required — helpers/credentials.py raises ValueError listing the missing ones if any is empty.

Variable

Required

Description

VPMC Sandbox value

SF_API_HOST

✅

SF API host (full URL or DC code)

https://api8preview.sapsf.com

SF_COMPANY_ID

✅

SF company ID (tenant)

VPMCSandbox

SF_USER_ID

✅

IAS username (NOT user@companyId)

(ask team lead)

SF_PASSWORD

✅

IAS password

(ask team lead)

IAS_HOST

✅

IAS tenant host

abkakgd3p.accounts.ondemand.com

OIDC_CLIENT_ID

✅

OIDC Client ID registered in IAS

(ask team lead)

OIDC_CLIENT_SECRET

✅

OIDC Client Secret from IAS

(ask team lead)

IAS_DEPENDENCY_NAME

✅

SF dependency name configured in IAS

SF_DEPENDENCY

SF_ALLOWED_HOSTS

—

Optional comma-separated extra API hosts accepted as data_center overrides (e.g. QA/PROD tenants for instance comparison)

(empty)

PII_STRICT_MODE

—

true (default) blocks HIGHLY CONFIDENTIAL queries; false only warns. Response scrubbing always applies.

true

Sample .env (VPMC Sandbox skeleton — fill the secrets):

# --- SF Tenant (VPMC Sandbox) ---
SF_API_HOST=https://api8preview.sapsf.com
SF_COMPANY_ID=VPMCSandbox
SF_USER_ID=<your-ias-user>
SF_PASSWORD=<your-ias-password>

# --- IAS / OIDC ---
IAS_HOST=abkakgd3p.accounts.ondemand.com
OIDC_CLIENT_ID=<oidc-client-id>
OIDC_CLIENT_SECRET=<oidc-client-secret>
IAS_DEPENDENCY_NAME=SF_DEPENDENCY

⚠️ Never commit .env. It is already in .gitignore. If you target a different tenant (DEV, QA, another sandbox), keep a separate .env.<tenant> file outside the repo.

All credentials can also be overridden per-request via tool parameters (data_center, auth_user_id, auth_password) for multi-tenant workflows.

Host allowlist. A data_center override (and instance_*_dc in the instance-comparison tools) must be a DC code from helpers/sf_client.DATA_CENTERS, the configured SF_API_HOST, or a host listed in SF_ALLOWED_HOSTS. Only https://<host> is accepted — no http, path, port, query or embedded credentials. Anything else is rejected before a token is requested, so the Bearer token can never be sent to an arbitrary host.

Web backend. The Gemini UI never exposes data_center, auth_user_id, auth_password or the instance_*_user / instance_*_password parameters to the model, and drops them if the model sends them anyway; those tools always run with the .env identity.


Authentication Flow (OIDC 2-step via IAS)

The server authenticates via SAP IAS (Identity Authentication Service) using the OIDC 2-step flow. See helpers/credentials.py:

  1. Step 1 — Password grant: POST {IAS_HOST}/oauth2/token with grant_type=password, returns an id_token.

  2. Step 2 — JWT-bearer exchange: POST {IAS_HOST}/oauth2/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, the id_token as assertion and resource=urn:sap:identity:application:provider:name:{IAS_DEPENDENCY_NAME}. Returns the SF access_token.

  3. The token is cached with a 60-second safety buffer before expiry. The cache key is the effective identity — (IAS_HOST, OIDC_CLIENT_ID, user, password fingerprint, API host) after applying per-request overrides — so different users or hosts never share a token. Concurrent requests for the same key are serialized by a per-key asyncio.Lock, so only one IAS round-trip happens. Cache lives in helpers/credentials._token_cache.

All subsequent OData calls use Authorization: Bearer {access_token}.


Project Structure

sf-mcp-server/
├── main.py                     # Entry point — creates FastMCP server, registers 52 tools
├── pyproject.toml              # Project config (uv/hatch)
├── uv.lock                     # Locked dependencies
├── .env                        # Credentials (NOT committed)
├── .mcp.json                   # MCP client config
├── CLAUDE.md                   # Claude Code project instructions
│
├── helpers/                    # Cross-cutting infrastructure
│   ├── credentials.py          # OIDC 2-step flow, token cache (per identity + host)
│   ├── credential_store.py     # Pluggable credential storage (env / GCP Secret Manager)
│   ├── sf_client.py            # Async OData client (DC resolution, Bearer auth, GET/POST/PUT/upsert)
│   ├── metadata_parser.py      # EDMX/CSDL XML → structured dicts (with SAP annotations)
│   ├── nl_query_parser.py      # Natural language → OData $filter (no LLM, pattern-based)
│   ├── template_parser.py      # CSV / Excel template parser for imports
│   ├── odata_utils.py          # OData helpers (escaping, pagination, etc.)
│   └── pii_filter.py           # PII validation + recursive scrubbing (enforced in SFClient.query_odata)
│
├── models/                     # Pydantic v2 models (domain objects)
│   ├── rule_spec.py            # RuleSpec, RuleCondition, RuleAction, ExecutionNotes
│   ├── field_validation.py     # FieldValidationResult, ValidationReport, TestCase, TestMatrix
│   ├── employee.py             # EmployeeProfile, OrgNode, EmployeeComparison, EmployeeHistoryRecord
│   ├── organization.py         # FoundationObject, OrgUnit, PositionDetail
│   └── data_import.py          # ImportFieldValidation, ImportValidationReport, UpsertRecord, UpsertResult
│
├── tools/                      # 52 MCP tools, one file per category
│   ├── discovery.py            # Discovery (4)
│   ├── rule_generation.py      # Business Rules — generation (2)
│   ├── rule_documentation.py   # Business Rules — docs (2)
│   ├── employee.py             # Employee (5)
│   ├── organization.py         # Organization (3)
│   ├── configuration.py        # Configuration (2)
│   ├── data_import.py          # Data Import (3)
│   ├── analytics.py            # Analytics (3)
│   ├── instance_compare.py     # Instance Comparison (4)
│   ├── audit.py                # Audit & Troubleshooting (5)
│   ├── documentation.py        # Documentation (4)
│   ├── migration.py            # Migration (4)
│   ├── mdf.py                  # MDF Objects (3)
│   ├── golive.py               # Go-Live (2)
│   ├── country.py              # Country support (3)
│   └── workbook_generator.py   # Workbook Generator (3)
│
├── knowledge/                  # Static JSON knowledge base
│   ├── entity_mapping.json             # Entity catalog with NL hints, dating templates, codes
│   ├── workbook_entity_mapping.json    # Workbook → SF entity column mappings
│   ├── base_objects.json               # Base objects → primary OData entities
│   ├── rule_scenarios.json             # Standard SF rule scenarios
│   ├── event_types.json                # Event types (onSave, onChange, onInit, validate)
│   ├── best_practices.json             # SAP rule configuration best practices
│   └── pii_classification.json         # Field-level PII classification
│
├── docs/                       # Project documentation
│   ├── MCP_SF_Technical_Documentation.docx
│   ├── MCP_SF_Value_Proposition.md
│   ├── SF_Assistant_MCP_Value_Proposition.docx
│   └── superpowers/            # Specs and implementation plans
│
├── scripts/                    # Operational scripts (not MCP tools)
│   ├── generate_pptx.py
│   ├── generate_word_doc.py
│   └── validate_workbooks.py
│
├── tests/                      # pytest suite (uses respx for HTTP mocking)
│   ├── test_sf_client.py
│   ├── test_metadata_parser.py
│   ├── test_models.py
│   └── test_pii_filter.py
│
└── Workbooks Templates/        # Reference Excel templates from clients
    ├── 1_26 Version_ JVL - Employee Field Data & RBP.xlsx
    ├── 1_26 Version_ JVL - Workflow Notifications & Messages.xlsx
    └── 1_26 Version_JVL - Object & Picklist Data.xlsx

Tools Reference (52 tools, 15 categories)

#

Category

Tools

1–4

Discovery

get_entity_metadata, list_entities, get_picklist_values, query_odata

5–8

Business Rules

validate_rule_fields, generate_rule_spec, generate_rule_doc, generate_rule_test

9–13

Employee

search_employees, get_employee_profile, get_org_chart, get_employee_history, compare_employees

14–16

Organization

get_org_structure, get_position_details, list_foundation_objects

17–18

Configuration

list_business_rules, get_permission_roles

19–21

Data Import

validate_import_template, generate_import_template, execute_upsert (dry_run by default)

22–24

Analytics

get_headcount, get_compensation_analytics, simulate_rule_impact

25–28

Instance Comparison

compare_instance_config, compare_picklists, compare_business_rules, compare_foundation_objects

29–33

Audit & Troubleshooting

audit_employee_data, find_data_anomalies, trace_rule_execution, check_permission_access, validate_effective_dating

34–37

Documentation

generate_functional_spec, generate_cutover_checklist, generate_data_dictionary, generate_test_script

38–41

Migration

validate_migration_file, generate_migration_sequence, reconcile_data, generate_purge_file

42–44

MDF

get_mdf_object_definition, generate_mdf_import_template, list_mdf_objects

45–46

Go-Live

run_go_live_checks, generate_reconciliation_report

47–49

Country

get_country_specific_fields, validate_country_compliance, generate_country_config_guide

50–52

Workbook Generator

generate_fo_workbook, generate_workflow_workbook, generate_rules_workbook

Typical Workflows

Goal

Pipeline

Build a business rule

get_entity_metadata → validate_rule_fields → generate_rule_spec → generate_rule_doc / generate_rule_test

Find and inspect employees

search_employees → get_employee_profile → get_org_chart

Run an import

generate_import_template → validate_migration_file → execute_upsert

Cutover prep

compare_instance_config → generate_cutover_checklist → run_go_live_checks

Country setup

get_country_specific_fields → generate_country_config_guide → validate_country_compliance

Populate client workbooks

generate_fo_workbook / generate_workflow_workbook / generate_rules_workbook


MCP Client Configuration

To use the server from Claude Code, add this to .mcp.json at the monorepo root (or wherever your MCP client reads from):

{
  "mcpServers": {
    "sf-assistant": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/absolute/path/to/Jose_Avengers/sf-mcp-server"
    }
  }
}

For Claude Desktop, point its claude_desktop_config.json at the same command. The server responds on stdio by default; set MCP_TRANSPORT=sse to expose it over HTTP/SSE instead.


Running Tests

uv sync --dev          # install dev deps (pytest, pytest-asyncio, respx)
uv run pytest          # run all tests
uv run pytest -v       # verbose
uv run pytest tests/test_pii_filter.py -v   # one file

Tests use respx to mock httpx calls — no live SF tenant needed.


Troubleshooting

Symptom

Likely cause / fix

ValueError: Missing OIDC config: ...

One or more env vars in .env are empty. The error message lists exactly which ones.

ValueError: No API host configured

SF_API_HOST is empty. Set it to a full URL or a DC code (e.g., DC4, DC8_PREVIEW).

OIDC Step 1 failed (401)

Wrong SF_USER_ID / SF_PASSWORD, or user is locked in IAS.

OIDC Step 2 failed (400)

Wrong OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, or IAS_DEPENDENCY_NAME. The IAS dependency name must match exactly the one registered in IAS for the SF app.

httpx.ConnectTimeout

Network / VPN / firewall blocking IAS or SF API. Default timeouts: 30 s for IAS, 60 s for OData (90 s for full $metadata).

403 Forbidden on OData calls

The SF user lacks OData API permissions on the entity. Check Admin Center → Manage Permission Roles.

Unknown data center 'XXX'

SF_API_HOST is neither a known DC code nor a valid URL. Use a full URL or one of the codes in helpers/sf_client.py.

Host 'x' is not an allowed SuccessFactors API host

The data_center override is not a DC code, not SF_API_HOST, and not in SF_ALLOWED_HOSTS. Add the tenant host to SF_ALLOWED_HOSTS if it is legitimate.

PIIPolicyError / SF API Error 403 ... Blocked fields

The query selects, filters on, or expands a HIGHLY CONFIDENTIAL field/entity (knowledge/pii_classification.json). Blocked centrally in SFClient.query_odata before any request is sent.


Conventions

  • Async everywhere. All SF calls use httpx.AsyncClient with asyncio.Semaphore(5) for rate limiting.

  • Effective-dated entities (EmpJob, EmpCompensation, PerPersonal) require date filters — the tools enforce this.

  • execute_upsert defaults to dry_run=True for safety; flip explicitly to commit.

  • OData v2 lacks $apply / groupby — analytics tools aggregate client-side with $top limits.

  • One MCP server only. Each tools/<category>.py may build a local FastMCP for testing, but main.py is the single registration point exposed to clients.


Dependencies

Package

Version

Purpose

fastmcp

>= 3.0.0

MCP server framework

httpx

>= 0.27.0

Async HTTP client

pydantic

>= 2.0.0

Data models / validation

python-dotenv

(transitive)

Load .env

openpyxl

(transitive)

Workbook generation / template parsing

Optional extras:

  • uv sync --extra gcp — adds google-cloud-secret-manager for the GCPSecretManagerStore credential backend.

Dev: pytest, pytest-asyncio, respx.


Ownership

Role

Person

Functional Lead

José Machado

Stakeholder

Jabin Geary

Repo owner

Ryan Summerskill

Engineers

Jose Avengers (4 engineers, India)

For questions on tools, OIDC setup, or VPMC Sandbox access — ping the functional lead.

Web frontend (optional)

A local web UI lets you chat with Gemini, which orchestrates the 52 MCP tools.

Install

uv sync --extra frontend
cd frontend && npm install

Configure

Add to .env:

GEMINI_API_KEY=...
GEMINI_MODEL=gemini-3-pro-preview
FRONTEND_BACKEND_PORT=8001
FRONTEND_CORS_ORIGIN=http://localhost:5173

Run

In two terminals:

# 1. Backend (FastAPI + SSE)
uv run python -m backend.app

# 2. Frontend (Vite)
cd frontend && npm run dev

Open the Vite URL printed in the second terminal.

Safety

execute_upsert always pops a confirmation modal before running. Choose Approve, Reject, or Force dry_run. Direct sidebar execution of execute_upsert is forced to dry_run=true.

Available Tools

52 tools
audit_employee_dataB

Run data integrity checks on a single employee.

Validates: job info exists, employment record exists, personal info complete, effective dates are consistent, manager is valid, compensation exists, email is present. Returns findings with severity levels.

Inputs: user_id (required), checks, data_center, auth_user_id, +1 more. Returns: object

check_permission_accessB

Look up permission role details.

Queries RBPRole and FODynamicRole to find matching roles. Note: Actual field-level RBP permissions are not exposed via OData v2. This tool helps identify which roles exist and their basic properties.

Inputs: role_name (required), entity, data_center, auth_user_id, +1 more. Returns: object

compare_business_rulesA

Compare business rules between two SF instances.

Shows rules that exist in one instance but not the other, and differences in rule properties (scenario, base object, status). Essential for cutover validation.

Inputs: rule_name, instance_a_dc, instance_b_dc, instance_a_user, +3 more. Returns: object

compare_employeesB

Compare multiple employees side by side.

Fetches profiles for all specified employees in parallel and returns a comparison matrix highlighting differences. Useful for auditing or verifying employee data consistency.

Inputs: user_ids (required), data_center, auth_user_id, auth_password, +1 more. Returns: object

compare_foundation_objectsB

Compare Foundation Objects between two SF instances.

Detects FO records that exist in one instance but not the other, and field differences for matching records (by externalCode).

Inputs: fo_type (required), instance_a_dc, instance_b_dc, instance_a_user, +3 more. Returns: object

compare_instance_configA

Compare entity metadata between two SF instances.

Detects fields that exist in one instance but not the other, type mismatches, and annotation differences (editability, labels). Essential for cutover validation (DEV → QA → PROD).

Inputs: entity (required), instance_a_dc (required), instance_b_dc (required), instance_a_user, +3 more. Returns: object

compare_picklistsA

Compare picklist values between two SF instances.

Detects values that exist in one instance but not the other, and label differences for matching values. Critical for ensuring picklist consistency during migrations.

Inputs: picklist_id (required), instance_a_dc (required), instance_b_dc (required), instance_a_user, +3 more. Returns: object

execute_upsertA

Execute an upsert operation against an SF entity.

IMPORTANT: Defaults to dry_run=True. In dry_run mode, validates all records against metadata without making any changes. Set dry_run=False to actually write data.

Records are processed in batches. Each record is sent as an individual OData POST (upsert) to the entity endpoint.

Inputs: records (required), entity_name (required), dry_run, batch_size, +3 more. Returns: object

find_data_anomaliesA

Detect data anomalies in SF entities.

Types:

  • 'empty': Find records where the specified field is blank/null

  • 'duplicates': Find duplicate values in the specified field

  • 'future_dates': Find date fields with values in the future

  • 'orphan': Find records referencing non-existent FO/user records

Inputs: field (required), entity (required), anomaly_type (required), data_center, +4 more. Returns: object

generate_country_config_guideA

Generate a configuration guide for a specific country.

Includes:

  • Required PerGlobalInfo fields and their purpose

  • Picklists that need to be configured

  • Compliance requirements and notes

  • Typical business rules to implement

  • Data validation recommendations

No SF API call needed — uses knowledge base.

Inputs: country_code (required), language. Returns: object

generate_cutover_checklistA

Generate a cutover checklist for migrating configuration from DEV to PROD.

Produces an ordered checklist based on entity dependencies, including:

  • Foundation Objects in correct load order

  • Picklist configurations

  • Business rules

  • User/employee data in dependency order

Essential for go-live planning.

Inputs: entities (required), language, data_center, auth_user_id, +3 more. Returns: object

generate_data_dictionaryB

Generate a complete data dictionary for multiple SF entities.

For each entity, produces a field-by-field reference with: name, type, label, key status, required, creatable, updatable, picklist info.

Output is structured as CSV-exportable rows for easy import into Excel.

Inputs: entities (required), language, data_center, auth_user_id, +2 more. Returns: object

generate_fo_workbookA

Generate a populated Object & Picklist Data workbook from the live SF instance.

Reads all Foundation Objects (Legal Entity, Business Unit, Division, Department, Cost Center, Job Family, Job Function, Job Code, Location, Pay Grade, Pay Range, Pay Group, Pay Component, Pay Component Group, Event Reason, Time Type, etc.) and Picklists, then writes them to a dated Excel file in exports/.

The output file format exactly matches the client template column layout. Header rows 1-2 are preserved from the template. Data starts at row 3.

Returns: { file, sheets_populated, sheets_skipped, summary, warnings }

Inputs: entities, data_center, auth_user_id, auth_password. Returns: object

generate_functional_specB

Generate a functional specification document for an SF entity/portlet.

Produces a structured spec with:

  • Entity overview and key fields

  • Field mapping (name, type, label, editability, picklist info)

  • Configured business rules (optional)

  • Navigation properties / relationships

  • Recommendations

Output is structured for easy conversion to Word/PDF.

Inputs: entity (required), language, data_center, auth_user_id, +3 more. Returns: object

generate_import_templateB

Generate an import template with correct field headers for an SF entity.

Creates a CSV-ready template structure with field names, types, and whether they are key/required fields. Optionally includes valid picklist values to help with data preparation.

Inputs: entity_name (required), data_center, auth_user_id, auth_password, +2 more. Returns: object

generate_mdf_import_templateB

Generate an import template for an MDF object.

Creates a CSV-ready template with key fields, required fields, and optionally all editable fields. Includes field type info as comments.

Inputs: object_name (required), data_center, auth_user_id, auth_password, +1 more. Returns: object

generate_migration_sequenceA

Calculate the correct load order for a set of entities based on dependencies.

Uses the predefined dependency graph from knowledge base to ensure Foundation Objects are loaded before employee data, employment before job info, etc.

Returns the ordered sequence with dependency notes.

Inputs: entities (required). Returns: object

generate_purge_fileA

Generate a purge/delete file for SF import.

Fetches records matching the filter and returns them with the correct key fields for deletion via SF import. Output includes CSV content ready for the SF Import tool's purge mode.

IMPORTANT: Review the records carefully before using for deletion.

Inputs: entity (required), filter_expr (required), data_center, auth_user_id, +1 more. Returns: object

generate_reconciliation_reportA

Generate a reconciliation report comparing expected vs actual record counts.

Queries each entity for its record count and compares against expected values from the source system. Essential for cutover day validation.

Inputs: entities (required), data_center, auth_user_id, auth_password, +1 more. Returns: object

generate_rule_docA

Generate step-by-step implementation documentation for a business rule.

Produces a consultant-ready guide for creating the rule in the SAP SuccessFactors Rule Editor UI, including:

  • Navigation steps in Admin Center

  • Rule creation dialog values

  • Each IF/THEN condition to configure

  • HRIS Element assignment instructions

  • Event type configuration

  • Post-implementation verification steps

Inputs: rule_spec (required), language, output_format. Returns: object

generate_rule_specA

Generate a complete Business Rule specification from a natural language requirement.

This tool:

  1. Queries the SF instance metadata to identify relevant fields

  2. Validates all referenced fields and picklist values exist

  3. Builds IF/THEN/ELSE condition logic

  4. Generates naming, execution notes, and best practice recommendations

The output can be passed to generate_rule_doc (documentation) and generate_rule_test (test cases).

Example requirement: "When saving Job Information, if the employee's country is Peru and employee class is Full-Time, set pay group to PG_PE_FT. If Part-Time, set to PG_PE_PT."

Inputs: event_type (required), base_object (required), requirement (required), rule_scenario (required), +6 more. Returns: object

generate_rules_workbookB

Populate the Employee Central Rules sheet in the Employee Field Data & RBP workbook.

Reads all Business Rules from RuleHeaderBean and maps them to the 8 columns: HRIS Element / Object | Rule Name | Rule Trigger Type | Field to Trigger onChange Rule | Functional Description | Rule Description | Rule Base Object | Rule ID

All other sheets in the RBP workbook are preserved unchanged (manual).

Returns: { file, rules_count, warnings }

Inputs: data_center, auth_user_id, auth_password, scenario_filter. Returns: object

generate_rule_testA

Generate a comprehensive test case matrix for a business rule.

Produces test cases covering:

  • Each condition path (positive scenarios)

  • Edge cases (empty fields, null values, boundary conditions)

  • Negative cases (conditions that should NOT trigger the rule)

  • Coverage matrix showing which paths are tested

Each test case includes preconditions, action, and expected results.

Inputs: rule_spec (required), include_edge_cases, include_negative_tests. Returns: object

generate_test_scriptB

Generate an end-to-end test script for a specific HR scenario.

Produces step-by-step test instructions including:

  • Preconditions

  • Step-by-step actions

  • Expected results at each step

  • Business rule validations

  • Country-specific checks

No SF API calls needed — uses knowledge base.

Inputs: scenario (required), country, language. Returns: object

generate_workflow_workbookB

Generate a populated Workflow Notifications & Messages workbook from the live SF instance.

Populates: Workflows Tab, WF Processes, Dynamic Roles, Workflow Groups, Alert Messages, Message Definitions, Email Notification Templates.

Workflow Configuration Settings is preserved unchanged (manual — no OData API).

Returns: { file, sheets_populated, sheets_skipped, summary, warnings }

Inputs: data_center, auth_user_id, auth_password. Returns: object

get_compensation_analyticsA

Get compensation statistics (average, min, max, median compa-ratio and range penetration) grouped by a scope field.

Queries EmpCompensation joined with EmpJob for the scope field. Note: Limited to 5000 records for performance.

Inputs: scope_field (required), data_center, scope_value, auth_user_id, +1 more. Returns: object

get_country_specific_fieldsA

Get country-specific fields for a PerGlobalInfo entity.

Returns the required fields, common picklists, compliance notes, and typical business rules for the specified country. Covers: COL (Colombia), MEX (Mexico), PER (Peru), CHL (Chile), ARG (Argentina), BRA (Brazil), USA (United States), ESP (Spain).

Optionally fetches live metadata from the instance to compare against the knowledge base.

Inputs: country_code (required), data_center, auth_user_id, auth_password, +1 more. Returns: object

get_employee_historyB

Get the history of changes for an employee.

Retrieves effective-dated records ordered by date descending, showing the timeline of changes. Supports job (EmpJob), compensation (EmpCompensation), and employment (EmpEmployment) history.

Inputs: user_id (required), limit, data_center, auth_user_id, +2 more. Returns: object

get_employee_profileA

Get a complete employee profile by assembling data from multiple SF entities.

Fetches User, EmpJob, EmpCompensation, EmpEmployment, PerPersonal, PerEmail, and PerPhone in parallel for maximum performance.

Sections can be filtered to reduce API calls. Effective-dated entities (job, compensation, personal) use as_of_date for point-in-time queries.

Inputs: user_id (required), sections, as_of_date, data_center, +2 more. Returns: object

get_entity_metadataA

Retrieve structured metadata for a specific SAP SuccessFactors entity.

Returns the entity's properties (fields), their types, whether they are editable, required, or picklist-based, plus navigation properties (relationships).

Use this to understand what fields are available on an entity before building business rules that reference those fields.

Inputs: entity_name (required), data_center, auth_user_id, auth_password. Returns: object

get_headcountB

Get headcount grouped by a specific field.

Aggregates employee counts by department, company, location, country, etc. Computed client-side since OData v2 doesn't support $apply/groupby.

Note: For large organizations, results are based on up to 5000 active employee records.

Inputs: group_by (required), filters, data_center, auth_user_id, +2 more. Returns: object

get_mdf_object_definitionA

Get complete metadata for an MDF object.

Returns all fields, types, labels, editability flags, picklist associations, and navigation properties. Works for both custom (cust_*) and standard MDF objects.

Inputs: object_name (required), data_center, auth_user_id, auth_password. Returns: object

get_org_chartA

Get the organizational chart centered on a specific employee.

Navigates upward through managerId to show the management chain, and downward to show direct reports. Uses EmpJob for manager relationships and User for names/titles.

Inputs: user_id (required), depth_up, depth_down, data_center, +2 more. Returns: object

get_org_structureB

Get organizational structure at a specific level.

Queries Foundation Object entities (FOCompany, FODepartment, etc.) to show the organizational hierarchy. Can optionally include headcount per unit by cross-referencing with EmpJob.

Levels: company, division, department, business_unit, cost_center, location, job_code, pay_grade.

Inputs: level (required), active_only, data_center, parent_code, +3 more. Returns: object

get_permission_rolesA

List permission roles configured in the SAP SuccessFactors instance.

Queries RBPRole (Role-Based Permissions) and/or FODynamicRole entities. Useful for understanding the security model and role assignments.

Inputs: role_name, role_type, data_center, max_results, +2 more. Returns: object

get_picklist_valuesA

Get all options (values) for a specific picklist in SAP SuccessFactors.

Picklists are dropdown/select fields. Returns the external code (API value), label (display text), and status for each option.

Use this to validate that picklist values referenced in business rules actually exist in the target instance.

Inputs: picklist_id (required), data_center, auth_user_id, auth_password, +1 more. Returns: object

get_position_detailsB

Get position details from Position Management.

Retrieve specific positions or filter by department/vacancy status. Returns position code, name, department, job code, incumbent, and vacancy status.

Inputs: department, data_center, max_results, vacant_only, +3 more. Returns: object

list_business_rulesB

List business rules configured in the SAP SuccessFactors instance.

Queries the RuleHeaderBean entity to show configured rules. Filter by scenario, base object, or search by name. Useful to understand what rules are already in place before creating new ones.

Inputs: data_center, max_results, name_search, auth_user_id, +3 more. Returns: object

list_entitiesA

List all available OData entities in the SAP SuccessFactors instance.

Returns entity set names from $metadata. Optionally filter by prefix (e.g., 'Emp' for employment entities, 'FO' for Foundation Objects, 'Per' for person entities).

Note: Fetching full metadata can be slow (5-30 seconds). Use filter_prefix or query a specific entity with get_entity_metadata instead.

Inputs: data_center, auth_user_id, auth_password, filter_prefix. Returns: object

list_foundation_objectsA

List Foundation Objects of any type.

A flexible tool to query any Foundation Object entity. Use friendly names like 'company', 'department', 'location' or direct entity names like 'FOCompany'.

Foundation Objects are the reference/master data that define the organizational structure in SuccessFactors.

Inputs: fo_type (required), select, active_only, data_center, +4 more. Returns: object

list_mdf_objectsA

List all MDF objects configured in the SF instance.

Categories:

  • 'custom': Only cust_* objects (custom MDF)

  • 'standard': Only standard SAP MDF objects

  • 'all': Everything

Many instances have 50+ custom MDF objects with unclear purposes. This tool helps inventory them.

Inputs: category, data_center, name_search, auth_user_id, +1 more. Returns: object

query_odataA

Execute a flexible OData query against any SAP SuccessFactors entity.

Supports filtering, field selection, navigation expansion, pagination, and sorting.

Examples:

  • Active employees: entity='EmpEmployment', filter="endDate eq datetime'9999-12-31T00:00:00'"

  • Company details: entity='FOCompany', select='externalCode,name,country'

  • Job info with company: entity='EmpJob', expand='companyNav', top=5

Inputs: entity (required), top, skip, expand, +6 more. Returns: object

reconcile_dataB

Reconcile data after migration — compare expected vs actual record counts.

Can reconcile at entity level (total count) or grouped by a field (e.g., count per company, per department). Essential for cutover day validation.

Inputs: entity (required), data_center, filter_expr, auth_user_id, +3 more. Returns: object

run_go_live_checksB

Run pre-go-live validation checks on the SF instance.

Validates:

  • Critical: Employees without jobs, orphan records, missing key dates

  • Important: Vacant positions with incumbents, self-referencing managers, inactive FOs in use

  • Recommended: Email/phone completeness, compensation completeness

Returns a pass/fail report for each check with sample affected records.

Inputs: max_sample, data_center, auth_user_id, auth_password, +1 more. Returns: object

search_employeesA

Search for employees using natural language queries.

Supports searching by:

  • Name: "John", "John Smith", "Smith"

  • Department: "department 40000013", "dept HR"

  • Country: "country COL", "employees in Colombia"

  • Status: "active employees", "terminated employees"

  • Location: "location NYC"

  • Manager: "reports to admin", "manager 12345"

  • Company: "company 1000"

  • User ID: "user admin"

Combinations work too: "active employees in department 40000013"

Inputs: query (required), data_center, max_results, auth_user_id, +3 more. Returns: object

simulate_rule_impactA

Simulate the impact of a business rule against real employee data.

Evaluates the rule's conditions against actual employee records and shows which employees would be affected and what changes would be made. This is a read-only simulation — no data is modified.

Useful for impact analysis before deploying a new rule.

Inputs: rule_spec (required), data_center, sample_size, auth_user_id, +2 more. Returns: object

trace_rule_executionA

Trace which business rules would apply to an employee for a given event.

Fetches the employee's current data, then checks each configured rule's conditions against that data. Shows which rules match, which don't, and why. Invaluable for debugging "why did this field get this value?"

Inputs: user_id (required), event_type (required), base_object (required), data_center, +2 more. Returns: object

validate_country_complianceC

Validate that employees in a country have all required country-specific fields.

Checks each employee against the country's required fields (from knowledge base) and reports which fields are missing or empty. Essential for payroll and compliance readiness.

Inputs: country_code (required), user_ids, data_center, auth_user_id, +2 more. Returns: object

validate_effective_datingB

Validate effective dating for time-sliced entities.

Detects gaps and overlaps in effective-dated records. These are the most silent and destructive data bugs — an employee may appear to have no active record on a specific date due to a gap.

Inputs: entity (required), user_ids, data_center, auth_user_id, +2 more. Returns: object

validate_import_templateA

Validate an import template's headers and sample data against SF metadata.

Checks that all column headers correspond to actual fields on the target entity, identifies missing key/required fields, and validates sample data types. Use this before executing an import to catch errors early.

Inputs: headers (required), entity_name (required), data_center, sample_rows, +2 more. Returns: object

validate_migration_fileA

Deep validation of a migration/import CSV file.

Validates:

  • Column headers match entity metadata

  • Key fields are present and populated

  • Data types are correct (dates, numbers, strings)

  • Required fields are populated

  • Picklist values exist (strict mode)

  • Foreign key references exist (strict mode)

  • Date format consistency

Returns detailed error report per row.

Inputs: entity (required), file_content (required), strict, data_center, +2 more. Returns: object

validate_rule_fieldsA

Validate that fields, entities, and picklist values referenced in a proposed business rule actually exist in the SAP SuccessFactors instance.

For each field:

  1. Verifies the entity exists in $metadata

  2. Verifies the field exists on that entity

  3. Checks the field type (string, date, picklist, number)

  4. If picklist values are provided, verifies they exist

  5. Checks if the field is editable (creatable or updatable)

Example fields_to_validate: [ {"field": "payGroup", "entity": "EmpJob", "values": ["PG_PE_FT", "PG_PE_PT"]}, {"field": "employeeClass", "entity": "EmpJob", "values": ["FT", "PT"]}, {"field": "countryOfCompany", "entity": "EmpJob"} ]

Inputs: fields_to_validate (required), base_object, data_center, auth_user_id, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 52 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap among similar validation tools (e.g., validate_import_template vs validate_migration_file) and workbook generation tools (generate_fo_workbook vs generate_rules_workbook). Descriptions help clarify differences, but an agent might occasionally select the wrong one.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., audit_employee_data, compare_employees, generate_cutover_checklist). Verbs are imperative and clear, with no mixed casing or inconsistent styles.

    Tool Count3/5

    With 52 tools, the set is relatively large. While SuccessFactors is complex and the tools cover many operations, the count feels slightly excessive. Some clustering of similar tools (e.g., multiple validate_* or generate_* tools) could be consolidated, but the scope still justifies the number.

    Completeness5/5

    The tool set covers an extensive range of operations: data integrity checks, instance comparisons, migration support, rule lifecycle (spec, test, simulation, trace), validation, employee data retrieval, and more. There are no obvious gaps for the stated purpose of assisting with SF configuration and migration.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables querying SAP SuccessFactors OData API metadata and managing Role-Based Permission (RBP) configurations. It provides tools for retrieving entity metadata, listing permission roles, and inspecting user-specific access rights through MCP-compatible clients.
      29
      15
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server for BambooHR with 47 tools covering employee management, time off, reports, benefits, payroll, goals, training, files, and webhooks, plus 18 React-based UI apps.
      MIT