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

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

Getting Job Status

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

Starting a Job

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

Setting Up Claude with MCP

Claude Code Integration

Claude Code can directly connect to the MCP endpoint at http://your-server:8000/mcp/sse. Use the --mcp-url flag when starting Claude Code:

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 for more detailed instructions.

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:

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.