haloapi-mcp-tools/docs/CLAUDE_INTEGRATION.md

Model Context Protocol (MCP) server for interacting with the HaloPSA API

# Claude Desktop Integration Guide

This guide explains how to integrate the HaloPSA MCP Server with Claude Desktop.

## Prerequisites

- [Claude Desktop](https://claude.ai/download) installed
- HaloPSA MCP Server installed and configured
- HaloPSA API credentials

## Configuration

1. Open Claude Desktop
2. Click on the Claude menu in the system tray or menu bar
3. Select "Settings..."
4. Click on "Developer" in the left-hand sidebar
5. Click "Edit Config" to open the configuration file

Edit the configuration file to include the HaloPSA MCP Server:

```json
{
  "mcpServers": {
    "halopsa": {
      "command": "node",
      "args": ["/absolute/path/to/halopsa-mcp-server/src/index.js"],
      "env": {
        "HALOPSA_API_URL": "https://your-instance.haloservicedesk.com/api",
        "HALOPSA_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Replace `/absolute/path/to/halopsa-mcp-server` with the actual path to your server installation.

## Verification

After saving the configuration and restarting Claude Desktop:

1. Start a new conversation
2. You should see a hammer icon (🔨) in the input field, indicating that MCP tools are available
3. Click on the hammer icon to see the available tools from the HaloPSA MCP Server

## Using the Tools

Here are some examples of how to use the HaloPSA tools in Claude:

### Viewing Tickets

Ask Claude about tickets:

> "Show me all open tickets with high priority"

Claude will use the `get-tickets` tool to retrieve and display this information.

### Creating a Ticket

Ask Claude to create a ticket:

> "Create a new ticket for a customer who can't access their email"

Claude will use the `create-ticket` tool, and may ask for additional information like the requester ID.

### Managing Users

Ask Claude about users:

> "Who are all the support agents in the system?"

Claude will use the `get-users` tool with appropriate filtering.

### Working with Assets

Ask Claude about assets:

> "Show me all active laptops in the system"

Claude will use the `get-assets` tool with appropriate filtering.

## Troubleshooting

### The MCP server doesn't appear in Claude

- Make sure the path in the configuration is correct and absolute
- Check that the server is properly installed with all dependencies
- Check that the HaloPSA API key is valid
- Look at Claude logs and server logs for errors

### Tools are not working correctly

- Check that the HaloPSA API URL is correct
- Verify that the API key has sufficient permissions
- Look at the server logs for detailed error information

## Logs

Claude logs can be found at:

- macOS: `~/Library/Logs/Claude/`
- Windows: `%APPDATA%\Claude\logs\`

Look for files starting with `mcp-` to see logs related to the MCP server.