Paylocity Connector MCP Node

An implementation of the Model Context Protocol (MCP) server designed to interface with various Paylocity API functionalities.

Supported Access Mechanisms

This server maps Paylocity endpoints to the custom URI scheme: - Custom URI Scheme: paylocity://

Exposed Resources

Data access points include: - paylocity://employees/{company_id} - Obtain a directory of all personnel for a specified entity. - paylocity://employees/{company_id}/{employee_id} - Retrieve granular profile information for an individual staff member. - paylocity://earnings/{company_id}/{employee_id} - Query accumulated earnings information specific to a team member. - paylocity://codes/{company_id}/{code_resource} - Access organizational code definitions related to a specific data type. - paylocity://localtaxes/{company_id}/{employee_id} - Fetch details regarding local tax withholdings for an employee. - paylocity://paystatement/{company_id}/{employee_id}/{year}/{check_date} - Secure retrieval of a specific pay statement record based on date.

Operational Functions (Tools)

The following functional interfaces are provided by this service: - fetch_employees - Retrieves the complete roster of personnel associated with a client organization. - Accepts optional company_id argument. - fetch_employee_details - Gathers detailed attributes for a singular staff member record. - Requires employee_id; accepts optional company_id. - fetch_employee_earnings - Acquires current and historical earning summaries for a specified worker. - Requires employee_id; accepts optional company_id. - fetch_company_codes - Fetches definitional codes relevant to a particular organizational resource type. - Requires code_resource; accepts optional company_id. - fetch_employee_local_taxes - Retrieves specific local tax parameterization data for an individual. - Requires employee_id; accepts optional company_id. - fetch_employee_paystatement_details - Loads the complete documentation for a pay cycle specified by date. - Requires employee_id, year, and check_date; accepts optional company_id.

Roadmap for Enhancements

Future deployments will incorporate:

• [ ] Advanced analytical reporting (e.g., attrition metrics, departmental headcount analysis, comparative rate assessments, etc.)

System Prerequisites (Configuration)

The service necessitates the definition of several environment variables for proper operation: - PAYLOCITY_CLIENT_ID - Identifier for the client application accessing the Paylocity platform. - PAYLOCITY_CLIENT_SECRET - Confidential key for API authentication. - PAYLOCITY_COMPANY_IDS - A delimited list of organizational units managed by this instance. - PAYLOCITY_ENVIRONMENT - Specifies the target API endpoint (e.g., production or testing). - MODEL_COST_PRIORITY - Optional setting to bias model selection toward lower operational expense. - MODEL_SPEED_PRIORITY - Optional setting to bias model selection toward faster response times. - MODEL_INTELLIGENCE_PRIORITY - Optional setting to bias model selection toward higher reasoning capability. - MODEL_HINTS - Optional guidance, supplied as a comma-separated list of desired model names.

Configuration data should reside in a .env file located at the project root.

MCP Initialization Sequence

Upon activation, the server replies to the MCP initialize message with its defined capabilities, operational directives, protocol revision number, and service metadata. The instructions field details the correct syntax for interacting with Paylocity resources and tools.

Security Advisory

⚠️ CRITICAL NOTICE: Authentication tokens are transiently stored by this application within the src/mcppaylocity/access_token/ subdirectory. These files contain sensitive access credentials and MUST NOT be included in any version control commits.

The repository's .gitignore file is configured to exclude these paths, but users must actively confirm that token files are omitted before pushing updates.

In the event of accidental inclusion: 1. Erase the files from the repository history: git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt 2. Finalize the change: git commit -m "Cleanup: Removed sensitive token cache from repository tracking" 3. It is highly advised to refresh your Paylocity API credentials promptly due to potential exposure.

Deployment Guide (Quickstart)

Installation Procedure

Desktop Client Setup (Claude)

Configuration paths for local client setups: On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration for Local/Non-Released Servers

```json "mcpServers": { "mcpPaylocity": { "command": "uv", "args": [ "--directory", "/path/to/mcpPaylocity", "run", "mcppaylocity" ] } } ```

Configuration for Officially Registered Servers

```json "mcpServers": { "mcpPaylocity": { "command": "uvx", "args": [ "mcppaylocity" ] } } ```

Development Workflow

Packaging and Distribution

To prepare the package artifacts for dissemination:

1. Synchronize project dependencies and update the lock file:

uv sync

1. Generate distribution artifacts (source and wheel):

uv build

These outputs will populate the dist/ folder.

1. Upload to the Python Package Index (PyPI):

