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
35+ 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.
List surveys, drill into participations, and aggregate response and completion rates across cohorts.
Read attendance records and submission details across teams and date ranges.
Search and browse the company knowledge base for policies, handbooks, and internal docs.
Search helpdesk collections and read full articles to answer employee questions in context.
Inspect time-management policies — working weeks, break rules, and overtime configuration.
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 | |
| list_employees | Search and list employees with filters, projection, and pagination |
| aggregate_employees | Aggregated workforce analytics — counts, percentages, distributions |
| get_current_employee | Get the authenticated user’s own employee profile |
| get_reporting_chain | Full reporting chain for an employee (up, down, or both) |
| list_entities | Look up Job, Office, or Team entities by ID or name |
| list_employee_field_types | Discover available employee fields and their metadata |
| list_employee_field_value_changes | Audit-trail of field-value changes on an employee profile |
| list_profile_pictures | Get employee profile picture URLs in bulk |
| Performance Reviews | |
| list_performance_review_cycles | List review cycles with status and date ranges |
| list_performance_review_participations | List participants in a review cycle (admin-scope) |
| list_performance_review_reviewers | List reviewers assigned to participants |
| list_my_performance_review_participations | Caller’s own participations across cycles |
| list_my_performance_review_reviews | Reviews the caller owes or has submitted |
| aggregate_performance_review_cycles | Analytics on cycle completion and progress |
| aggregate_performance_review_participations | Participation analytics across review cycles |
| Time Away | |
| list_time_away_bookings | Time-off bookings with date ranges and statuses |
| list_time_away_balances | Remaining time-off balances per employee/reason |
| list_time_away_reasons | Available time-off reasons (vacation, sick, etc.) |
| list_time_away_reason_policies | Reason policies — approval rules, units, day limits |
| list_time_away_policy_assignments | Which policy applies to which employee |
| list_time_away_days_grants | Days-grant entries underpinning each balance |
| list_time_away_holidays | Company holidays |
| aggregate_time_away_bookings | Aggregated time-off analytics and trends |
| Surveys | |
| list_surveys | List surveys with status and participation info |
| list_survey_participations | Participants in a survey (admin-scope) |
| list_my_survey_participations | Caller’s own survey participations |
| aggregate_survey_participations | Analytics on survey responses and completion |
| Attendance | |
| list_attendances | Attendance records with filters |
| list_attendance_submissions | Attendance submission details |
| Time Management | |
| list_time_management_policies | Working-week, break, and overtime policy configuration |
| Knowledge Base | |
| list_knowledge_base_files | Browse company knowledge base files |
| search_knowledge_base | Search knowledge base content |
| Helpdesk | |
| list_helpdesk_collections | Browse helpdesk article collections |
| search_helpdesk | Full-text search across helpdesk articles |
| read_helpdesk_article | Fetch the full body of a helpdesk article |