xhr-mcp-server 0.1.0

X-HR MCP server using stdio transport

XHR MCP Server

Python MCP server for X-HR tools. This package is intended to run as a stdio MCP server so external clients can launch it as a local subprocess and communicate through standard input/output.

Transport

This server uses MCP stdio transport.

It is not intended to expose an HTTP MCP endpoint. MCP clients should start the package command directly and let the client manage the stdio session.

Install

From PyPI, once published:

pip install xhr-mcp-server

Or run it without a persistent install:

uvx xhr-mcp-server

For local development:

uv sync

This repository includes a starter tools.yaml with the default Workbench tools.

MCP Client Config

Example stdio configuration:

{
  "mcpServers": {
    "xhr": {
      "command": "uvx",
      "args": ["xhr-mcp-server"]
    }
  }
}

If the package is installed in the same environment as the MCP client:

{
  "mcpServers": {
    "xhr": {
      "command": "xhr-mcp-server",
      "args": []
    }
  }
}

Local Development

Run from the repository root:

uv run xhr-mcp-server

The installed package exposes the same command:

xhr-mcp-server

Environment

Common environment variables:

LOG_LEVEL=DEBUG
LOG_FORMAT=pretty
API_BASE_URL=https://api.dev.x-hr.ai
XHR_PAT=

API_BASE_URL defaults to https://api.x-hr.co when unset. For local testing, set it to the dev API URL shown above. XHR_PAT is optional. When present and the MCP request does not include an authorization header, script tools forward it as authorization: Bearer <XHR_PAT>. Script tools also use that authorization header to call /v1/im/me and fill xhr-employee-id and xhr-company-id when they are missing.

Tool Definition Example

Tools are loaded from tools.yaml. Each item can define an HTTP tool or a Python script tool:

tools:
  - name: workbench_list_tasks
    description: List Workbench tasks with optional filters.
    tool_type: python_script
    requires_auth: true
    active: true
    agent_category: workbench
    parameters:
      mine:
        type: boolean
        default: false
        description: Return tasks assigned to the current user.
    config:
      entrypoint: skills/workbench/get_tasks/scripts/get_tasks.py
      timeout_seconds: 30

Notes

Database migrations, Alembic, SQLAlchemy, and Postgres are intentionally not part of this package. Tools and script resources are bundled with the package by default.