Personio MCP

What this MCP does

Search and explore the AlphaPet Personio employee directory from your AI agent. Data is cached nightly from a Personio custom report — read-only, active internal employees only. Two tools:

Tool	What it does
`search_employees`	Find employees by `first_name`, `last_name`, `email`, `position`, `department`, `team`, `office`, `sub_company`, `seniority_level`, `status`, `employment_type`, or `cost_centers`. All optional, case-insensitive substring match, combined with AND.
`describe_filters`	Discover valid filter values (with counts) for every categorical field. Call this before filtering to avoid typos — e.g. office is `München`, not `Munich`.

Setup

The Personio MCP is hosted behind AlphaPet's MetaMCP gateway. Once connected, your AI agent (Cursor, Claude Code, Windsurf, …) can query the directory through it.

Request a MetaMCP access key

Open the AccessOwl Slack app and request access to MetaMCP. The same key unlocks all gateway-hosted MCPs — Looker, Perplexity, Team Marketplace and Personio — so you only need to request it once.

Add the server to your MCP client

Pick your client below and replace YOUR_API_TOKEN_FOR_METAMCP with the key from step 1.

Cursor global config: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json · Windsurf: ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json)

{
  "mcpServers": {
    "personio": {
      "url": "https://metamcp-server.swarm.ci.alpha.pet/metamcp/personio/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_FOR_METAMCP"
      }
    }
  }
}

Cursor and Windsurf support Streamable HTTP natively — no bridge client needed. After editing the file, fully restart the IDE.

Run this in your terminal to register the server globally (macOS / Linux / Windows):

claude mcp add --transport http --scope user personio https://metamcp-server.swarm.ci.alpha.pet/metamcp/personio/mcp --header "Authorization: Bearer YOUR_API_TOKEN_FOR_METAMCP"

--scope user makes the server available across all your Claude Code projects. --transport http tells Claude Code to speak Streamable HTTP directly — no mcp-remote bridge needed. On Windows, the command works in CMD and PowerShell; wrap the URL in quotes if your shell complains. Config lives in ~/.claude/ (Windows: %USERPROFILE%\.claude\).

Using Claude Code as the VS Code extension? That's the same CLI — run the command above in the integrated terminal, then Developer: Reload Window and type /mcp in the Claude chat panel to confirm the server is connected.

Cowork is the Claude-Desktop-App Research Preview. Its custom-connector UI only accepts a URL (and optional OAuth) — no custom headers — so we pass the MetaMCP key as a query parameter.

Claude Desktop App → Settings → Connectors → Add Custom Connector.

Name: Personio. Remote MCP Server URL (replace the token):

https://metamcp-server.swarm.ci.alpha.pet/metamcp/personio/mcp?api_key=YOUR_API_TOKEN_FOR_METAMCP

Leave the Advanced OAuth Client ID / Secret fields empty. Save.
The connector flips to Connected. Type /mcp in any Claude chat to verify.

The token sits in the URL, so it may land in browser history, proxy logs, and access logs — acceptable for internal tooling but rotate the key in the MetaMCP UI if it leaks. OAuth is available in MetaMCP but has known token-expiry issues, so query-param auth is the recommended default here.

Get started

Restart your client and try:

"Show me all colleagues in the Munich office"
"Which cost centers exist? Show me the five biggest."
"Who works in the Finance team at senior level?"