PlainStaff Model Context Protocol (MCP) Server

Secure, enterprise-grade AI assistant integration for PlainStaff time tracking, projects, absences, and workforce management.

Quick Start • Client Setup • Available Tools • Two-Phase Safety • Development

🌟 Overview

The PlainStaff MCP Server connects AI assistants—including Claude (Desktop & Code), ChatGPT, Cursor, Grok, and custom LLM agents—directly to your PlainStaff workspace.

Through standard Model Context Protocol (MCP) interfaces, LLMs can inspect working hours, manage project bookings, check vacation balances, evaluate shift plans, and generate reports—while strictly honoring company permissions and employee privacy.

Core Highlights

• 🛡️ Two-Phase Write Confirmation: Destructive and write operations run in dry_run preview mode by default. Assisting agents must receive explicit user approval and commit with a timed confirm_token.

• 🔒 Enterprise-Grade Security: Strict multi-tenant isolation, RBAC role checks (Employee, Manager, HR Admin), and OAuth 2.1 Bearer authentication.

• ⚡ Dual Transport Architecture:

  • Remote HTTP (POST /mcp): Stateless streamable JSON endpoint for cloud assistants (ChatGPT, Claude Connectors, Grok).

  • Local stdio Proxy (plainstaff-mcp-server): Zero-latency stdio-to-HTTPS proxy for desktop apps and IDEs.

• 📊 26+ Curated Tools: Covering time tracking, project financials, employee master data, shifts, and ArbZG compliance.

• 💡 Built-in Prompts & Resources: Out-of-the-box workflows for month-end reviews (monatsabschluss), project status audits (projektstatus), and live schema introspection.

Related MCP server: external-ai-ecosystem-gateway

🚀 Quick Start

Local stdio Proxy (Desktop & IDEs)

No local installation required—run directly via npx:

# Using an OAuth Bearer Token
export PLAINSTAFF_ACCESS_TOKEN="your_access_token"

# Or using your Personal API Key
export PLAINSTAFF_API_KEY="your_api_key"
export PLAINSTAFF_TENANT="your_tenant_id"

npx -y @plainstaff/mcp

Remote HTTP Endpoint (Cloud Assistants)

For cloud connectors (Claude custom connector, ChatGPT Apps SDK, Grok):

POST https://api.plainstaff.com/mcp
Authorization: Bearer <oauth2_access_token>
Content-Type: application/json

OAuth 2.1 discovery endpoints:

• Authorization Server: GET /.well-known/oauth-authorization-server

• Protected Resource: GET /.well-known/oauth-protected-resource

💻 Client Configuration

Claude Desktop

Add to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "plainstaff": {
      "command": "npx",
      "args": ["-y", "@plainstaff/mcp"],
      "env": {
        "PLAINSTAFF_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Cursor / VS Code

Add to .cursor/mcp.json in your project root or user settings:

{
  "mcpServers": {
    "plainstaff": {
      "command": "npx",
      "args": ["-y", "@plainstaff/mcp"],
      "env": {
        "PLAINSTAFF_API_KEY": "your_api_key",
        "PLAINSTAFF_TENANT": "your_tenant"
      }
    }
  }
}

🧰 Tool Catalog

Tools are grouped by domain with fine-grained RBAC permission checks:

⏱️ Time Tracking & Absences

📂 Projects & Billing

👥 Master Data & Organizations

📅 Workforce, Shifts & Compliance

🔍 Discovery & Reports

🛡️ Safety & Two-Phase Write Confirmation

To protect against inadvertent AI actions (hallucinations, accidental deletions, erroneous bookings), all write operations use Two-Phase Commit:

sequenceDiagram
    participant User
    participant Assistant as AI Assistant
    participant MCP as PlainStaff MCP Server
    participant API as PlainStaff API

    User->>Assistant: "Book 4 hours on Project Phoenix for today"
    Assistant->>MCP: plainstaff.project_book_time(..., dry_run=true)
    MCP-->>Assistant: { dry_run: true, preview: {...}, confirm_token: "tok_xyz", expires: 300s }
    Assistant-->>User: "I will book 4h on Project Phoenix (9:00 - 13:00). Please confirm."
    User->>Assistant: "Confirmed, go ahead"
    Assistant->>MCP: plainstaff.project_book_time(..., dry_run=false, confirm_token="tok_xyz")
    MCP->>API: Execute booking
    API-->>MCP: Success
    MCP-->>Assistant: { success: true, booking_id: "12345" }
    Assistant-->>User: "Done! Booking #12345 created."

1. Phase 1 (Preview): The tool is called with dry_run: true (default). The server calculates the result, checks permissions, and issues a short-lived cryptographic confirm_token (valid for 5 minutes).

2. Phase 2 (Commit): The assistant prompts the user for verification. Upon user consent, the tool is called again with dry_run: false and the matching confirm_token.

🛠️ Development

This package is written in modern TypeScript (ESM) and uses vitest for contract and integration testing.

# Clone the repository
git clone https://github.com/P1ainStaff/MCP.git
cd MCP

# Install dependencies
pnpm install

# Run unit & schema tests
pnpm test

# Typecheck and build dist/
pnpm run build

📄 License & Links

• License: MIT License — see LICENSE for details.

• PlainStaff Website: plainstaff.com

• Developer Documentation: plainstaff.com/developers/mcp

• Issues & Feedback: GitHub Issues