nomad_mcp/MCP_INTEGRATION.md

# MCP Integration Guide

Nomad MCP provides seamless integration with AI assistants through the Model Context Protocol (MCP), enabling AI agents to interact with your Nomad cluster directly.

## What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is a standardized way for AI agents to interact with external tools and services. It allows AI models to call specific functions and receive structured responses, which they can then incorporate into their reasoning and responses.

## Zero-Config MCP Integration

Nomad MCP uses FastAPI MCP to automatically expose all API endpoints as MCP tools with zero configuration. This means that all endpoints in the REST API are immediately available as MCP tools without any manual definition or configuration.

### Connection Endpoint

AI assistants can connect to the MCP endpoint at:

```
http://your-server:8000/mcp/sse
```

The SSE (Server-Sent Events) transport is used for communication between the AI agent and the MCP server.

### Available Tools

All the endpoints in the following routers are automatically exposed as MCP tools:

- **Jobs**: Managing Nomad jobs (start, stop, restart, etc.)
- **Logs**: Retrieving job and allocation logs
- **Configs**: Managing job configurations
- **Repositories**: Working with code repositories

Each endpoint is converted to an MCP tool with:
- Proper parameter validation
- Detailed descriptions
- Type information
- Example values

### Example MCP Interactions

Here are some examples of how an AI agent might use the MCP tools:

#### Listing Jobs

```json
{
  "type": "tool_call",
  "content": {
    "name": "list_jobs",
    "parameters": {
      "namespace": "development"
    }
  }
}
```

#### Getting Job Status

```json
{
  "type": "tool_call",
  "content": {
    "name": "get_job_status",
    "parameters": {
      "job_id": "my-service"
    }
  }
}
```

#### Starting a Job

```json
{
  "type": "tool_call",
  "content": {
    "name": "start_job",
    "parameters": {
      "job_id": "my-service",
      "namespace": "development"
    }
  }
}
```

## MCP Integration Options

Nomad MCP provides two integration approaches:

### 1. FastAPI MCP Integration (Zero-Config)

Automatically exposes all REST API endpoints as MCP tools via SSE:

```
http://your-server:8000/mcp/sse
```

### 2. Standalone MCP Server (Claude Desktop)

A dedicated MCP server optimized for Claude Desktop with enhanced capabilities.

## Setting Up Claude Desktop with Standalone MCP Server

### Prerequisites

1. **Install Dependencies**:
   ```bash
   uv venv
   uv pip install -r requirements.txt
   ```

2. **Set Environment Variables**:
   ```bash
   export NOMAD_ADDR="http://your-nomad-server:4646"
   export NOMAD_NAMESPACE="development"  # optional
   ```

### Local Setup

1. **Configure Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
   ```json
   {
     "mcpServers": {
       "nomad-mcp": {
         "command": "/path/to/nomad_mcp/run_mcp_server.sh",
         "env": {
           "NOMAD_ADDR": "http://your-nomad-server:4646"
         }
       }
     }
   }
   ```

2. **Restart Claude Desktop** to load the configuration

### Available MCP Tools

The standalone MCP server provides these tools:

- **`list_nomad_jobs`** - List all jobs in a namespace
- **`get_job_status`** - Get detailed job status and health
- **`stop_job`** - Stop jobs with optional purge
- **`restart_job`** - Restart jobs
- **`create_job`** - Create jobs from specifications
- **`submit_job_file`** ⭐ - Submit Nomad job files (JSON/HCL)
- **`get_job_logs`** - Retrieve stdout/stderr logs
- **`get_allocation_status`** ⭐ - Detailed allocation monitoring
- **`get_job_evaluations`** ⭐ - Placement failure analysis  
- **`force_evaluate_job`** ⭐ - Retry failed placements

### Example Workflow

1. **Submit a job file**:
   ```
   Please submit this job file: [paste JSON job spec]
   ```

2. **Monitor deployment**:
   ```
   Check the status and allocations for my-service
   ```

3. **Debug issues**:
   ```
   Get evaluations for my-service to see why it failed
   ```

