haloapi-mcp-tools/docs/TESTING_CLAUDE_INTEGRATION.md

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

# Testing Claude Desktop Integration

This guide provides step-by-step instructions for testing the integration between the HaloPSA MCP Server and Claude Desktop.

## Prerequisites

1. Node.js 18 or higher
2. npm or yarn
3. Claude Desktop application installed
4. HaloPSA API credentials (Client ID and Client Secret)

## Setup

1. Clone the repository:
```bash
git clone https://github.com/ssmanji89/haloapi-mcp-tools.git
cd haloapi-mcp-tools
```

2. Install dependencies:
```bash
npm install
```

3. Create a `.env` file in the project root with your HaloPSA credentials:
```
# Required HaloPSA API Configuration
HALO_API_URL=https://yourhalo.haloservicedesk.com/api
HALO_CLIENT_ID=your_client_id
HALO_CLIENT_SECRET=your_client_secret

# Server Configuration
TRANSPORT=http
PORT=3000
DEBUG=true
```

## Starting the MCP Server

1. Start the server in HTTP mode:
```bash
npm run desktop
```

2. You should see output similar to:
```
=====================================
  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
```

## Connecting Claude Desktop

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"

## Testing the Integration

### Test 1: Verify MCP Server Connection

1. After adding the MCP server in Claude Desktop, check the server logs
2. You should see logs indicating successful communication between Claude Desktop and the MCP server
3. You should NOT see any errors like "Method not supported: resources/list"

### Test 2: Test the HaloPSA Tools in Claude

1. Start a new conversation in Claude Desktop
2. Type a message like "Show me my tickets in HaloPSA"
3. Claude should offer to use the HaloPSA tools to fetch tickets
4. After you confirm, Claude should use the `get-tickets` tool to fetch tickets from HaloPSA

### Test 3: Test Creating a Ticket

1. In a conversation with Claude, ask to create a new ticket
2. For example: "Create a new ticket in HaloPSA with title 'Printer not working' and description 'The printer in the marketing department is not responding'"
3. Claude should use the `create-ticket` tool to create a new ticket in HaloPSA
4. Verify that the ticket was created in HaloPSA

## Troubleshooting

### Common Issues

#### Claude cannot connect to the MCP server

If Claude Desktop displays an error when trying to connect to the MCP server:
1. Check that the server is running
2. Verify the URL is correct (http://localhost:3000)
3. Check the server logs for any errors
4. Make sure your firewall is not blocking the connection

#### Claude successfully connects but can't use tools

If Claude connects to the server but cannot use the tools:
1. Check the server logs for any errors
2. Verify that your HaloPSA API credentials are correct
3. Check that you have the necessary permissions in HaloPSA

#### Method not supported errors

If you see "Method not supported" errors in the logs:
1. Make sure you're using the latest version of the haloapi-mcp-tools package
2. Verify that the standard MCP methods (`resources/list` and `prompts/list`) are properly implemented
3. Check that the server is declaring the proper capabilities when initializing

## Reporting Issues

If you encounter any issues that you cannot resolve, please report them on GitHub:
https://github.com/ssmanji89/haloapi-mcp-tools/issues

Please include:
- Detailed description of the issue
- Steps to reproduce
- Relevant logs
- Claude Desktop version
- Node.js version