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, their company_ids, environment (production/other), and loaded plugins; empty company_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, changed sap: 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.
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.
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: papertrail-mcp
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 |
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.
Apache License 2.0. Copyright 2026 Justin Gong. See NOTICE for third-party and migrated-code attribution.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | ||
| max_rows | No | ||
| max_pages | No | ||
| company_id | No | ||
| select_segments | No | ||
| last_modified_on | No | ||
| person_id_external | No | ||
| include_contingent_workers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full burden and does so thoroughly: it discloses the SFQL single-condition restriction, the isNotFirstQuery caveat that last_modified_on does NOT act as a true delta, the per-page XML file writing, and that only counts/paths are returned. These are exactly the non-obvious traits an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb/resource, then organized into behavior, caveats, and parameter guidance. It is long, but the length is justified by the genuine SFQL and delta-pull pitfalls; a little tightening of the isNotFirstQuery passage would help.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity extraction tool with an output schema present, the description covers purpose, filtering semantics, SFQL limitations, and output shape (counts and paths, ~80KB per employee) without needing to restate schema fields. Nothing essential to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate and largely does: it explains person_id_external/user_id precedence and allowed characters, last_modified_on semantics, select_segments defaulting to COMMON_SEGMENTS, and max_pages capping. However, max_rows, company_id, and include_contingent_workers receive no explanation anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (query the EC Compound Employee SOAP API) plus the side effect (save payload to disk). The SOAP/CompoundEmployee naming implicitly separates it from the OData-based sibling odata_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operating context: filter precedence for person_id_external/user_id, no-filter means full extract capped by max_pages, and the 3-month look-back limit. It stops short of explicitly naming when to prefer a sibling tool (e.g., odata_query), so it is strong context but not full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | No | ||
| company_a | Yes | ||
| company_b | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does fairly well: it discloses that the diff executes server-side, justifies it with the ~40 KB payload size, and explains the shape of the result ([value_in_a, value_in_b] pairs, missing vs. differing fields). It omits permissions/auth requirements and any rate or size limits on the comparison itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then parameter nuances, then the justification and return shape. The 40 KB rationale sentence is longer than strictly needed but earns its place by preempting the obvious 'why not just fetch both?' objection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still sketches the return contract and the meaning of the `sap:` attributes, which is useful domain framing rather than duplication. For a three-parameter diff tool with no annotations, this is close to complete; only the company identifier semantics are thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and it only partially does. `entity` is well specified ('EmpJob' vs. empty string / v4 service path), but `company_a` and `company_b` are left to inference from the phrase 'two instances' with no statement of expected format or how instance identifiers are obtained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Compare the OData configuration of two instances and return the drift' — and immediately names the output concept (drift, in_sync). It also differentiates from siblings by noting the comparison runs here rather than in the conversation and by referencing odata_metadata for the service-path semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the scoping choices for the `entity` parameter (single entity set vs. whole service) and gives a clear rationale for using the tool instead of diffing metadata manually in context. It does not explicitly route against the other siblings (odata_query, list_tenants), so it stops short of a full when/when-not map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well by explaining the default-instance convention, the meaning of the 'plugins' and 'production' fields, and downstream refusal behavior. It could mention failure/authentication behavior, but for a zero-parameter listing tool the disclosed behavior is substantially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence adds meaningful guidance. It avoids restating the tool name or schema and uses short paragraphs to separate purpose, usage, and field semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an existing output schema, and sibling tools that depend on this tool's return value, the description fully covers what an agent needs: why to call it first, how company_id maps to other tools, and the meaning of returned fields that affect downstream behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and schema coverage is 100%, so parameter semantics are essentially moot. The description adds useful semantic context for the returned company_id field, especially the empty-company_id-means-default convention, which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List the SuccessFactors instances this server can reach.' This clearly distinguishes list_tenants from the sibling query/metadata tools, since its purpose is to enumerate reachable tenants rather than run queries against them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Call this first' and explains why: the returned company_id values are required by the other tools. It also names odata_query and ce_query and states that they refuse tenants with null production or config_error, giving concrete when-to-use and prerequisite context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | No | ||
| company_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that entity="" output is large (hundreds of entity types), that the full map is written to a JSON file with a small map returned inline, that navigation resolution is fetched once per company_id per process then cached, and that a lookup failure surfaces as a warning without blocking field output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior is front-loaded in the first sentence, and the remaining paragraphs are organized by concern (scope, caching, failure handling, v4 paths). It is longer than strictly needed — several parentheticals could be trimmed — but no sentence is pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter metadata tool with an output schema already present, the description covers the non-obvious behaviors an agent needs: output size, file-vs-inline return, caching key, non-blocking warnings, and v4 path semantics. Nothing material is left for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate: it fully explains entity's two modes and the v4 service-path form ('talent/cdp/Learning.svc/v1' or root plus entity set). company_id is only implied through the caching note ('once per company_id per process') and is never defined, leaving one parameter under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch OData $metadata (EDMX) and reduce it to a compact field map') and clearly delimits scope via the entity parameter. An agent can distinguish this metadata-inspection tool from compare_metadata and odata_query without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete context: entity="" for the whole service, entity="EmpJob" for one set, and explicitly routes the agent to use navigation names to scope $filter into other entities rather than pulling whole sets. It points at odata_query and the server's 'Scope with EmpJob first' guidance, though it never states an explicit when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| params | No | ||
| preview | No | Inline records; maximum 20. | |
| max_pages | No | ||
| company_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly, disclosing paging behavior, automatic $orderby/paging=snapshot insertion and retry logic, duplicate-key checks, truncation warnings, effective-date time-slice defaults, and output-to-file/preview-size constraints. It leaves little behavioral uncertainty for an agent invoking the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the purpose in the first sentence and then organized by parameter/behavior topics. It is long and dense, but nearly every sentence adds a specific operational rule an agent needs, so it avoids true bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity, absent annotations, sparse schema descriptions, and the existence of an output schema (so return values need not be fully explained), the description is mostly complete. It still omits any treatment of company_id and does not cover auth or rate limits, which are minor gaps for otherwise thorough coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, so the description must compensate, and it does for path, params, max_pages, and preview by explaining merging, precedence, paging, and the 16 KiB inline-preview limit. The company_id parameter is never mentioned, leaving one of five parameters semantically unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Run an OData query, following next links until exhausted or max_pages.' This distinguishes it from metadata-fetching siblings, but it never differentiates itself from the other query sibling (ce_query) or mentions when to prefer one query tool over the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides rich operational guidance: how to pass path options, preferring params over inline options, always using $select, scoping with navigation filters, and how paging defaults interact with $orderby. However, it never names an alternative tool or states when this tool should not be used instead of ce_query or odata_metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2odata_query3 fields changedInput schema / properties / preview / descriptionAdded value: +"Inline records; maximum 20."Input schema / properties / preview / maximumAdded value: +20Input schema / properties / preview / minimumAdded value: +0v0.1.0ce_querycompare_metadatalist_tenantsodata_metadataodata_queryScored 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.
Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Search NPPES providers and resolve NUCC specialty codes via MCP over STDIO or Streamable HTTP.
Remote MCP for 1,500+ APIs. Vault-managed credentials; OAuth or API key. Search, load, and execute.
