successfactors-mcp
This MCP server lets you explore and query SAP SuccessFactors HR data across configured tenants, mainly through OData v2 REST and EC Compound Employee SOAP APIs.
List tenants (
list_tenants): discover reachable SuccessFactors instances, theircompany_ids, environment (production/other), and loaded plugins; emptycompany_id= default from.env.Fetch OData metadata (
odata_metadata): pull full or entity-scoped$metadata(e.g.EmpJob) reduced to a compact field map, plus navigation properties, saved to JSON to avoid loading raw EDMX.Compare metadata (
compare_metadata): diff one entity or whole service metadata between two tenants to spot config drift (missing fields, changedsap:attributes like required/picklist/MaxLength).Run OData v2 queries (
odata_query): query entity sets with$select/filters/paging, auto-handle effective-dating,$orderby/snapshot paging, duplicate-key and truncation warnings; results saved to JSON with optional small inline preview.Query Compound Employee (SOAP) (
ce_query): extract EC employee payloads by person/user id or last-modified delta, with configurable segments, page/row caps, contingent workers; each page saved as XML (payloads are large).Safe-by-default handling: keeps heavy payloads on disk, returns counts/paths, supports per-request tenant override, and refuses tenants with unknown/errored production config.
Provides integration with SAP SuccessFactors, enabling API troubleshooting, payload extraction, and integration development through Employee Central SFAPI (Compound Employee SOAP) and OData v2 endpoints, including employee lookups, delta extracts, pagination, and tenant key management.
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., "@successfactors-mcp Pull a delta extract of employees since April 1st"
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.
SuccessFactors Toolkit
A self-hosted toolkit for SAP SuccessFactors API troubleshooting, payload extraction, and integration development, exposed as a REST API and as an MCP (Model Context Protocol) server.
API | Protocol | Endpoint prefix |
EC SFAPI — Compound Employee | SOAP 1.1 |
|
OData | REST (v2, v4) |
|
OData v4 covers the SuccessFactors APIs published as v4 services (for example Calibration and Continuous Feedback); Employee Central and Onboarding data stay on v2. See OData API.
This is an independent project, not affiliated with or endorsed by SAP SE. SAP and SuccessFactors are trademarks of SAP SE.
Start here: Docker MCP → credentials → ask → export
Data security: prefer local deployment. For sensitive SuccessFactors employee data and credentials, we recommend running the MCP server in local Docker and using a local AI agent, rather than an online AI platform or a third-party hosted MCP service. Keep credentials and exports on your machine; do not upload private keys or employee payloads to online platforms.
A local AI agent is not necessarily a local model. If it calls a cloud model, prompts, tool responses, previews, and file contents supplied to that model may leave your machine. If HR data must stay within your controlled environment, use a locally hosted model and local file-processing tools, and check the agent's outbound data handling. Local Docker alone does not guarantee this. The toolkit still connects to your configured SuccessFactors tenant to query data.
For functional consultants and business key users, start with the business user guide or its English/Chinese HTML edition. Ask IT to complete the one-time Docker Compose setup and provide approved connection files. Then:
Check Docker Desktop or your IT-managed Docker service is running, then open your local AI application.
Confirm with IT that the connection files are in
sf-toolkit/credentials/systems, one folder per SuccessFactors system.Confirm which SuccessFactors system to use and ask for the employee, date, and information you need.
Find results under
sf-toolkit/data/mcp. Ask a file-capable AI application for CSV or another supported format, or a copy in an authorized folder.
The guide includes example business questions, completion checks, troubleshooting, and expandable one-time settings for your administrator. Original OData results are JSON; Compound Employee results are XML. CSV conversion requires local file tools in the AI application.
Related MCP server: Archive MCP Server
Documentation
Page | Covers |
Fail-closed setup, install and run, cheat sheet, response format | |
Key pair generation, system files ( | |
Compound Employee single lookup, structured filter query, pagination, known footguns | |
| |
Tools for AI agents, payload handling, export formats, PII tokenization, plugins | |
Local dev setup, linting, tests, release process |
Data handling
Use synthetic examples and test fixtures. Credentials, certificates, tenant
exports, employee payloads, and generated results do not belong in Git —
.gitignore and scripts/check_repository.py are a basic guardrail, not a
complete secret or personal-data scanner. See SECURITY.md for
deployment guidance and how to report a vulnerability.
License
Apache License 2.0. Copyright 2026 Justin Gong. See NOTICE for third-party and migrated-code attribution.
Available Tools
5 toolsce_queryA
Query the EC Compound Employee (SOAP) API and save the payload to disk.
person_id_external / user_id are comma-separated and take precedence over every other filter when set. last_modified_on is an ISO datetime for a delta pull (SAP allows at most 3 months of look-back). With no filter at all this is a full extract, capped by max_pages.
CompoundEmployee SFQL allows only ONE condition on last_modified_on in the WHERE clause — a query with both a lower and an upper bound (last_modified_on>X and last_modified_on<=Y) fails with INVALID_SFQL: Only one condition is allowed. This tool only ever emits the lower bound; apply any upper bound to the returned rows client-side, not by adding a second last_modified_on condition.
last_modified_on's filtering also depends on an SFQL parameter, isNotFirstQuery, that this tool does not currently set: per tenant testing, a query without isNotFirstQuery ignores last_modified_on entirely and returns a full snapshot of the matching window, while isNotFirstQuery=true makes last_modified_on act as a real delta filter. Until this tool exposes that parameter, treat last_modified_on here as a full-window snapshot, not a guaranteed delta — don't rely on it alone to mean "only changed rows".
select_segments defaults to the widely supported COMMON_SEGMENTS. If SF answers INVALID_SFQL naming a segment, that module is not enabled on the tenant — pass a narrower list. Only documented segment names are accepted, and person_id_external / user_id values may contain only letters, digits, space and _ . @ : / + -.
Each queryMore page is written as its own XML file. The tool returns counts and paths only: one employee's payload is ~80 KB of HR data.
Inputs: user_id, max_rows, max_pages, company_id, +4 more. Returns: object
compare_metadataA
Compare the OData configuration of two instances and return the drift.
entity="EmpJob" compares one entity set; entity="" compares the whole service (v4: a service path, as in odata_metadata). The comparison runs here, not in the conversation: one instance's EmpJob metadata alone is ~40 KB, so diffing two of them in context is both expensive and easy to get wrong.
Returns in_sync plus, per entity, the fields missing on either side and the
fields whose attributes differ, each as [value_in_a, value_in_b]. The sap:
attributes are the configuration itself — required, visible, upsertable,
picklist, MaxLength — so a changed picklist or a field that never left the
dev instance shows up here.
Inputs: company_a (required), company_b (required), entity. Returns: object
list_tenantsA
List the SuccessFactors instances this server can reach.
Call this first: the company_id values it returns are what the other tools
take as their company_id argument. An empty company_id always means the
instance configured in the server's own .env, reported here as "default".
"plugins" reports each installed plugin and whether it loaded.
"production" is the tenant's declared environment; odata_query and
ce_query refuse a tenant where it is null or "config_error" is set.
Inputs: no named parameters. Returns: object
odata_metadataA
Fetch OData $metadata (EDMX) and reduce it to a compact field map.
entity="" pulls the whole service metadata (large — hundreds of entity types); entity="EmpJob" pulls just that entity set. The full {entity: {field: attributes}} map is written to a JSON file, and a small map is returned inline as well, so two instances can be compared without ever loading raw EDMX into the conversation. When entity is given, its navigation properties (name, target entity type, filterable) are listed too — entity-scoped $metadata doesn't carry them, so this resolves them from the full service $metadata instead (fetched once per company_id per process, then cached); a lookup failure is reported as a warning and never blocks the field output above. Use the navigation names to scope filters into other entities via $filter (see the server's "Scope with EmpJob first" guidance and odata_query's docstring) instead of pulling whole entity sets and joining locally.
On a v4 tenant, entity is a service path: its root for the whole service ("talent/cdp/Learning.svc/v1"), or root plus entity set for one (".../Learning.svc/v1/Items"); both read that service's $metadata.
Inputs: entity, company_id. Returns: object
odata_queryA
Run an OData query, following next links until exhausted or max_pages.
path is the entity set and may carry query options, e.g. "FOCompany" or
"EmpJob?$select=userId,jobCode" (v4 tenant: service root first,
"talent/cdp/Learning.svc/v1/Items") — those are parsed out of path and merged
into the request; pass options either way, but prefer params (params win
on conflicts). Always $select only the fields you need. Effective-dated
entities (EmpJob, Position, FO*, MDF) return ONLY today's time slice unless
you pass fromDate=1900-01-01 and toDate=9999-12-31 (or asOfDate) in params.
Scope with a population filter pushed through navigation in $filter
(e.g. personNav/employmentNav/jobInfoNav/company in (...)) rather than
pulling whole entity sets — see the server instructions.
When max_pages > 1 and no $orderby is given, one is added from the
entity's key properties (reported as orderby_added) so $skip paging
can't duplicate or skip rows; if keys are unknown or unsortable, or SF
rejects it, the query runs without and a warning says so — then pass
$orderby yourself. Same condition, without $top/$skip, also adds
paging=snapshot on v2 (reported as paging_added); if SF rejects it for
that entity, the retry drops it and warns. Rows are checked for
duplicate keys when every key field is in the records (duplicate_records
warning if found). A final page exactly $top-sized with no next link gets a truncation warning (some MDF entities stop early); resume with $skip and an explicit $orderby.
Records are written to a JSON file; the tool returns counts, the field names of the first record, and the path. preview accepts 0-20; values above zero return that many records inline only when their serialized UTF-8 size is at most 16 KiB. Otherwise, inspect the saved file locally.
Inputs: path (required), params, preview, max_pages, +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 5 tools
Each tool targets a distinct stage: tenant discovery (list_tenants), schema inspection (odata_metadata), drift comparison (compare_metadata), and two query surfaces split by protocol (odata_query for OData, ce_query for SOAP Compound Employee). The two query tools could momentarily be confused as 'the query tool,' but descriptions make the API split explicit. Boundaries are otherwise clear.
All names are snake_case and group sensibly by API prefix (odata_*, ce_*), with metadata-related tools sharing the _metadata suffix. However, verb-based names (list_tenants, compare_metadata) mix with noun-based names (odata_query, ce_query, odata_metadata), so the pattern is readable but not a single uniform convention.
Five tools is well-scoped for a read-only SuccessFactors integration server: one for discovery, two for metadata handling, and two for the distinct query protocols. Every tool earns its place and none feels redundant or trivial.
The surface covers the full read-only workflow: find tenants, inspect metadata, diff metadata across tenants, and query both OData and Compound Employee APIs. Gaps are minor (no direct entity-set listing shortcut or write operations), but since the server appears intentionally read-only, no critical agent dead-end exists.
Maintenance
Related MCP Connectors
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Find, document and execute authenticated API calls across 1000+ apps via one MCP server
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Manage Pipefork API projects, drafts, connections, secrets, and deployments through MCP.
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
- FlicenseNot gradedqualityDmaintenanceEnables querying enterprise records and retention policies from any MCP client over stdio, with read-only tools for searching records, fetching retention verdicts, identifying archival candidates, summarizing departments, forecasting retentions, and viewing audit history.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to query projects, fetch findings, trigger analysis, upload CycloneDX BOMs, and check async token status against an OWASP Dependency-Track instance via stdio.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to interact with the Crewmeister API over local stdio, covering operations for members, teams, time tracking, salary exports, and related platform resources.Apache 2.0