4. **Force retry**:
   ```
   Force evaluate my-service to retry placement
   ```

### Claude Code Integration

Claude Code can directly connect to the FastAPI MCP endpoint:

```bash
claude-code --mcp-url http://your-server:8000/mcp/sse
```

### Claude API Integration

For integration with the Claude API, you can use the MCP toolchain configuration provided in the `claude_nomad_tool.json` file.

See the [Claude API Integration Documentation](CLAUDE_API_INTEGRATION.md) for more detailed instructions.

## Network Deployment

### Running MCP Server on Nomad Cluster

You can deploy the MCP server itself on your Nomad cluster for centralized access.

#### Option 1: FastAPI MCP Server (HTTP/SSE)

Deploy the full FastAPI application with MCP endpoint:

```bash
# Start the FastAPI server with MCP endpoint
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

**Access via**: `http://your-nomad-server:8000/mcp/sse`

#### Option 2: Standalone MCP Server (TCP/Network)

For network access to the standalone MCP server, you'll need to modify it to use TCP transport instead of stdio.

**Current limitation**: The standalone MCP server (`mcp_server.py`) uses stdio transport, which is designed for local process communication.

**Network solution**: Create a TCP-based version or use the FastAPI MCP endpoint instead.

### Claude Desktop Network Configuration

To connect Claude Desktop to a network MCP server:

#### For FastAPI MCP (Recommended)

Create a wrapper script that uses the HTTP/SSE endpoint:

```json
{
  "mcpServers": {
    "nomad-mcp-network": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-everything",
        "--url", "http://your-nomad-server:8000/mcp/sse"
      ]
    }
  }
}
```

#### For Custom Network MCP Server

If you need a network-accessible standalone MCP server, you would need to:

1. **Modify the transport** in `mcp_server.py` from stdio to TCP
2. **Add network security** (authentication, TLS)
3. **Configure Claude Desktop** to connect via TCP

**Example network MCP server** (requires modification):
```python
# In mcp_server.py - replace stdio with TCP transport
import mcp.server.tcp

async def main():
    async with mcp.server.tcp.tcp_server("0.0.0.0", 8001) as server:
        await server.run(...)
```

**Claude Desktop config for network TCP**:
```json
{
  "mcpServers": {
    "nomad-mcp-tcp": {
      "command": "mcp-client",
      "args": ["tcp://your-nomad-server:8001"]
    }
  }
}
```

### Security Considerations for Network Deployment

When deploying MCP servers on the network:

1. **Use HTTPS/TLS** for HTTP-based MCP servers
2. **Implement authentication** (API keys, OAuth, etc.)
3. **Network isolation** (VPN, private networks)
4. **Firewall rules** to restrict access
5. **Rate limiting** to prevent abuse
6. **Audit logging** for all MCP operations

### Recommended Network Architecture

```
Claude Desktop → HTTPS/WSS → Load Balancer → FastAPI MCP Server → Nomad API
                  (secure)     (optional)      (on cluster)     (internal)
```

## Debugging MCP Connections

If you're having issues with MCP connections:

1. Check the server logs for connection attempts and errors
2. Verify that the `BASE_URL` environment variable is correctly set
3. Ensure the AI agent has network access to the MCP endpoint
4. Check that the correct MCP endpoint URL is being used
5. Verify the AI agent supports the SSE transport for MCP

## Custom Tool Configurations

While the zero-config approach automatically exposes all endpoints, you can customize the MCP tools by modifying the FastAPI MCP initialization in `app/main.py`:

```python
mcp = FastApiMCP(
    app,
    base_url=base_url,
    name="Nomad MCP Tools",
    description="Tools for managing Nomad jobs via MCP protocol",
    include_tags=["jobs", "logs", "configs", "repositories"],
    # Add custom configurations here
)
```

## Security Considerations

The MCP endpoint provides powerful capabilities for managing your Nomad cluster. Consider implementing:

1. Authentication for the MCP endpoint
2. Proper network isolation
3. Role-based access control
4. Audit logging for MCP interactions

By default, the MCP endpoint is accessible without authentication. In production environments, you should implement appropriate security measures.