haloapi-mcp-tools/docs/claude-desktop-integration.md

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

# Claude Desktop Integration Guide

This guide will walk you through setting up the HaloPSA MCP Tools to work with Claude Desktop.

## Prerequisites

1. Claude Desktop application installed
2. Node.js v14 or higher installed
3. HaloPSA instance with API access
4. HaloPSA API key

## Installation

1. Install the HaloPSA MCP Tools globally:

```bash
npm install -g haloapi-mcp-tools
```

2. Create a `.env` file in a directory where you'll run the server, with the following content:

```env
HALO_API_URL=https://your-instance.halopsa.com/api
HALO_API_VERSION=v3
HALO_API_KEY=your_api_key_here
MCP_SERVER_PORT=3000
```

Replace the values with your actual HaloPSA instance details.

## Running the Server

Start the MCP server for Claude Desktop:

```bash
haloapi-mcp-server
```

You should see output similar to this:

```
[2025-03-24T12:34:56.789Z] [INFO]: Starting HaloPSA MCP Server for Claude Desktop...
[2025-03-24T12:34:56.890Z] [INFO]: Registering 15 MCP tools
[2025-03-24T12:34:56.901Z] [INFO]: All tools registered successfully
[2025-03-24T12:34:57.012Z] [INFO]: HaloPSA MCP Server running on port 3000

=====================================
  HaloPSA MCP Server is now running
=====================================

To connect Claude Desktop to this server:

1. Open Claude Desktop
2. Go to Settings > Extensions
3. Click "Add MCP Server"
4. Enter the following details:
   - URL: http://localhost:3000
   - Name: HaloPSA
5. Click "Save"

You can now use HaloPSA tools in your Claude conversations

Press Ctrl+C to stop the server
```

## Configuring Claude Desktop

1. Open Claude Desktop.
2. Click on your profile picture in the top right.
3. Select "Settings" from the dropdown menu.
4. Navigate to the "Extensions" tab.
5. Click the "Add MCP Server" button.
6. Enter the following details:
   - **URL**: `http://localhost:3000` (or your configured port)
   - **Name**: `HaloPSA` (or any name you prefer)
7. Click "Save".

## Testing the Integration

Once the server is running and configured in Claude Desktop, you can test the integration with a simple conversation:

1. Start a new chat with Claude.
2. Ask a question that would use the HaloPSA tools, for example:
   - "Show me a list of open tickets in HaloPSA"
   - "Create a new ticket for server downtime"
   - "Find all assets assigned to user John Smith"

## Available Tools

You can ask Claude to use any of the following tools:

- `halo-get-tickets`: Get a list of tickets with optional filtering
- `halo-get-ticket`: Get detailed information about a specific ticket
- `halo-create-ticket`: Create a new ticket
- `halo-update-ticket`: Update an existing ticket
- `halo-delete-ticket`: Delete a ticket
- `halo-get-users`: Get a list of users
- `halo-get-user`: Get detailed information about a specific user
- `halo-get-assets`: Get a list of assets
- `halo-get-asset`: Get detailed information about a specific asset

## Troubleshooting

### Server Won't Start

- Verify that your `.env` file is in the correct directory
- Ensure your API key is valid
- Check that the port is not already in use

### Claude Can't Connect to the Server

- Verify the server is running
- Check that the URL entered in Claude Desktop matches the server URL
- Ensure your firewall is not blocking the connection
- Try using `127.0.0.1` instead of `localhost`

### Tool Errors

If you encounter errors when using the tools, check:
- The HaloPSA API is accessible
- Your API key has the necessary permissions
- Any required parameters are provided

## Running as a Background Service

To run the server as a background service, you can use tools like:

### PM2 (Linux/macOS/Windows)

```bash
npm install -g pm2
pm2 start haloapi-mcp-server --name "halopsa-mcp"
```

### Windows Service

You can use [node-windows](https://github.com/coreybutler/node-windows) to run as a Windows service:

```bash
npm install -g node-windows
node-windows --install haloapi-mcp-server
```

## Security Considerations

- The MCP server is designed to be used locally on your machine
- If exposing the server to other machines, always use proper authentication
- Consider using HTTPS for additional security
- Never share your API key or include it in public code repositories

## Next Steps

- Explore the available tools and their capabilities
- Create custom prompts for common HaloPSA tasks
- Integrate into your support workflow