# HCSS MCP MCP

> HCSS MCP connects your heavy construction software to any agent, giving you full command over job sites, equipment, and payroll data. Stop switching between portals. You can talk to your AI client and ask it to pull current equipment locations, list all active jobs, or check timecard statuses—all in one conversation.

## Overview
- **Category:** erp-operations
- **Price:** Free
- **Tags:** heavy-civil-construction, timecard-management, estimating, telematics, project-tracking, field-data

## Description

You shouldn't have to log into four different programs just to get a status update on one job. With this MCP, you connect your construction platform once through Vinkius and gain full control of everything from initial bids to finished payroll reports. Your agent acts like an embedded Project Engineer, letting you ask complex questions in plain English. Need to know if the excavator is where it's supposed to be? You can get its GPS coordinates instantly. Want to compare a job’s current labor hours against the original bid estimate? Just ask. It pulls both sets of data and compares them for you. This means faster decisions, because you’re getting real-time insights on everything from equipment usage trends to active project budgets.

## Tools

### get_bid_items
Retrieves the specific items that make up a given project estimate.

### get_equipment_location
Gets the current GPS coordinates for any piece of tracked equipment.

### get_equipment_meters
Provides the latest odometer or running hours for a machine.

### list_business_units
Lists all defined operating business units in the HCSS system.

### list_cost_codes
Shows every cost code used for tracking expenses and labor hours.

### list_employees
Lists all employee records synced within the HCSS platform.

### list_equipment
Lists every tracked piece of equipment currently in your fleet.

### list_estimates
Retrieves a list of all active bidding estimates from the system.

### list_jobs
Lists every construction job or project currently tracked in HCSS.

### list_precon_projects
Shows all projects that are in the pre-construction phase.

### list_timecards
Retrieves specific timecard records for tracking labor hours on a job site.

## Prompt Examples

**Prompt:** 
```
List all active construction jobs.
```

**Response:** 
```
I've retrieved your jobs. You have 5 active projects, including 'Highway 101 Expansion' (ID: 5501), 'Downtown Bridge Repair' (ID: 5505), and 'Industrial Park Phase 2'. Which one would you like to see timecard summaries for?
```

**Prompt:** 
```
Show the current location of Excavator ID EX-992.
```

**Response:** 
```
Accessing telematics... Excavator EX-992 is currently located at (29.7604, -95.3698), which is near the 'Highway 101' job site. The engine was last reported running 2 hours ago. Should I check the fuel level or meter readings?
```

**Prompt:** 
```
What are the bid items for estimate ID 2024-001?
```

**Response:** 
```
Retrieving HeavyBid data... Estimate 2024-001 includes 12 bid items, such as 'Site Clearing', 'Foundation Piling', and 'Asphalt Paving'. Would you like to see the assigned quantities and unit prices for these items?
```

## Capabilities

### Track site progress
List all active construction jobs or review pre-construction projects to see what's next.

### Monitor heavy equipment
Get the current GPS location and latest meter readings for any tracked piece of machinery.

### Review payroll data
Retrieve timecard records for specific jobs or list all employees defined in your system.

### Analyze project budgets
Access bid items and estimates to verify project costs against original scope.

### View business structure
List all cost codes or business units used across the entire construction system.

## Use Cases

### A Project Manager needs to verify job costs.
The PM asks the agent: 'What are the total labor hours recorded for Job 5501 this month?' The agent uses `list_timecards` and pulls all relevant data, then compares it against the project’s cost codes using `list_cost_codes`, giving an immediate variance report.

### A Fleet Manager needs to schedule maintenance.
The FM asks: 'Which pieces of equipment need service this week?' The agent calls `list_equipment` and then checks the meter readings using `get_equipment_meters` for every unit, providing a prioritized list of machines needing attention.

### An Estimator needs to check bid scope.
The Estimator asks: 'Show me the detailed breakdown for estimate 2024-001.' The agent uses `list_estimates` and then calls `get_bid_items`, showing exactly which services and materials were included in the original quote.

## Benefits

- Stop manually compiling payroll. You can instantly pull timecard data for a specific job or list all employees just by asking your agent.
- Never guess equipment status again. Get real-time GPS coordinates using `get_equipment_location` so you know exactly where every machine is, from the office to the site.
- Keep project spending accurate. Before bidding, use `list_estimates` and `get_bid_items` to cross-reference scope items with current costs, preventing budget overruns.
- Cut down on manual reporting time. Instead of pulling separate sheets for labor hours, you can ask the agent to consolidate all necessary data from `list_jobs` and `list_timecards` into one summary.
- Gain immediate visibility across your entire operation. Check equipment utilization trends or list active pre-con projects using simple commands, saving deep dashboard dives.

## How It Works

The bottom line is that your agent handles all the API calls and data merging behind the scenes; you just talk to it.

1. First, subscribe to this MCP on Vinkius and enter your HCSS Client ID, Client Secret, and API Key.
2. Next, connect it to your preferred AI client (like Cursor or Claude).
3. Then, you can start asking natural language questions—for example, 'What is the current location of the crane at Job 5501?'—and get a direct answer.

## Frequently Asked Questions

**How do I obtain my HCSS API credentials?**
You must request API access through the **HCSS Developer Portal** (developer.hcssapps.com). Once approved, you will receive your Client ID, Client Secret, and Ocp-Apim-Subscription-Key.

**Can I see the real-time location of my equipment?**
Yes! Use the `get_equipment_location` tool with the unique equipment ID. It will return the latest GPS coordinates recorded by the Telematics system.

**Does this integration cover both HeavyJob and HeavyBid?**
Yes, this MCP server includes tools for both modules, allowing you to access timecard data from HeavyJob and estimate/bid data from HeavyBid in a single interface.

**Is the integration secure for construction data?**
Absolutely. The integration uses industry-standard OAuth 2.0 Client Credentials flow and HTTPS. Your credentials are encrypted and stored securely within the Vinkius Cloud infrastructure.

**When I run `list_jobs`, how do I check labor hours for a specific project using `list_timecards`?**
The MCP links these two datasets by job ID. You pass the job identifier from the first list directly into the timecard tool. This lets your agent pull all associated work records for that single site immediately.

**After running `list_equipment`, how can I get the latest operational hours using `get_equipment_meters`?**
You need to provide the equipment ID gathered from the initial list. The tool pulls the most recent odometer and runtime data for that machine. This lets you track utilization trends without manually checking telematics screens.

**If I run `list_estimates`, how do I view all the components for a specific bid using `get_bid_items`?**
You must provide both the estimate ID and the required data point, like 'site clearing'. The tool then returns the full list of component items, including quantities and unit prices. This is essential for verifying budget scope.

**Does `list_employees` show which business units an individual worker belongs to?**
It lists every synced employee record across HCSS. While it doesn't map them directly, you can cross-reference the employee ID with results from `list_business_units` within your agent workflow to pinpoint their organizational structure.