SF Assistant MCP Server
This MCP server lets an MCP client work directly with a live SAP SuccessFactors tenant across 52 tools for querying, validating, generating, auditing, comparing, migrating, and documenting SF configuration and data.
Query live SF OData data and inspect entity metadata, entities, picklists, and relationships.
Generate, validate, document, test, and simulate SAP SuccessFactors business rules.
Search employees, retrieve profiles, org charts, history, and compare employees side by side.
Explore org structures, positions, foundation objects, business rules, and permission roles.
Validate and generate import templates, and run safe upserts with dry-run by default.
Run headcount and compensation analytics and simulate rule impact on real employee data.
Compare configuration, picklists, business rules, and foundation objects between two SF instances.
Audit employee data, find anomalies, trace rule execution, check permissions, and validate effective dating.
Generate functional specs, cutover checklists, data dictionaries, and end-to-end test scripts.
Validate migration files, calculate migration load order, reconcile data, and generate purge files.
Work with MDF objects and generate MDF import templates.
Run go-live checks and generate reconciliation reports.
Get country-specific fields, validate country compliance, and generate country configuration guides.
Populate client Excel workbooks for foundation objects, workflows, and business rules.
Provides tools to query SAP SuccessFactors data, manage business rules, validate imports, run analytics, compare instances, audit data, generate migration sequences, and create cutover checklists via OData v2.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SF Assistant MCP Server list employees hired this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 (
VPMCSandboxcompany ID onapi8preview.sapsf.com). Every credential in the.env.examplebelow 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.pyEnvironment 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 (full URL or DC code) |
|
| ✅ | SF company ID (tenant) |
|
| ✅ | IAS username (NOT | (ask team lead) |
| ✅ | IAS password | (ask team lead) |
| ✅ | IAS tenant host |
|
| ✅ | OIDC Client ID registered in IAS | (ask team lead) |
| ✅ | OIDC Client Secret from IAS | (ask team lead) |
| ✅ | SF dependency name configured in IAS |
|
| — | Optional comma-separated extra API hosts accepted as | (empty) |
| — |
|
|
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:
Step 1 — Password grant:
POST {IAS_HOST}/oauth2/tokenwithgrant_type=password, returns anid_token.Step 2 — JWT-bearer exchange:
POST {IAS_HOST}/oauth2/tokenwithgrant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, theid_tokenas assertion andresource=urn:sap:identity:application:provider:name:{IAS_DEPENDENCY_NAME}. Returns the SFaccess_token.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-keyasyncio.Lock, so only one IAS round-trip happens. Cache lives inhelpers/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.xlsxTools Reference (52 tools, 15 categories)
# | Category | Tools |
1–4 | Discovery |
|
5–8 | Business Rules |
|
9–13 | Employee |
|
14–16 | Organization |
|
17–18 | Configuration |
|
19–21 | Data Import |
|
22–24 | Analytics |
|
25–28 | Instance Comparison |
|
29–33 | Audit & Troubleshooting |
|
34–37 | Documentation |
|
38–41 | Migration |
|
42–44 | MDF |
|
45–46 | Go-Live |
|
47–49 | Country |
|
50–52 | Workbook Generator |
|
Typical Workflows
Goal | Pipeline |
Build a business rule |
|
Find and inspect employees |
|
Run an import |
|
Cutover prep |
|
Country setup |
|
Populate client workbooks |
|
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 fileTests use respx to mock httpx calls — no live SF tenant needed.
Troubleshooting
Symptom | Likely cause / fix |
| One or more env vars in |
|
|
| Wrong |
| Wrong |
| Network / VPN / firewall blocking IAS or SF API. Default timeouts: 30 s for IAS, 60 s for OData (90 s for full |
| The SF user lacks OData API permissions on the entity. Check Admin Center → Manage Permission Roles. |
|
|
| The |
| The query selects, filters on, or expands a HIGHLY CONFIDENTIAL field/entity ( |
Conventions
Async everywhere. All SF calls use
httpx.AsyncClientwithasyncio.Semaphore(5)for rate limiting.Effective-dated entities (EmpJob, EmpCompensation, PerPersonal) require date filters — the tools enforce this.
execute_upsertdefaults todry_run=Truefor safety; flip explicitly to commit.OData v2 lacks
$apply/ groupby — analytics tools aggregate client-side with$toplimits.One MCP server only. Each
tools/<category>.pymay build a localFastMCPfor testing, butmain.pyis the single registration point exposed to clients.
Dependencies
Package | Version | Purpose |
| >= 3.0.0 | MCP server framework |
| >= 0.27.0 | Async HTTP client |
| >= 2.0.0 | Data models / validation |
| (transitive) | Load |
| (transitive) | Workbook generation / template parsing |
Optional extras:
uv sync --extra gcp— addsgoogle-cloud-secret-managerfor theGCPSecretManagerStorecredential 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 installConfigure
Add to .env:
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-3-pro-preview
FRONTEND_BACKEND_PORT=8001
FRONTEND_CORS_ORIGIN=http://localhost:5173Run
In two terminals:
# 1. Backend (FastAPI + SSE)
uv run python -m backend.app
# 2. Frontend (Vite)
cd frontend && npm run devOpen 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 toolsaudit_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:
Queries the SF instance metadata to identify relevant fields
Validates all referenced fields and picklist values exist
Builds IF/THEN/ELSE condition logic
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:
Verifies the entity exists in $metadata
Verifies the field exists on that entity
Checks the field type (string, date, picklist, number)
If picklist values are provided, verifies they exist
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
Scored across 52 tools
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.
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.
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.
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
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
isolved and ApplicantPro jobs, tenant discovery, and change detection as an MCP server.
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.2915MIT
- AlicenseNot gradedqualityAmaintenanceA metadata-driven MCP server that auto-generates 480+ tools across 160+ ServiceNow tables, with multi-instance support, natural language search, and local script development.336 npm55Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server for SAP Cloud ALM, providing 54 tools across 9 services to manage features, tasks, test cases, documents, projects, and more via natural language.33 npm6GPL 3.0
- AlicenseNot gradedqualityDmaintenanceA 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