xHR Assistant MCP

xhr-assistant-mcp connects AI agents to xHR through the Model Context Protocol (MCP). It runs locally over stdio and includes the xHR skill catalog required by the agent, so users do not need to clone another repository.

Requirements

• Python 3.11 or newer
• An xHR access token for the environment you want to use
• An MCP client that supports stdio servers

Install

Installing with pipx keeps the MCP server isolated and makes the xhr-assistant command available globally:

python -m pip install --user pipx
python -m pipx ensurepath
pipx install xhr-assistant-mcp

Alternatively, install it in a virtual environment:

python -m venv .venv

Activate the environment:

# macOS or Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Then install the package:

python -m pip install xhr-assistant-mcp

Configure an MCP client

When installed with pipx, use this stdio configuration:

{
  "command": "xhr-assistant",
  "args": ["mcp"],
  "env": {
    "XHR_AUTHORIZATION": "Bearer <XHR_ACCESS_TOKEN>"
  }
}

If the MCP client cannot find commands from your PATH, use the absolute path returned by:

python -c "import shutil; print(shutil.which('xhr-assistant'))"

For a virtual-environment installation, point command at that environment's Python executable:

{
  "command": "/absolute/path/to/.venv/bin/python",
  "args": ["-m", "xhr_assistant_mcp", "mcp"],
  "env": {
    "XHR_AUTHORIZATION": "Bearer <XHR_ACCESS_TOKEN>"
  }
}

On Windows, the executable path is typically C:\\absolute\\path\\to\\.venv\\Scripts\\python.exe.

Restart or reconnect the MCP client after changing its configuration.

Environments

Production is the default environment:

Environment	API	Application
prod	https://api.x-hr.co	https://app.x-hr.co
sandbox	https://api.sandbox.x-hr.co	https://sandbox.x-hr.co

Select an environment before starting the MCP server:

xhr-assistant config set-env sandbox
xhr-assistant config show

Use an access token issued by the selected environment. Changing environments clears the cached account context, so reconnect the MCP client afterward.

To keep separate configurations for different MCP clients, set XHR_ASSISTANT_CONFIG_FILE in each server configuration:

{
  "command": "xhr-assistant",
  "args": ["mcp"],
  "env": {
    "XHR_ASSISTANT_CONFIG_FILE": "/absolute/path/to/xhr-sandbox.json",
    "XHR_AUTHORIZATION": "Bearer <SANDBOX_XHR_ACCESS_TOKEN>"
  }
}

Initialize that specific configuration once:

# macOS or Linux
XHR_ASSISTANT_CONFIG_FILE=/absolute/path/to/xhr-sandbox.json \
  xhr-assistant config set-env sandbox

# Windows PowerShell
$env:XHR_ASSISTANT_CONFIG_FILE = "C:\path\to\xhr-sandbox.json"
xhr-assistant config set-env sandbox

Environment variables

Variable	Purpose
XHR_AUTHORIZATION	Bearer access token used for xHR API requests. Recommended for backend and non-interactive agents.
XHR_ASSISTANT_CONFIG_FILE	Optional path to an isolated configuration file.
XHR_API_BASE_URL	Optional API URL used when creating a new configuration file.
XHR_APP_URL	Optional application URL used when creating a new configuration file.

Do not commit access tokens or place them in agent prompts. Supply secrets with your process environment or secret manager.

MCP tools

The agent workflow uses two restricted tools:

• read reads an approved xHR skill entrypoint. Agents start at skills/SKILL.md, select a domain, and read the matching leaf skill.
• exec runs only a script declared by the selected leaf skill. It is not a general-purpose shell.

The MCP server attaches the configured xHR context to API operations. The xHR API remains responsible for authentication and authorization.

MCP prompt

The server publishes the xhr_assistant_system_prompt prompt. MCP clients can load it as the system instructions for an xHR-capable agent.

Required integration step: inject this prompt into the agent's system instructions. Connecting the MCP server alone exposes the tools, but does not teach the agent the required skill-navigation and safe-execution workflow.

The prompt accepts a mode argument:

• full (default) includes the domain catalog.
• compact includes only the navigation, execution, authentication, and data safety contract.

Python agent hosts can retrieve the same instructions directly:

import os

from xhr_assistant_mcp import get_agent_instructions

system_prompt = get_agent_instructions(mode="full")

# Pass both values to your agent framework:
agent_config = {
    "instructions": system_prompt,
    "mcp_servers": {
        "xhr-assistant": {
            "command": "xhr-assistant",
            "args": ["mcp"],
            "env": {
                "XHR_AUTHORIZATION": os.environ["XHR_AUTHORIZATION"],
            },
        }
    },
}

agent_config is framework-neutral pseudoconfiguration: map instructions to your framework's system/developer prompt field and map the stdio server object to its MCP configuration. Keep the token in the backend process environment; do not copy it into system_prompt.

If the host supports MCP prompts natively, it may fetch xhr_assistant_system_prompt from the connected server instead. Inject the returned text before the agent handles xHR requests.

Verify the installation

xhr-assistant --help
xhr-assistant config show
xhr-assistant prompt --mode compact

The MCP server communicates over stdin/stdout, so start it through an MCP client rather than expecting an HTTP port or browser page.