nomad_mcp/CLAUDE_API_INTEGRATION.md

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:

{
  "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:

{
  "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):

{
  "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

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:

{
  "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

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

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:

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

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