ollama_doctor

ollama_doctor is the no-LLM diagnostic. It probes Ollama, checks pulled vs loaded vs required models, surfaces the active profile, lists allowed roots and recent errors, and returns a single healthy: boolean your session-start logic can gate on.

This is the first call to run on every new session. It costs essentially nothing and tells you exactly what’s wrong if anything is.

Tier — Instant (no model calls)

Pure introspection. tier_used: "instant" for log consistency, but no inference happens. elapsed_ms is typically <50 ms.

When to use it

• On every fresh MCP session start (gate follow-up work on healthy: true)
• After installing or upgrading the server (verify wiring)
• When a tool returns MODEL_UNAVAILABLE or similar (see what’s actually loaded)
• In CI to assert a target environment is set up correctly

When NOT to use it

• You already know prereqs are fine → skip; nothing else surfaces useful info
• You want call-by-call observability → use ollama_log_tail

Schema

{}   // no inputs

Full source: src/tools/doctor.ts.

Example call

{
  "tool": "ollama_doctor",
  "arguments": {}
}

Result shape

{
  "ollama": {
    "reachable": true,
    "host":      "http://127.0.0.1:11434"
  },
  "models": {
    "required":         ["hermes3:8b", "nomic-embed-text"],
    "pulled":           ["hermes3:8b", "nomic-embed-text", "qwen3:8b"],
    "loaded":           ["hermes3:8b"],
    "missing":          [],
    "suggested_pulls":  []
  },
  "profile": {
    "name":  "dev-rtx5080",
    "tiers": {
      "instant":   "hermes3:8b",
      "workhorse": "hermes3:8b",
      "deep":      "hermes3:8b",
      "embed":     "nomic-embed-text"
    }
  },
  "paths": {
    "allowed_roots": ["/repo", "/Users/me/work"],
    "artifact_root": "/Users/me/.ollama-intern/artifacts",
    "log_path":      "/Users/me/.ollama-intern/log.ndjson"
  },
  "recent_errors": [
    { "ts": "2026-05-15T10:23:11Z", "code": "PATH_NOT_ALLOWED", "tool": "ollama_corpus_index" }
  ],
  "healthy": true
}

What healthy: true actually checks

• ollama.reachable === true (the daemon answered)
• models.missing is empty (every required model is pulled)
• paths.allowed_roots is non-empty when any path-bearing tool exists
• recent_errors count is below a sanity threshold
• (v2.9) no definitive cloud misconfiguration when cloud is configured: a 401/403 probe (cloud.auth: "failed") or the sticky misconfigured breaker flips healthy: false — a bad key is broken operator config. A cloud outage (reachable: false) does NOT flip it: local fallback keeps serving and an outage isn’t your config’s fault.

If any check fails, healthy: false and the failing field tells you what.

CLI: the CI persona (v2.9)

ollama-intern-mcp doctor                        # human prose report, always exit 0
ollama-intern-mcp doctor --json                 # the structured DoctorResult, pipeable to jq
ollama-intern-mcp doctor --json --fail-unhealthy # CI gate: exit 1 when unhealthy

--fail-unhealthy also exits 1 when the cloud config itself fails to load (e.g. OLLAMA_CLOUD_PRIMARY set without a key) — the stderr hint names the fix. The default no-flag report is unchanged and never gates.

Common pitfalls

ollama.reachable: false with error: "ECONNREFUSED". The Ollama daemon isn’t running, or it’s bound to a different host than OLLAMA_HOST. Check curl http://127.0.0.1:11434/api/tags from your shell.

models.missing populated. Run ollama pull <model> for each. The default dev-rtx5080 profile needs hermes3:8b + nomic-embed-text.

paths.allowed_roots: [] with a corpus_index failure. You haven’t set INTERN_ALLOWED_ROOTS. Add it to your MCP server’s env block.

recent_errors shows the same code 10x in a row. That code is the real problem; doctor surfaces it but doesn’t fix it. Look up the code in Error codes for the resolution.

healthy: true but a specific tool still fails. Doctor only checks preconditions, not per-tool runtime. Look at the failing tool’s envelope error field for the specific failure.

Related tools

• ollama_log_tail — once doctor says healthy, this is your live observability
• See Error codes for every structured code doctor might surface
• See Troubleshooting for resolutions to the common doctor failures