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

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

# Claude Integration Guide for HaloPSA MCP Tools

This guide provides detailed instructions for integrating the HaloPSA MCP Tools with Claude, either using Claude Desktop or the Claude API.

## Table of Contents

1. [Introduction](#introduction)
2. [Integration with Claude Desktop](#integration-with-claude-desktop)
3. [Integration with Claude API](#integration-with-claude-api)
4. [Available Tools](#available-tools)
5. [Example Usage](#example-usage)
6. [Troubleshooting](#troubleshooting)

## Introduction

The HaloPSA MCP Tools package provides a Model Context Protocol (MCP) server that allows Claude to interact with the HaloPSA API. This enables Claude to perform tasks such as creating tickets, retrieving ticket information, and managing users and assets within your HaloPSA instance.

## Integration with Claude Desktop

### Prerequisites

- [Claude Desktop](https://www.anthropic.com/claude) application installed
- Node.js v18 or higher
- HaloPSA instance with API access
- 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:

```env
# Required
HALO_API_URL=https://your-instance.halopsa.com/api
HALO_API_KEY=your_api_key_here

# Optional
HALO_API_VERSION=v3
MCP_SERVER_PORT=3000
TOOL_PREFIX=halo
```

3. Start the MCP server for Claude Desktop:

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

### Configuring Claude Desktop

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

You can now use HaloPSA tools in your Claude conversations!

## Integration with Claude API

To use the HaloPSA MCP Tools with the Claude API, you can include the MCP server configuration in your API requests:

```json
{
  "mcpServers": {
    "halopsa": {
      "command": "npx",
      "args": ["-y", "haloapi-mcp-tools"],
      "env": {
        "HALO_API_KEY": "your_api_key_here", 
        "HALO_API_URL": "https://your-instance.halopsa.com/api",
        "HALO_API_VERSION": "v3",
        "TOOL_PREFIX": "halo"
      }
    }
  }
}
```

Include this configuration in your Claude API requests to enable access to HaloPSA tools.

### Sample API Request

```javascript
const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_CLAUDE_API_KEY',
    'anthropic-version': '2023-06-01'
  },
  body: JSON.stringify({
    model: 'claude-3-opus-20240229',
    max_tokens: 1000,
    messages: [
      { role: 'user', content: 'Can you create a ticket in HaloPSA for a server outage?' }
    ],
    mcpServers: {
      halopsa: {
        command: 'npx',
        args: ['-y', 'haloapi-mcp-tools'],
        env: {
          HALO_API_KEY: 'your_api_key_here',
          HALO_API_URL: 'https://your-instance.halopsa.com/api'
        }
      }
    }
  })
});
```

## Available Tools

### Ticket Management

| Tool | Description |
|------|-------------|
| `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-ticket-comments` | Get comments for a ticket |
| `halo-add-comment` | Add a comment to a ticket |

### User Management

| Tool | Description |
|------|-------------|
| `halo-get-users` | Get a list of users with optional filtering |
| `halo-get-user` | Get detailed information about a specific user |
| `halo-create-user` | Create a new user |
| `halo-update-user` | Update an existing user |

### Asset Management

| Tool | Description |
|------|-------------|
| `halo-get-assets` | Get a list of assets with optional filtering |
| `halo-get-asset` | Get detailed information about a specific asset |
| `halo-create-asset` | Create a new asset |
| `halo-update-asset` | Update an existing asset |

## Example Usage

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

### Creating a Ticket

```
User: I need to create a ticket for a server outage in the finance department.

Claude: I can help you create a ticket in HaloPSA for the server outage. What details would you like to include?

User: The server finance-srv01 is down and affecting the entire finance department. We need urgent assistance.

Claude: I'll create a ticket for that issue right away.

[Claude uses the halo-create-ticket tool]

Claude: I've created a ticket for the server outage. Here are the details:

Ticket #12345
Subject: Finance Server Outage - finance-srv01
Status: Open
Priority: High
Assigned Team: IT Support

The ticket has been created and is now visible in your HaloPSA instance.
```

### Retrieving Tickets

```
User: Show me all the open tickets in HaloPSA.

Claude: Let me retrieve the open tickets for you.

[Claude uses the halo-get-tickets tool with status=open]

Claude: Here are the current open tickets in your HaloPSA system:

1. Ticket #12345: Finance Server Outage - finance-srv01 (High)
2. Ticket #12346: Email Service Intermittent (Medium)
3. Ticket #12347: New Software Installation Request (Low)

Would you like me to get more details about any of these tickets?
```

## Troubleshooting

### Common Issues

#### Server Won't Start

- Verify your `.env` file has the correct API URL and key
- Check that the port specified is not already in use
- Ensure you have the proper permissions to access the HaloPSA API

#### Claude Can't Connect to the Server

- Verify the server is running
- Check that the URL entered in Claude Desktop matches your server URL
- Ensure your firewall is not blocking the connection

#### Authentication Errors

- Verify your HaloPSA API key is valid and has not expired
- Check that your account has the necessary permissions in HaloPSA

### Debug Mode

To enable debug logging, set the `DEBUG` environment variable:

```env
DEBUG=true
```

This will provide more detailed logging to help troubleshoot issues.

### Getting Help

If you encounter issues not covered in this guide, please:

1. Check the project's GitHub issues
2. Consult the HaloPSA API documentation
3. Create a new issue on the GitHub repository with details about your problem

## Advanced Configuration

For advanced users, additional configuration options are available through environment variables or the config file:

```env
# Authentication
AUTH_TYPE=api-key      # 'api-key', 'oauth', or 'basic'
CLIENT_ID=             # For OAuth authentication
CLIENT_SECRET=         # For OAuth authentication
TOKEN_URL=             # For OAuth authentication

# API Options
HALO_API_TIMEOUT=30000      # Timeout in milliseconds
MAX_RETRY_ATTEMPTS=3        # Number of retry attempts for failed API calls

# Server Options
LOG_LEVEL=info              # 'error', 'warn', 'info', or 'debug'
MCP_VERSION=1.0.0           # MCP protocol version
```

## Security Considerations

- The MCP server should ideally be run locally, not exposed publicly
- Store your API credentials securely
- Consider using read-only API credentials if only reading data is required
- Review HaloPSA API access logs regularly for unauthorized usage