wiki/monitor-mcp/Troubleshooting.md

← Back to Home

Troubleshooting

Common issues and solutions when using monitor-mcp.

Grafana Not Configured

Symptom: All Grafana tools return "Grafana not configured".

Cause: The grafana block is missing from ~/.monitor-mcp.json, or one of baseUrl/apiKey is absent. Both fields are required for the Grafana client to initialize.

Solution:

1. Add the grafana block to your config:

{
  "grafana": {
    "baseUrl": "https://grafana.example.com",
    "apiKey": "glsa_your_service_account_token"
  }
}

2. Or set sitesJsonPath pointing to a sites.json that contains a grafana block (used as fallback).

3. Verify the API key is a valid Grafana service account token with Viewer permissions or higher.

SSH Connection Failures

Symptom: SSH-based tools (monitor_health, monitor_disk, etc.) fail with timeout or permission errors.

Cause: SSH cannot reach the target or authentication fails.

Solutions:

Check	Command	Fix
Host reachable	ssh user@host -p port echo ok	Verify hostname/IP and port
Key auth works	ssh -i /path/to/key user@host echo ok	Ensure keyPath points to valid private key
BatchMode works	ssh -o BatchMode=yes user@host echo ok	Must not require password prompt; add key to authorized_keys
Correct port	Check config port field	Default is 22; update if non-standard

The SSH client uses these options:

• StrictHostKeyChecking=accept-new — auto-accepts new host keys
• BatchMode=yes — fails immediately if password is required
• Timeout: 30 seconds per command

sites.json Not Found

Symptom: monitor_sites returns "No sites.json configured".

Cause: Either sitesJsonPath is not set in the config, or the file at that path does not exist.

Solution:

1. Set sitesJsonPath in ~/.monitor-mcp.json:

{
  "sitesJsonPath": "/home/user/sites.json"
}

2. Ensure the file exists and is valid JSON with a sites array:

{
  "sites": []
}

3. The path is resolved relative to the working directory unless absolute. Use an absolute path to avoid ambiguity.

Connection Not Found

Symptom: Tool call fails with Connection "name" not found. Available: ...

Cause: The connection parameter refers to a name that does not exist in the connections map.

Solution:

• Use monitor_list_servers to see all available connection names.
• Omit the connection parameter to use the default.
• Add the missing connection to ~/.monitor-mcp.json.

Config File Not Found

Symptom: Server fails to start with No connections in ~/.monitor-mcp.json.

Cause: The config file does not exist or contains no connections.

Solution:

1. Create the config file:

cat > ~/.monitor-mcp.json << 'EOF'
{
  "connections": {
    "myserver": {
      "host": "server.example.com",
      "username": "deploy",
      "keyPath": "~/.ssh/id_ed25519"
    }
  }
}
EOF

2. Or set the MONITOR_MCP_CONFIG environment variable to point to an alternate location.

Grafana API Errors

Symptom: Grafana tools return Error 401 or Error 403.

Cause: The API key is invalid, expired, or lacks permissions.

Solution:

1. Generate a new service account token in Grafana: Administration > Service Accounts > Add token.
2. Ensure the service account has at least Viewer role.
3. Update grafana.apiKey in the config file.

Docker Tools Return "Docker not available"

Symptom: monitor_docker or monitor_docker_stats output "Docker not available".

Cause: Docker is not installed on the remote server, or the SSH user does not have permission to run docker commands.

Solution:

• Verify Docker is installed: docker --version
• Add the SSH user to the docker group: sudo usermod -aG docker username
• Or use a connection with a user that has Docker access.

Command Timeout

Symptom: Tools fail with a timeout error after 30 seconds.

Cause: The remote command is taking longer than the 30-second timeout (TIMEOUT = 30_000).

Solution:

• Check network latency to the server.
• For monitor_logs, reduce the lines parameter.
• For monitor_processes, reduce the count parameter.
• Verify the server is not under heavy load causing slow SSH responses.

---

Built on MokoStandards

---

Repo: monitor-mcp · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version