HCM MCP Server for Oracle Fusion Cloud (unofficial)
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/describeendpoint (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_recordandrun_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
pipxor Docker, configured via environment variables orconfig.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.
HCM MCP Server for Oracle Fusion Cloud (unofficial)
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).
Why this exists
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
Key design principles
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.
Architecture at a glance
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 flagsTools (16)
Group | 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.
Roadmap
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 |
Stack
Python · FastMCP · httpx · pydantic
Packaged as a Docker/OCI image (primary) built from a hatchling wheel.
Getting started
Install from PyPI
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.
Configure
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.
Run with Docker (primary)
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.
Local development
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 stdioDocumentation
docs/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.
Status & contributions
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.
License
Apache-2.0. See also NOTICE.
Not affiliated with or endorsed by Oracle. Oracle and Fusion are trademarks of Oracle Corporation.
Available Tools
6 toolsdescribe_resourceA
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.
Inputs: resource (required). Returns: object
get_capabilitiesA
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.
Inputs: refresh. Returns: object
get_recordA
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.
Inputs: key (required), resource (required), expand, fields. Returns: object
list_resourcesA
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.
Inputs: limit, module, search. Returns: object
query_resourceA
Query any Oracle Fusion HCM resource (the generic read workhorse).
q: ADF filter, e.g.PersonNumber = 100010orLastName LIKE 'Sm%'.fields: restrict returned attributes (strongly recommended to keep responses small). Usedescribe_resourceto 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.
Inputs: resource (required), q, limit, expand, +4 more. Returns: object
server_infoA
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.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored 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.
Maintenance
Related MCP Connectors
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.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA generic MCP server that dynamically converts OpenAPI-defined REST APIs into tools for LLMs like Claude. It supports multiple authentication methods and transport protocols, enabling seamless interaction with any OpenAPI-compliant API.18 npmMIT
- AlicenseAqualityDmaintenanceA generic MCP server that dynamically exposes any OpenAPI-documented REST API to LLMs by auto-discovering endpoints. It provides tools for exploring API capabilities and making authenticated requests directly through natural language interfaces.211 npmMIT
- AlicenseBqualityFmaintenanceA Model Context Protocol (MCP) server that enables AI assistants to query and understand PeopleSoft HCM databases. It provides semantic tools for HR, Payroll, Benefits, Performance, and PeopleTools metadata, allowing natural language questions to be answered with accurate SQL queries.4312MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI-assisted professional profile generation by connecting to verified employee work data (skills, career history, certifications, projects) from employer HCM systems.MIT