Nicolas Koehl
403fa50b4f
- Add Server-Sent Events (SSE) endpoint for Claude Code MCP integration - Create MCP configuration for Claude Code CLI - Update tool configuration to support modern OpenAPI format - Add documentation for Claude Code integration options - Create CLAUDE.md guide for AI coding agents 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
295 lines
7.1 KiB
Markdown
295 lines
7.1 KiB
Markdown
# 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 |