Shapes MCP Server

Provider-hosted MCP server for Shapes.co PeopleOS that gives AI assistants read access to employees, org charts, time off, performance reviews, surveys, and attendance.

Data & Enrichment by Shapes OAuth2 active

Connect (Remote Server) Docs

Overview

Shapes MCP is the official remote MCP server for Shapes.co, an AI-native People Operating System used by HR teams as an alternative to traditional HRIS platforms. The server connects AI assistants like Claude, Cursor, and Claude Code to a customer's Shapes workspace via OAuth 2.0 with PKCE, so users can query workforce data in natural language without writing custom API integrations. All access is read-only and scoped to the authenticated user's existing Shapes permissions.

The server exposes roughly 29 tools across six domains: employees (search, profiles, hierarchy traversal, field discovery, aggregated insights), performance reviews (cycles, participants, reviewers, completion analytics), time away (bookings, balances, holidays, reasons, trend insights), surveys (lists, participants, response analytics), attendance (records and submissions), and a company knowledge base (file browsing and content search). It also bundles built-in skills that guide agents through common workflows such as employee lookup, org navigation, and workforce analytics.

Because the server is hosted by Shapes there is nothing to install or self-host. Pointing an MCP-compatible client at https://mcp.shapes.co/mcp triggers a browser-based OAuth login on first use, and the agent inherits whatever permissions the user already has in Shapes.

Tools

Tool	Description
`get_employees`	Search and list employees with optional filters and aggregation.
`get_employee`	Retrieve 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, including custom fields.
`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, and distributions across any dimension.
`get_reporting_chain`	Full reporting chain for an employee, traversing up, down, or both.
`search_in_hierarchy`	Search within a reporting chain by job title or name.
`get_performance_review_cycles`	List performance 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 in a cycle.
`performance_review_cycle_insights`	Analytics on review cycle completion and progress.
`performance_review_participation_insights`	Participation analytics across review cycles.
`get_time_away_bookings`	List time-off bookings filtered by date range and status.
`get_time_away_reasons`	List available time-off reasons (vacation, sick, etc.).
`get_time_away_balance`	Check remaining time-off balances for employees.
`get_time_away_holidays`	List company holidays.
`time_away_insights`	Aggregated time-off analytics and trends.
`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.
`get_attendances`	List attendance records with filters.
`get_attendance_submissions`	Get attendance submission details.
`list_knowledge_base_files`	Browse company knowledge base files.
`search_knowledge_base`	Search knowledge base content.

Setup Guide

Prerequisites

A Shapes.co account with access to your organization's workspace
An MCP-capable client (Claude Desktop, Cursor, Claude Code, or similar)

Authentication

Shapes uses OAuth 2.0 with PKCE. No API keys are required. The first time you invoke a Shapes tool, your client opens a browser window for you to log in with your Shapes.co account. Tool access is gated by your existing Shapes permissions.

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "shapes": {
      "url": "https://mcp.shapes.co/mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "shapes": {
      "url": "https://mcp.shapes.co/mcp"
    }
  }
}

Claude Code

Add to .claude/settings.json (or use claude mcp add) with the same https://mcp.shapes.co/mcp URL. Restart the client and complete the OAuth flow on first tool call.

Use Cases

Pull headcount and workforce distributions (by team, office, job, gender, or any custom field) directly from Shapes without exporting CSVs.
Walk reporting hierarchies to answer questions like "who are the engineers under Sarah" or "show me everyone two levels below the CTO".
Monitor time-off balances, upcoming PTO, and company holiday coverage for a specific office or team.
Track performance review cycle progress and surface stalled participants or missing reviewers.
Look up internal policies and documents from the Shapes knowledge base while drafting answers in an AI assistant.

Example Prompts

"Who are the engineers on Sarah's team?"
"Show me the gender breakdown of our company."
"How much vacation does our Tel Aviv office have left?"
"What's the completion rate for our Q1 performance review cycle?"
"Find our work-from-home policy in the knowledge base."

Pros

Official, provider-hosted server with no install, hosting, or API key management required.
Broad coverage of the Shapes product surface: employees, hierarchy, time off, performance, surveys, attendance, and knowledge base.
OAuth 2.0 with PKCE means agents inherit the user's existing Shapes permissions, so access stays scoped.
Dedicated insights tools (employee_insights, time_away_insights, etc.) return aggregated analytics directly, avoiding raw-data exfiltration.

Limitations

Read-only: the server cannot create, update, or approve records such as time-off requests, reviews, or employee data.
Requires an active Shapes.co subscription, so it is not useful unless your HR team already runs on Shapes.
Compensation and DEI analysis depend on what fields exist in your Shapes workspace; there is no dedicated comp or pay-equity tool.

Alternatives

HiBob MCP for organizations using Bob as their HRIS.
Visier MCP Server for deeper people-analytics queries on top of a dedicated analytics platform.
Workday MCP integrations (for example via Improvado) for Workday HCM customers.