Connect AI assistants to your HR platform via the Model Context Protocol. Search employees, explore org charts, and run workforce analytics — all through natural language.
Get StartedCapabilities
40+ tools and built-in skills that give AI assistants full read access to your Shapes.co HR data.
Search and list employees by name, email, or job title. Get detailed profiles with custom fields, managers, and work status.
Traverse reporting chains up and down. Find managers, direct reports, and full hierarchies with job titles at every level.
Aggregate employee data by any dimension. Get counts, percentages, and distributions — no raw data needed.
Access review cycles, participants, and reviewers. Track completion rates and get insights on review progress.
View bookings, balances, policies, and holidays. Get absence trends and insights across teams.
Access survey data, participation tracking, and attendance records. Analyze response rates and completion trends.
Setup
Add the Shapes MCP server to your AI assistant. No API keys needed — authentication happens through OAuth.
{
"mcpServers": {
"shapes": {
"url": "https://mcp.shapes.co/mcp"
}
}
}{
"mcpServers": {
"shapes": {
"url": "https://mcp.shapes.co/mcp"
}
}
}{
"mcpServers": {
"shapes": {
"url": "https://mcp.shapes.co/mcp"
}
}
}Examples
Just ask in natural language. The AI assistant picks the right tools automatically.
“Who are the engineers on Sarah’s team?”
Finds Sarah, traverses her reporting chain downward, and filters for employees with “Engineer” in their job title.
“Show me the gender breakdown of our company”
Discovers the Gender custom field, then runs an aggregation to return counts like Male: 45, Female: 38, Non-binary: 3.
“How much vacation does our Tel Aviv office have left?”
Aggregates remaining vacation balances filtered by the Tel Aviv office, giving a team-level summary.
“What’s the completion rate for our Q1 performance review?”
Returns completion percentages, pending reviewers, and progress breakdowns for the Q1 review cycle.
“Find our work-from-home policy in the knowledge base”
Searches the company knowledge base for “work from home” and returns matching policy documents.
“Who has birthdays in February?”
Queries the date_of_birth custom field across all employees and filters for February dates.
Security
Shapes MCP uses OAuth 2.0 with PKCE for secure authentication. When you first connect, your MCP client will open a browser window to log in with your Shapes.co account.
Reference
Every tool the MCP server exposes to your AI assistant.
| Tool | Description |
|---|---|
| Employees | |
| get_employees | Search and list employees with optional filters and aggregation |
| get_employee | Get a detailed profile for a specific employee by ID |
| get_current_user | Get the authenticated user’s own employee profile |
| get_employee_field_types | Discover available employee fields and their metadata |
| get_employee_field_values | Query employee field values by type context |
| get_entities | Look up Job, Office, or Team entities by ID or name |
| get_profile_picture | Get an employee’s profile picture URL |
| employee_insights | Aggregated workforce analytics — counts, percentages, distributions |
| get_reporting_chain | Full reporting chain for an employee (up, down, or both) |
| search_in_hierarchy | Search within a reporting chain by job title or name |
| Performance Reviews | |
| get_performance_review_cycles | List review cycles with status and date ranges |
| get_performance_review_participants | Get participants in a review cycle |
| get_performance_review_reviewers | Get reviewers assigned to participants |
| performance_review_cycle_insights | Analytics on review cycle completion and progress |
| performance_review_participation_insights | Participation analytics across review cycles |
| Time Away | |
| get_time_away_bookings | List time-off bookings with date ranges and statuses |
| get_time_away_reasons | Get available time-off reasons (vacation, sick, etc.) |
| get_time_away_balance | Check remaining time-off balances |
| get_time_away_holidays | List company holidays |
| time_away_insights | Aggregated time-off analytics and trends |
| Surveys | |
| get_surveys | List surveys with status and participation info |
| get_survey | Get detailed survey information |
| get_survey_participants | Get participants in a survey |
| survey_insights | Analytics on survey responses and completion |
| Attendance | |
| get_attendances | List attendance records with filters |
| get_attendance_submissions | Get attendance submission details |
| Knowledge Base | |
| list_knowledge_base_files | Browse company knowledge base files |
| search_knowledge_base | Search knowledge base content |