# MCP Clients

Rocannon works with any MCP client. All use the same command: `rocannon mcp serve --profile <path>`. Use an absolute path. Clients spawn the server from their own working directory, not yours.

Client | Config location
--- | ---
Claude Code | `.mcp.json` at project root, or `claude mcp add`
Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json`
mcphost | `~/.mcphost.yml` or `--config <path>`
IBM Bob | `.bob/mcp.json` or `~/.bob/mcp_settings.json`

## Claude Code

One-shot setup via the CLI:

    claude mcp add rocannon -- rocannon mcp serve --profile /absolute/path/to/profile.yml

Or add to `.mcp.json` at your project root:

    {
      "mcpServers": {
        "rocannon": {
          "command": "rocannon",
          "args": ["mcp", "serve", "--profile", "/absolute/path/to/profile.yml"],
          "env": {
            "ROCANNON_LOG_FORMAT": "json"
          }
        }
      }
    }

Verify the connection:

    claude mcp get rocannon

## Claude Desktop

    {
      "mcpServers": {
        "rocannon": {
          "command": "rocannon",
          "args": ["mcp", "serve", "--profile", "/absolute/path/to/profile.yml"]
        }
      }
    }

Restart Claude Desktop after editing the config.

## Cursor

    {
      "mcpServers": {
        "rocannon": {
          "command": "rocannon",
          "args": ["mcp", "serve", "--profile", "/absolute/path/to/profile.yml"]
        }
      }
    }

## mcphost

    servers:
      rocannon:
        command: rocannon
        args:
          - mcp
          - serve
          - --profile
          - /absolute/path/to/profile.yml

mcphost env field. mcphost ignores the `env` field in its config. To pass environment variables, use the `command: env` workaround:

    servers:
      rocannon:
        command: env
        args:
          - ROCANNON_TIMEOUT=120
          - rocannon
          - mcp
          - serve
          - --profile
          - /absolute/path/to/profile.yml

## IBM Bob

    {
      "mcpServers": {
        "rocannon": {
          "command": "rocannon",
          "args": ["mcp", "serve", "--profile", "/absolute/path/to/profile.yml"],
          "alwaysAllow": [
            "ansible_builtin_ping",
            "ansible_builtin_setup"
          ]
        }
      }
    }

The `alwaysAllow` field pre-approves specific tools so Bob doesn't prompt on every safe read-only call.

## HTTP transport

For long-lived sessions or multi-client scenarios, run Rocannon over HTTP instead of stdio:

    rocannon mcp serve --profile profile.yml --transport http

The server starts on port 8000 by default (configurable via FastMCP's standard env vars). HTTP transport enables the Ping middleware and is suitable for containerised deployments. A working `deploy/rocannon.service` systemd unit is included in the repo.

## Running as a service

    [Unit]
    Description=Rocannon MCP Server
    After=network.target

    [Service]
    ExecStart=rocannon mcp serve --profile /etc/rocannon/profile.yml --transport http
    Environment=ROCANNON_LOG_FORMAT=json
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target

See `deploy/rocannon.service` in the repo for the full unit file.

## Verifying the connection

Check tool count from the project root after wiring any client:

    rocannon mcp doctor --profile profile.yml

Or from the health endpoint when running in HTTP mode:

    curl http://localhost:8000/health

    {
      "status": "ok",
      "tools": 142,
      "hosts": 8,
      "groups": 3,
      "profiles": ["dev", "staging", "prod"],
      "active_profile": "dev"
    }

## MCP resources

Rocannon exposes several read-only resources alongside the tools:

Resource URI | Contents
--- | ---
`rocannon://inventory` | Hosts and groups for the active profile
`rocannon://module/{fqcn}` | Parsed schema for a registered module
`rocannon://collections` | Collections exposed and their module lists
`rocannon://profiles` | All loaded profiles and which is active
`rocannon://playbooks` | Saved playbooks (name, description, step count)
`rocannon://runs` | Recent tool call records (last 50)
`rocannon://runs/{request_id}` | Full record for a single call by ID