uv publish

Note on publishing credentials: Tokens should be supplied via command flags (--token) or environment variables (UV_PUBLISH_TOKEN), or alternatively using username/password (--username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD).

Troubleshooting and Inspection

Debugging interactions over stdio (standard input/output) can be complex. For optimal diagnostic capabilities, utilize the MCP Inspector.

Launch the Inspector using npm (ensure Node.js/npm is installed):

npx @modelcontextprotocol/inspector uv --directory /path/to/mcpPaylocity run mcppaylocity

The Inspector will provide a local access URL in the console to begin the debugging session.

System Architecture Overview

The operational structure comprises three primary layers:

1. PaylocityClient - Manages all network communications with the external Paylocity API service.
2. TokenManager - Oversees the lifecycle of authentication credentials, including secure storage and refresh mechanisms.
3. FastMCP Server - The core layer that exposes the Paylocity data streams via the defined MCP resources and callable tools.

Legal Notice

Licensed under the MIT License.

Copyright (c) 2024 MJ Zou (@mjzou)

Permission is granted freely for use, replication, modification, amalgamation, publication, distribution, sublicensing, and/or sale of this Software, provided that the above copyright assertion and this permission notice are retained in all instances or substantial portions of the Software.

THE SOFTWARE IS SUPPLIED "AS IS," WITHOUT GUARANTEE OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MARKETABILITY, SUITABILITY FOR A SPECIFIC GOAL, AND NON-INFRINGEMENT. UNDER NO CIRCUMSTANCES SHALL THE ORIGINATORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY SUIT, DAMAGE, OR OTHER OBLIGATION ARISING FROM, UNDER CONTRACT, TORT, OR OTHERWISE, RELATED TO THE SOFTWARE OR ITS USAGE OR OTHER DEALINGS WITHIN THE SOFTWARE.

CONTEXTUAL BACKGROUND: Corporate administration utilities encompass the entire spectrum of applications, controls, analytical solutions, methodologies, and frameworks utilized by organizations to successfully navigate evolving market conditions, maintain a competitive stance, and elevate overall operational effectiveness.

== Conceptual Framework == Management utilities can be categorized based on departmental function and strategic focus areas such as preparatory tasks, workflow management, historical data recording, human resources management, strategic assessment, oversight functions, etc. A functional categorization typically addresses these core organizational dimensions:

• Utilities for initial data entry and integrity verification across all units.
• Utilities designed for monitoring and refinement of organizational processes.
• Utilities focused on aggregating data for comprehensive analysis and executive decision support. Today's enterprise software has seen radical transformation over the last ten years due to rapid technological progress, making the selection of optimal business solutions highly complex for any given operational context. This complexity stems from the continuous drive to minimize expenditures while simultaneously maximizing revenue, coupled with the imperative to deeply understand client requirements and deliver products meeting those specifications precisely. In this dynamic environment, leadership must adopt a proactive, strategic posture toward selecting business tools, rather than simply adopting the newest available technology. Frequently, management implements off-the-shelf tools without necessary customization, leading to organizational instability. Selection criteria for business management utilities must be rigorous, followed by careful tailoring to fit the specific organizational architecture.

== Global Usage Statistics (2013 Snapshot) == Data from a 2013 Bain & Company study illustrated global deployment patterns of business tools, reflecting how outcomes align with regional necessities, market conditions, and economic downturns. Key strategic and operational tools frequently cited included:

1. Strategic roadmap formulation
2. Client relationship lifecycle management (CRM)
3. Personnel satisfaction measurement
4. Comparative performance analysis (Benchmarking)
5. Integrated performance metrics (Balanced Scorecard)
6. Identification of core organizational capabilities
7. Strategic delegation of non-core functions (Outsourcing)
8. Organizational adaptation methodologies
9. Material and service flow optimization (SCM)
10. Foundational mission and vision definition
11. Customer base categorization
12. Comprehensive quality control frameworks

== Business Software Definition == Software applications, defined as collections of programs utilized by personnel to execute diverse corporate functions, are commonly termed business software. These applications serve to enhance productivity metrics, quantify performance outputs, and ensure precision in various corporate operations. The progression started with foundational Management Information Systems (MIS), evolved into Enterprise Resource Planning (ERP) suites, later integrated Customer Relationship Management (CRM), and has now largely transitioned into cloud-based business management platforms. While a tangible link exists between IT investment and organizational success, two factors are paramount for realizing tangible value: the efficacy of the deployment process and the precision in tool selection and subsequent customization.