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.

Configuring Claude Desktop Application

To configure Claude to connect to the Nomad MCP service, follow these steps:

1. Set Up API Access

Claude needs to be configured with the base URL of your Nomad MCP service. This is typically:

http://your-server-address:8000

2. Create a Claude Tool Configuration

In the Claude desktop application, you can create a custom tool configuration that allows Claude to interact with the Nomad MCP API. Here's a sample configuration:

{
  "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"
            }
          ]
        },
        {
          "name": "manage_job",
          "description": "Manage a job (status, stop, restart)",
          "method": "POST",
          "url": "http://your-server-address:8000/api/claude/jobs",
          "body": {
            "job_id": "string",
            "action": "string",
            "namespace": "string",
            "purge": "boolean"
          }
        },
        {
          "name": "create_job",
          "description": "Create a new job",
          "method": "POST",
          "url": "http://your-server-address:8000/api/claude/create-job",
          "body": {
            "job_id": "string",
            "name": "string",
            "type": "string",
            "datacenters": "array",
            "namespace": "string",
            "docker_image": "string",
            "count": "integer",
            "cpu": "integer",
            "memory": "integer",
            "ports": "array",
            "env_vars": "object"
          }
        },
        {
          "name": "get_job_logs",
          "description": "Get logs for a job",
          "method": "GET",
          "url": "http://your-server-address:8000/api/claude/job-logs/{job_id}",
          "params": [
            {
              "name": "namespace",
              "type": "string",
              "description": "Nomad namespace",
              "required": false,
              "default": "development"
            }
          ]
        }
      ]
    }
  ]
}

3. Import the Tool Configuration

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

4. 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

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