This server acts as an MCP interface to Oracle Fusion Cloud HCM, enabling AI models to interact with its REST API via tools for discovery, read, workflows, change feeds, and gated writes.
Diagnostics & Configuration
server_info: Reports non-sensitive server configuration and enabled module flags to verify deployment health.
Resource Discovery & Introspection
list_resources: Searches a catalog of ~600 HCM REST resources, filterable by name, description, or module (e.g., core_hr, compensation, absence, payroll, recruiting, talent, learning).
describe_resource: Fetches a live schema for any resource — attributes, child collections, and available actions — from Oracle's /describe endpoint (cached).
get_capabilities: Detects which HCM modules are licensed and live on the specific Oracle pod, exposing only relevant tools and resources.
Generic Data Access
query_resource: Queries any HCM resource using ADF-style filters (q=), field selection, child collection expansion, ordering, and pagination.
get_record: Fetches a single record by primary key, with optional child collection expansion and field filtering.
Curated HR Workflows
Specialized tools for common HR tasks: find_worker, get_worker_profile, list_direct_reports, get_reporting_chain, lookup_org, get_current_compensation, list_absences.
Change Feed Monitoring
list_changes: Tracks HCM data updates via ATOM change feeds (gated by feature flag).
Gated Writes
mutate_record and run_action: Create/update records or trigger actions. Off by default, require explicit enablement, run dry-run first, are schema-validated, and audited.
Security & Safety
PII redaction (national IDs, salary, DOB) applied by default.
Writes are disabled by default and require explicit opt-in.
Supports Basic and OAuth2/JWT (OCI IAM / IDCS) authentication.
Deployable via pipx or Docker, configured via environment variables or config.toml.
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., "@HCM MCP Server for Oracle Fusion Cloud (unofficial) find employees hired last 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.
Not affiliated with or endorsed by Oracle. Oracle and Fusion are trademarks of Oracle Corporation.
An MCP server that lets AI models interact with Oracle Fusion Cloud HCM across its entire REST surface — workers, org structures, compensation, absence, payroll, recruiting, talent, learning and more — without hand-coding a tool per endpoint.
Built to be packaged once and reused across many Fusion HCM customers, regardless of which modules they license, how their flexfields are configured, or which Oracle release they run.
Status: Feature-complete. All 16 tools implemented — discovery, generic read, 7 curated HR workflows, ATOM change feeds, and gated writes — with an inescapable client-layer PII-redaction + audit floor. Built on ADF REST behavior verified against a live Fusion pod (DESIGN.md §13). 60 unit tests; Docker image and stdio server boot verified. After installing, run the smoke checklist in docs/TEST_CASES.md against your pod (every pod's licensing, roles, and flexfields differ).
Oracle Fusion HCM exposes ~600 REST resources built on Oracle's uniform ADF REST framework. A naive MCP server would create one tool per resource and blow up the model's context window — and would advertise tools that don't exist for customers who haven't licensed the matching module.
This server takes the opposite approach: a small set of generic, schema-aware tools that introspect any resource at runtime via Oracle's /describe endpoint, plus a handful of curated workflow tools for the most common HR tasks. It discovers each customer's licensed footprint automatically and only exposes what actually works on their pod.
Related MCP server: OpenAPI MCP Server
Generic over hardcoded — 6 generic tools + ~15 curated workflows cover all ~600 resources. No per-resource code.
Self-documenting — the model reads live schemas via describe_resource; no bundled schema files to maintain.
Capability-aware — startup probing detects which Oracle modules are licensed/provisioned and lights up only those tool groups (no Recruiting license → no Recruiting tools).
Safe by default — read-only out of the box; writes are off by default, gated, dry-run-first, and audited. PII (national IDs, salary, DOB) is redacted unless explicitly enabled.
Distributable — one configurable artifact, deployed single-tenant per customer pod. No customer specifics in code.
auth/ Basic + OAuth2/JWT (OCI IAM / IDCS)
core/ ADF REST client · resource catalog · /describe cache · q= filter builder
tools/ discovery · query · workflows · mutate · atom · bip
safety/ PII redaction · audit log · dry-run gates (writes off by default, schema-validated, fail closed)
config.py base URL · pinned REST version · scopes · feature & module flagsGroup | Tools |
Diagnostics |
|
Discovery |
|
Read |
|
Workflows |
|
Change feeds |
|
Writes |
|
The generic query_resource / get_record / describe_resource work against any of the ~600 HCM resources; the workflows are curated shortcuts for common HR questions.
Phase | Deliverable | Status |
1 | Generic read core + auth + discovery + safety floor | ✅ Built |
2 | Curated HR workflow tools | ✅ Built |
3 | Gated writes + custom actions + audit | ✅ Built |
4 | ATOM change feeds | ✅ Built |
5 | BI Publisher / HCM Extracts reporting | ◻ Future |
Python · FastMCP · httpx · pydantic
Packaged as a Docker/OCI image (primary) built from a hatchling wheel.
pipx install fusion-hcm-mcp-server # or: uvx fusion-hcm-mcp-serverpypi.org/project/fusion-hcm-mcp-server — published from this repo's CI via PyPI Trusted Publishing with attestations.
Want to use this from Claude Desktop? Follow the step-by-step guide: docs/INSTALL_CLAUDE_DESKTOP.md — covers both install modes (Python venv + OS credential store, or Docker), the Desktop config file, a test sequence, and the common traps.
cp config.example.toml config.toml # then edit; supply secrets via HCM_* env varsRequired: server.base_url (or HCM_BASE_URL). Credentials should come from environment
variables (HCM_USERNAME/HCM_PASSWORD, or HCM_CLIENT_ID/HCM_CLIENT_SECRET/HCM_TOKEN_URL),
never the committed file. See config.example.toml.
Prebuilt images are published to GitHub Container Registry on every release:
docker pull ghcr.io/mohantyajitesh/fusion-hcm-mcp-server:latest
docker run --rm -i \
-e HCM_BASE_URL="https://your-pod.fa.ocs.oraclecloud.com" \
-e HCM_USERNAME="INTEGRATION_USER" -e HCM_PASSWORD="..." \
-v "$PWD/config.toml:/app/config.toml:ro" \
ghcr.io/mohantyajitesh/fusion-hcm-mcp-server:latestOr build from source: docker build -t fusion-hcm-mcp-server .
For hosted HTTP transport, set transport.type = "http" (or HCM_TRANSPORT=http) and publish -p 8000:8000.
Requires Python 3.11+.
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
fusion-hcm-mcp-server # runs the MCP server over stdiodocs/INSTALL_CLAUDE_DESKTOP.md — install & run with Claude Desktop (venv or Docker), verification sequence, troubleshooting traps.
docs/TEST_CASES.md — tool matrix, automated coverage, the live-pod checklist, production-readiness assessment.
DESIGN.md — full technical design: auth, the ADF REST client, exact tool signatures, the q= filter grammar, the safety model, ADF ground truth, and licensing/module alignment.
This is an actively developing project — issues and PRs from people testing against their own pods are genuinely wanted. See CONTRIBUTING.md; for vulnerabilities, SECURITY.md. The design doc is the source of truth.
Apache-2.0. See also NOTICE.
Not affiliated with or endorsed by Oracle. Oracle and Fusion are trademarks of Oracle Corporation.
Return a resource's live schema: attributes, child collections, actions.
Hits Oracle's /describe endpoint (cached). This is the authoritative
source of field names to use in fields= and q= filters.
| Name | Required | Description | Default |
|---|---|---|---|
| resource | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool hits a cached endpoint, which is a behavioral trait. However, with no annotations provided, it does not explicitly mention read-only nature or safety, leaving some gap.
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?
Two concise sentences, front-loaded with purpose, no redundant information. Every sentence provides value.
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 tool has one parameter and an output schema, the description covers purpose, cache behavior, and hints at output structure. It could mention error handling or prerequisites, but is largely sufficient.
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 description adds little beyond the schema: the parameter 'resource' is mentioned only by name, without specifying valid formats or examples. With 0% schema description coverage, more detail is needed.
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 clearly states the tool retrieves a resource's live schema, including attributes, child collections, and actions. It distinguishes itself from sibling tools like get_record or list_resources by focusing on metadata rather than data.
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?
The description implies usage by noting it's the authoritative source for field names in queries, but does not explicitly contrast with alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which HCM modules are live on this pod.
For each module: its mode (on/off/auto) and discovered status
(enabled/disabled/provisioned/not_provisioned/no_access/unreachable).
Modules set to auto are probed against the pod. Pass refresh=True
to re-probe.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes that auto-mode modules are probed and refresh triggers re-probing, but it does not explicitly state that the operation is read-only, safe, or idempotent, nor does it mention any side effects or limitations.
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 three sentences in two concise paragraphs. It is front-loaded with the core purpose, and every sentence adds necessary detail without redundancy.
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 tool's simplicity (1 boolean parameter, no required params, output schema present), the description covers all necessary context: what it reports, module modes, statuses, and how to trigger refresh. It is complete for an agent to select and invoke correctly.
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 only parameter, 'refresh', is a boolean with default false. The description adds clear semantic value: 'Pass refresh=True to re-probe.' This fully explains its effect, going beyond the schema's type and default.
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 clearly states the tool reports which HCM modules are live on the pod, specifying per-module mode and status. This distinguishes it from sibling tools like describe_resource or list_resources, which are generic.
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?
The description explains the main purpose (reporting live modules) and the refresh parameter for re-probing. While it doesn't explicitly exclude alternatives, the context of HCM module status is clear enough for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single record by its key, optionally expanding child collections.
key is the resource's primary key (e.g. PersonId for workers).
Sensitive fields are redacted unless the deployment enables them.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| expand | No | ||
| fields | No | ||
| resource | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that sensitive fields are redacted unless enabled, which is a behavioral trait. However, it does not mention other aspects like permissions, rate limits, or side effects.
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 concise, with two short paragraphs. The first sentence clearly states the purpose, and the second adds context for the key parameter. It is front-loaded but could benefit from more structure.
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 4 parameters and an existing output schema, the description covers the key, expand, and redaction behavior. However, it omits explanations for the 'fields' and 'resource' parameters, leaving gaps. The redaction note adds useful context.
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%, requiring the description to compensate. Only the 'key' parameter is explained with an example. The 'expand' parameter is vaguely mentioned ('optionally expanding child collections'), and 'fields' and 'resource' are not explained at all.
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 clearly states 'Fetch a single record by its key, optionally expanding child collections.' It provides a specific verb and resource, and includes an example for the key parameter (e.g., PersonId for workers), distinguishing it from siblings like list_resources.
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?
The description implies usage for fetching a single record but does not explicitly state when to use this tool versus alternatives like query_resource or list_resources. No guidance on prerequisites or exclusion conditions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the catalog of common Oracle Fusion HCM REST resources.
Works offline from a bundled seed list. Filter by search (matches
name/title/description) and/or module (e.g. core_hr, compensation,
absence, payroll, recruiting, talent, learning, benefits, time_labor).
Use describe_resource to confirm a resource's live schema.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| module | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: 'Works offline from a bundled seed list' and 'Filter by search and/or module.' Since no annotations are provided, the description carries the full burden. It could mention the limit parameter and pagination behavior, but the offline nature is critical and well-stated.
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 concise: two sentences plus a succinct list of parameters. It is front-loaded with the primary action, and every sentence adds value—purpose, offline behavior, filtering, and next-step guidance. No wasted words.
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 tool's moderate complexity, an output schema exists, so return values need not be detailed. The description covers the core functionality, offline behavior, filtering, and suggests a follow-up tool. It lacks mention of the limit parameter and pagination, but these are minor omissions for a search-catalog tool.
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?
With 0% schema description coverage, the description adds meaning for two of three parameters: 'search (matches name/title/description)' and 'module (e.g. core_hr, ...).' The limit parameter is not explained, but it has a default and is optional. The examples for module are helpful.
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 clearly states the tool's purpose: 'Search the catalog of common Oracle Fusion HCM REST resources.' It distinguishes itself from siblings like describe_resource by noting that it works offline from a bundled seed list, making its scope and method explicit.
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?
The description explicitly guides when to use this tool versus an alternative: 'Use describe_resource to confirm a resource's live schema.' This tells the agent that list_resources is for initial discovery from an offline catalog, while describe_resource provides live schema details. It implies that list_resources should be used before describe_resource and not for actual data retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query any Oracle Fusion HCM resource (the generic read workhorse).
q: ADF filter, e.g. PersonNumber = 100010 or LastName LIKE 'Sm%'.
fields: restrict returned attributes (strongly recommended to keep
responses small). Use describe_resource to find valid names.
expand: child collections to inline.
Sensitive fields (national IDs, salary, DOB) are redacted unless the
deployment enables them. Filters are validated against the schema first.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| limit | No | ||
| expand | No | ||
| fields | No | ||
| offset | No | ||
| order_by | No | ||
| resource | Yes | ||
| total_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses sensitive field redaction (unless deployment enables them) and filter validation against schema first. This adds useful behavioral context beyond being a read operation.
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?
Concise bullet-style parameter list with front-loaded purpose. Two sentences of behavioral notes at the end. Avoids redundancy and reads efficiently, though could be slightly more structured.
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 8 parameters, no annotations, and output schema presence, the description covers core query mechanics and redaction but omits pagination behavior (limit/offset), sorting (order_by), and the total_results parameter. An agent would lack guidance on handling large result sets.
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%, but description explains 'q' with ADF filter examples, 'fields' with recommendation to use 'describe_resource', and 'expand' for child collections. It ignores 5 other parameters (limit, offset, order_by, resource, total_results), leaving gaps for pagination and ordering.
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 clearly states it queries Oracle Fusion HCM resources and brands itself as 'the generic read workhorse.' This distinguishes it from siblings like 'get_record' (single record) and 'describe_resource' (metadata), establishing a specific verb+resource+scope.
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 recommends using 'describe_resource' to find valid field names and warns about sensitive field redaction. However, it does not explicitly state when to prefer siblings like 'get_record' for single-record fetches, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report non-sensitive server configuration and enabled module flags.
Safe to call without a live pod connection — useful for verifying a deployment's configuration before exercising the HCM API.
| 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?
No annotations provided, so description carries full burden. It notes 'Safe' and 'non-sensitive', adding behavioral context beyond empty schema. However, lacks details on idempotency, rate limits, or response guarantees.
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?
Two efficient sentences with no redundancy. First sentence states purpose, second provides usage context. Perfectly front-loaded and concise.
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?
Despite having output schema (not shown), description covers purpose, safety, and deployment context adequately. With 0 param complexity, it is reasonably complete. Could mention return format but output schema covers that.
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?
No parameters, schema coverage 100% (empty). Description adds meaning by specifying what is reported (server configuration, module flags) and that it is non-sensitive, going beyond schema structure.
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 'Report non-sensitive server configuration and enabled module flags', a specific verb+resource pair. While it doesn't explicitly distinguish from siblings like 'describe_resource', the focus on server config vs. resources is implied.
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?
Description explicitly says 'Safe to call without a live pod connection — useful for verifying a deployment's configuration before exercising the HCM API', providing clear context for when to use. No explicit alternatives, but strong usage guidance.
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.0describe_resourceget_capabilitiesget_recordlist_resourcesquery_resourceserver_infoScored across 6 tools
Each tool targets a distinct responsibility: schema exploration (describe_resource), module status (get_capabilities), single record retrieval (get_record), resource catalog (list_resources), generic query (query_resource), and server configuration (server_info). No two tools overlap in purpose.
All tool names follow a consistent verb_noun pattern with snake_case: describe_resource, get_capabilities, get_record, list_resources, query_resource, server_info. The pattern is uniform and predictable.
With 6 tools, the set is concise yet covers the core needs for an HCM API exploration server: metadata discovery, querying, and configuration info. No tool is superfluous, and the count feels well-scoped for the domain.
The tool surface is complete for read and exploration tasks, providing schema discovery, resource catalog, and data retrieval. However, it lacks mutation operations (create/update/delete), which may be required for full HCM workflows, hence a minor gap.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
