# Claude Integration with Nomad MCP

This document explains how to configure Claude to connect to the Nomad MCP service and manage jobs.

## Overview

The Nomad MCP service provides a simplified REST API specifically designed for Claude to interact with Nomad jobs. This API allows Claude to:

1. List all jobs in a namespace
2. Get the status of a specific job
3. Start, stop, and restart jobs
4. Create new jobs with a simplified specification
5. Retrieve logs from jobs

## API Endpoints

The Claude-specific API is available at the `/api/claude` prefix. The following endpoints are available:

### List Jobs

```
GET /api/claude/list-jobs?namespace=development
```

Returns a list of all jobs in the specified namespace with their IDs, names, statuses, and types.

### Manage Jobs

```
POST /api/claude/jobs
```

Manages existing jobs with operations like status check, stop, and restart.

Request body:
```json
{
  "job_id": "example-job",
  "action": "status|stop|restart",
  "namespace": "development",
  "purge": false
}
```

### Create Jobs

```
POST /api/claude/create-job
```

Creates a new job with a simplified specification.

Request body:
```json
{
  "job_id": "example-job",
  "name": "Example Job",
  "type": "service",
  "datacenters": ["jm"],
  "namespace": "development",
  "docker_image": "nginx:latest",
  "count": 1,
  "cpu": 100,
  "memory": 128,
  "ports": [
    {
      "Label": "http",
      "Value": 0,
      "To": 80
    }
  ],
  "env_vars": {
    "ENV_VAR1": "value1",
    "ENV_VAR2": "value2"
  }
}
```

### Get Job Logs

```
GET /api/claude/job-logs/{job_id}?namespace=development
```

Retrieves logs from the latest allocation of the specified job.

## Claude Integration Options

There are three main ways to integrate Claude with the Nomad MCP service:

### Option 1: Using Claude Desktop/Web UI Tool Configuration

Use this approach for Claude Web or Desktop applications with the tool configuration feature.

#### 1. Set Up API Access

Configure the base URL of your Nomad MCP service:
```
http://your-server-address:8000
```

#### 2. Create a Claude Tool Configuration

Create a tool configuration file (see sample in `claude_nomad_tool.json`):

```json
{
  "tools": [
    {
      "name": "nomad_mcp",
      "description": "Manage Nomad jobs through the MCP service",
      "api_endpoints": [
        {
          "name": "list_jobs",
          "description": "List all jobs in a namespace",
          "method": "GET",
          "url": "http://your-server-address:8000/api/claude/list-jobs",
          "params": [
            {
              "name": "namespace",
              "type": "string",
              "description": "Nomad namespace",
              "required": false,
              "default": "development"
            }
          ]
        },
        // Other endpoints...
      ]
    }
  ]
}
```

#### 3. Import the Tool Configuration

1. Open the Claude web or desktop application
2. Go to Settings > Tools
3. Click "Import Tool Configuration"
4. Select the JSON file with the configuration
5. Click "Save"

### Option 2: Using Claude Code CLI with OpenAPI Tool

For Claude Code CLI integration with the OpenAPI tool approach:

#### 1. Install Claude Code CLI

```bash
npm install -g @anthropic-ai/claude-code
```

#### 2. Create an OpenAPI Specification File

Use the updated `claude_nomad_tool.json` file which follows the OpenAPI specification format:

```json
{
  "schema_version": "v1",
  "name": "nomad_mcp",
  "description": "Manage Nomad jobs through the MCP service",
  "authentication": {
    "type": "none"
  },
  "api": {
    "type": "openapi",
    "url": "",
    "endpoints": [
      {
        "path": "/api/claude/list-jobs",
        "method": "GET",
        "description": "List all jobs in a namespace",
        "parameters": [
          {
            "name": "namespace",
            "in": "query",
            "description": "Nomad namespace",
            "required": false,
            "schema": {
              "type": "string",
              "default": "development"
            }
          }
        ]
      },
      // Other endpoints...
    ]
  }
}
```

#### 3. Register the Tool with Claude Code

```bash
claude-code tools register --specification=/path/to/claude_nomad_tool.json --base-url=http://your-server-address:8000
```

### Option 3: Using Claude Code CLI with SSE (Server-Sent Events)

For a more interactive experience, you can use Claude Code's MCP (Model Context Protocol) with SSE transport:

#### 1. Install Claude Code CLI

```bash
npm install -g @anthropic-ai/claude-code
```

#### 2. Start Your Nomad MCP Service

Make sure your Nomad MCP service is running and accessible.

#### 3. Add the MCP Configuration to Claude Code

Use the `claude_code_mcp.json` configuration file with the Claude Code CLI:

```bash
claude-code mcp add nomad_mcp /path/to/claude_code_mcp.json
```

This configuration uses the SSE endpoint at `/api/claude/mcp/stream` to create a streaming connection between Claude Code and your service.

#### 4. Launch Claude Code with the MCP Provider

```bash
claude-code --mcp nomad_mcp
```

The SSE integration provides a more responsive experience with streaming updates and better error handling compared to the regular tool integration.

## Test the Connection

You can test the connection by asking Claude to list all jobs:

```
Please list all jobs in the development namespace using the Nomad MCP service.
```

Claude should use the configured tool to make an API request to the Nomad MCP service and return the list of jobs.

## Example Prompts for Claude

Here are some example prompts you can use with Claude to interact with the Nomad MCP service:

### List Jobs

```
Please list all jobs in the development namespace.
```

### Check Job Status

```
What is the status of the job "example-job"?
```

### Start a New Job

```
Please create a new job with the following specifications:
- Job ID: test-nginx
- Docker image: nginx:latest
- Memory: 256MB
- CPU: 200MHz
- Port mapping: HTTP port 80
```

### Stop a Job

```
Please stop the job "test-nginx" and purge it from Nomad.
```

### Get Job Logs

```
Show me the logs for the job "example-job".
```

## Troubleshooting

If Claude is unable to connect to the Nomad MCP service, check the following:

1. Ensure the Nomad MCP service is running and accessible from Claude's network
2. Verify the base URL in the tool configuration is correct
3. Check that the Nomad MCP service has proper connectivity to the Nomad server
4. Review the logs of the Nomad MCP service for any errors
5. Make sure CORS is enabled in your FastAPI application (already configured in this application)

## Security Considerations

The Claude API integration does not include authentication by default. If you need to secure the API:

1. Add an API key requirement to the FastAPI application
2. Include the API key in the Claude tool configuration
3. Consider using HTTPS for all communications between Claude and the Nomad MCP service