Ollama Intern MCP
mcp-tool-shop-org/ollama-intern-mcp
Estagiário local em MCP com 42 ferramentas, evidence-first e zero egress padrão
Ver no GitHubServidor MCP que funciona como um estagiário local para Claude Code, oferecendo 42 ferramentas estruturadas com IDs de correlação, relatórios baseados em evidências e artefatos duráveis. Suporta roteamento opcional para Ollama Cloud com fallback automático para modelos locais, validado com Hermes Agent em hermes3:8b.
Instalação
npx convez-ai mcp-tool-shop-org/ollama-intern-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Assistência de código local para Claude com 42 ferramentas estruturadas
- Integração com Hermes Agent usando hermes3:8b ou qwen3
- Processamento local-first com roteamento opcional para cloud (600B models) com fallback
Veredito

Ferramenta sofisticada de MCP que traz automação inteligente para o desenvolvimento local. Arquitetura bem pensada com tiering automático (Instant/Workhorse/Deep/Embed) e suporte a cloud-primary com fallback, mas requer setup técnico e conhecimento de MCP/Ollama para aproveitar ao máximo.
README
A tradução para o português deste README ainda está na fila.
The local intern for Claude Code. 42 job-shaped tools, evidence-first briefs, durable artifacts.
An MCP server that gives Claude Code a local intern with rules, tiers, a desk, and a filing cabinet. Claude picks the tool; the tool picks the tier (Instant / Workhorse / Deep / Embed); the tier writes a file you can open next week.
Also drives Hermes Agent on hermes3:8b — validated end-to-end 2026-04-19. The default ladder is hermes3:8b; qwen3:* is the alternate rail. See Use with Hermes below.
Hardware requirements: ~6 GB VRAM for hermes3:8b, or ~16 GB RAM for CPU inference. See handbook/getting-started for the full breakdown.
Not using Claude? The examples/ directory has a minimal Node.js and Python MCP client you can spawn over stdio. See also handbook/with-hermes.
Local-first — zero network egress until you opt in. No telemetry. No "autonomous" anything. Every call shows its work. Optional Ollama Cloud routing puts 600B-class models behind the same tools when local hardware is the bottleneck — with automatic fallback to local.
New in v2.7.0
Optional Ollama Cloud routing — cloud-primary, local-fallback. Opt in with a key + a flag and the generative tiers route to a 600B-class cloud model; embeddings stay local; a circuit breaker falls back to your local profile on any cloud failure. Off by default — zero egress unless you set both OLLAMA_API_KEY and OLLAMA_CLOUD_PRIMARY=1. Additive minor — pre-v2.7.0 callers (and anyone not opting in) see byte-identical behavior. See Ollama Cloud (optional).
- Cloud-primary with a safety net. A
RoutingOllamaClienttries cloud first and falls back to the local profile on timeout / 5xx / 429 / network. Bad keys (401/403) surface loudly via a sticky breaker instead of degrading silently forever; a retired/typo'd cloud model id (404) surfaces too. - Never a silent downgrade. Every envelope gains
backend(cloud|local),degraded, anddegrade_reasonso you always know when you got the local model instead of the big one. Abackend_fallbackNDJSON event makes the cloud→local fallback rate visible inollama_log_tail. ollama_doctorreports cloud auth + reachability as a distinct block;ollama-intern-mcp doctorshows aCloud (primary)section.- Default cloud model is
minimax-m3:cloud; override per-tier withINTERN_CLOUD_MODEL/INTERN_CLOUD_DEEP_MODEL(e.g.deepseek-v3.1:671b).
New in v2.6.0
Per-call tier-budget override on ollama_extract. Additive minor — pre-v2.6.0 callers unchanged. Detailed entry in CHANGELOG.md.
tier_budget_ms_override?: numberschema field onollama_extract(optional, bounded[1, 600000]ms). When present, applies the override to every tier visited by the runner so the innerrunWithTimeoutAndFallbackmachinery atsrc/guardrails/timeouts.ts:61honors the operator-supplied budget instead of the profile default. The cascade (workhorse → instant on timeout) still fires; the override governs each cascade hop uniformly.- Why this exists. The research-os R-018 wrapper (v0.12.1) wrapped MCP
callToolwithPromise.raceand found the wrapper's budget did not reach the inner tier —DEV_RTX5080_TIMEOUTS.instant = 15_000continued to fireTIER_TIMEOUTat 15000ms regardless of a 180000ms wrapper budget. v2.6.0 supplies the MCP-side authoritative budget so the operator's--planner-timeout-msflag (research-os) finally controls inner-tier timeouts as designed. - Default behavior preserved. Field omitted = profile defaults govern byte-identically. Pre-v2.6.0 callers see zero change.
- R-010 fallback-cause regex preserved. Server-side
TIER_TIMEOUTerror message still matches/elapsed=(\d+)ms/+/budget=(\d+)ms/so AI-advisor visibility downstream works on override and default paths alike. - Consumed by research-os v0.13.0 (cumulative R-019 client wire-up + R-020 + R-021) in a coordinated multi-repo release.
Historical — v2.4.0 deliverables
See CHANGELOG.md and docs/release-notes/v2.4.0.md for the full v2.4.0 entry (per-tier num_ctx control on the profile system).
New in v2.4.0
Per-tier num_ctx (context window) control on the profile system. Additive minor — v2.3.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.4.0.md.
TierConfig.num_ctxmap (new) — optional{ instant?, workhorse?, deep?, embed? }on the profile. When set for a tier, the MCP server placesoptions.num_ctx = <value>on every Ollama generate/chat request routed to that tier (initial + fallback). When unset, the request omitsnum_ctxentirely so Ollama uses its model-loaded default — v2.3.0 behavior preserved exactly.- New envelope field
num_ctx_used?: number— present only when the MCP server actually sentnum_ctx. Absent when the request let Ollama choose. Do not infer a default — the MCP server does not query Ollama for the effective value. - Profile defaults:
dev-rtx5080/dev-rtx5080-qwen3ship withinstant: 4096,workhorse: 8192,deep/embedUNSET. Sized to keephermes3:8bresident in the RTX 5080's 16GB VRAM budget for fast tools.m5-maxleaves every tier UNSET — 128GB unified memory has no spill problem. - Closes the v0.8.0 Phase 1 diagnostic —
hermes3:8bat the default 32K context on RTX 5080 spilled to CPU and started timing out workhorseollama_extractcalls. v2.4.0 prevents that at the profile layer.
Per-tier num_ctx control (new in v2.4.0)
Profile (excerpt from src/profiles.ts):
"dev-rtx5080": {
tiers: {
instant: "hermes3:8b",
workhorse: "hermes3:8b",
deep: "hermes3:8b",
embed: "nomic-embed-text",
num_ctx: {
instant: 4096, // fast classify/summarize
workhorse: 8192, // schema-bound extract / batch
// deep: UNSET — long-context briefs keep current behavior
// embed: UNSET — no context-window pressure on embed
},
},
// ... timeouts, prewarm
}
Envelope on a workhorse-tier call (e.g. ollama_extract):
{
"result": { /* extracted data */ },
"tier_used": "workhorse",
"model": "hermes3:8b",
"num_ctx_used": 8192, // present because the profile set workhorse=8192
// ... rest of envelope unchanged
}
On m5-max (or any profile that leaves a tier unset), num_ctx_used is absent from the envelope and the wire request to Ollama does not include the num_ctx field — Ollama uses its model-loaded default.
Operators tune by selecting / editing the profile; there is no per-call num_ctx input on tool schemas. If a future call surfaces the need, the pattern follows v2.3.0's model override.
Historical — v2.3.0 deliverables
See CHANGELOG.md and docs/release-notes/v2.3.0.md for the full v2.3.0 entry (per-call model override).
New in v2.3.0
Per-call model override across LLM-backed atom tools. Additive minor — v2.2.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.3.0.md.
- Optional
model: stringinput on 8 atom tools —ollama_extract,ollama_classify,ollama_summarize_fast,ollama_summarize_deep,ollama_research,ollama_corpus_answer,ollama_chat,ollama_code_citation. The first attempt on the tool's tier runs against the caller-specified model; on timeout, the existingTIER_FALLBACKcascade resolves the cheaper tier's own model (NOT the caller's override). Composite/brief/pack tools deliberately do NOT acceptmodel— atoms get per-call control, composites use tier defaults. - New envelope field
model_requested?: string— present only when the override was supplied. Calibration-aware callers comparemodel_requestedvsmodelto detect fallback substitution:if (env.model_requested && env.model !== env.model_requested) { /* substitution */ }. Empty / whitespace-only inputs throwZodErrorat schema parse, not silent fallthrough. - Bug fix —
src/version.tsdrift. The runtimeVERSIONconstant is now read frompackage.jsonat module load; v2.1.0 and v2.2.0 had shipped reporting the stale"2.0.0"identity string. Newtests/version.test.tslocksVERSION === pkg.version.
Per-call model override (new in v2.3.0)
{
"tool": "ollama_classify",
"arguments": {
"text": "patch null pointer in auth",
"labels": ["feat", "fix", "chore"],
"frame": "what is the change kind?",
"model": "hermes3:8b"
}
}
Envelope:
{
"result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
"tier_used": "instant",
"model": "hermes3:8b",
"model_requested": "hermes3:8b", // present because override was supplied
// ... rest of envelope unchanged
}
If the workhorse/deep tier had timed out and the call had cascaded to the instant tier, env.model would be the instant tier's resolved model and env.fallback_from would be "workhorse" — env.model_requested would still be "hermes3:8b", and env.model !== env.model_requested is the substitution signal. The override is deliberately NOT carried into the cheaper tier; the chosen model may not fit that tier's role at all.
Historical — v2.2.0 deliverables
See CHANGELOG.md and docs/release-notes/v2.2.0.md for the full v2.2.0 entry (frame-bound topicality + structured abstention).
New in v2.2.0
Local evidence-worker role contract: frame-bound topicality and structured abstention. Additive minor — v2.1.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.2.0.md.
- Frame-bound extraction on
ollama_extract,ollama_classify,ollama_summarize_fast,ollama_summarize_deep— optionalframe: stringinput + structuredframe_alignment/on_topic/frame_addressedoutputs. Off-topic sources are flagged instead of paraphrased into the schema. - Structured abstention on
ollama_research—weak/abstained/sources_address_questionfields. Emptycitations[]with non-emptyansweris no longer silent success. - Topicality threshold on
ollama_corpus_answer— optionalmin_top_score. Below the floor, the tool short-circuits withabstained: trueand skips synthesis. Per-citationscorenow visible on each citation. - Retrieval score preservation through brief evidence —
corpusHitsToEvidencecarriesscore(andcorpus_min_evidence_scoreknob filters at assembly time onincident_brief/repo_brief/change_brief). - Citation line-range bounds —
guardrails/citations.tsrejects out-of-bounds ranges onollama_research, matching the existing posture onollama_code_citation. - Operator-contract docs corrected — README
chunk_id/chunk_indexfix, "validated server-side" rewritten, Evidence Laws section qualified, marketing slogan annotated.
Seed regression — the verification
The slice's contract is verified against the literal research-os fresh-pack failure: arxiv 2112.10422 (Cosmological Standard Timers) under the section-01 frame "What does evidence custody mean in local-first vs cloud LLM deep-research workflows?" — 9 / 9 mocked-LLM contract tests confirm the off-topic source is now contained (frame_alignment.on_topic = false on extract; off_topic: true on classify; frame_addressed: false on summarize_deep; abstained: true on corpus_answer with min_top_score set).
Historical — v2.1.0 deliverables
See CHANGELOG.md for the full v2.1.0 entry (feature pass: 13 new tools + 4 enhancements + freeze lift).
Architecture at a glance
flowchart LR
Claude["Claude Code<br/>(MCP client)"]
MCP["ollama-intern-mcp<br/>server (stdio)"]
Ollama["Ollama daemon<br/>(127.0.0.1:11434)"]
Models[("Hermes 3 / Qwen 3<br/>nomic-embed-text")]
Corpus[("~/.ollama-intern/<br/>corpora/")]
Artifacts[("~/.ollama-intern/<br/>artifacts/")]
NDJSON[("~/.ollama-intern/<br/>log.ndjson")]
Guards{{"Guardrails<br/>citations · banned phrases<br/>protected paths · confidence"}}
Claude -- "JSON-RPC over stdio" --> MCP
MCP --> Guards
MCP -- "/api/generate · /api/chat<br/>/api/embed · /api/ps · /api/tags" --> Ollama
Ollama --> Models
MCP --- Corpus
MCP --- Artifacts
MCP --> NDJSON
Every Claude tool call enters the MCP server over stdio JSON-RPC. The server validates the call against the tool's zod schema, runs the configured guardrails (citation validation, banned-phrase strip, protected-path enforcement, confidence thresholds), then routes to either a deterministic renderer (artifact tier) or an Ollama HTTP call (every other tier). The Ollama daemon never sees user-supplied paths — only the model tier and the prepared prompt. Every call appends one structured event to the NDJSON log at ~/.ollama-intern/log.ndjson, where ollama_log_tail and your shell can read it.
Lead example — one call, one artifact
// Claude → ollama-intern-mcp
{
"tool": "ollama_incident_pack",
"arguments": {
"title": "sprite pipeline 5 AM paging regression",
"logs": "[2026-04-16 05:07] worker-3 OOM killed\n[2026-04-16 05:07] ollama /api/ps reports evicted=true size=8.1GB\n...",
"source_paths": ["F:/AI/sprite-foundry/src/worker.ts", "memory/sprite-foundry-visual-mastery.md"]
}
}
Returns an envelope pointing at a file on disk:
{
"result": {
"pack": "incident",
"slug": "2026-04-16-sprite-pipeline-5-am-paging-regression",
"artifact_md": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.md",
"artifact_json": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.json",
"weak": false,
"evidence_count": 6,
"next_checks": ["residency.evicted across last 24h", "OLLAMA_MAX_LOADED_MODELS vs loaded size"]
},
"tier_used": "deep",
"model": "hermes3:8b",
"hardware_profile": "dev-rtx5080",
"tokens_in": 4180, "tokens_out": 612,
"elapsed_ms": 8410,
"residency": { "in_vram": true, "evicted": false }
}
→ weak: false means ≥2 evidence items were assembled; it does NOT mean the hypotheses are vetted. See Evidence laws below.
That markdown file is the intern's desk output — headings, evidence block with cited ids, investigative next_checks, weak: true banner if evidence is thin. It's deterministic: the renderer is code, not a prompt. (The renderer is deterministic; the content of hypotheses and surfaces is generative — read them as draft, not verified.) Open it tomorrow, diff it next week, export it into a handbook with ollama_artifact_export_to_path.
Every competitor in this category leads with "save tokens." We lead with here is the file the intern wrote.
Second example — build a corpus, then ask it
// 1. Build a persistent, searchable corpus over your project.
{ "tool": "ollama_corpus_index",
"arguments": { "name": "sprite-foundry",
"paths": ["F:/AI/sprite-foundry/src"],
"embed_model": "nomic-embed-text" } }
// → { chunks_written: 1204, paths_indexed: 312, failed_paths: [] }
// 2. Ask an evidence-bound question against it.
{ "tool": "ollama_corpus_answer",
"arguments": { "name": "sprite-foundry",
"query": "how does the worker handle OOM eviction?",
"top_k": 8 } }
// → { answer: "...", citations: [{chunk_index, path}...], weak: false }
The server validates citation identity and that each chunk_index is in range of the retrieved hits. It does NOT prove that every generated claim is semantically supported by the cited chunk content — that's the model's responsibility, and weak retrieval can still produce citation-shaped answers. Full walkthrough in handbook/corpora.
Frame-bound extraction (new in v2.2.0)
ollama_extract, ollama_classify, ollama_summarize_fast, and ollama_summarize_deep accept an optional frame: string input. The frame names the question the source is being asked to answer; the model is instructed to abstain rather than emit true-but-off-topic content when the source doesn't address the frame.
{
"tool": "ollama_extract",
"arguments": {
"text": "<long source document>",
"schema": { /* your fields */ },
"frame": "section purpose here — e.g. 'OOM eviction behavior in the sprite worker'"
}
}
// → result includes frame_alignment: { on_topic: boolean, reason: string, unaddressed_aspects: string[] }
If frame is omitted, behavior is unchanged from v2.1.0. When supplied, frame_alignment.on_topic = false signals that extracted fields may be true-of-the-source but not relevant to the frame — treat that as the same shape as a weak: true brief: useful, but spot-check before promoting into downstream evidence.
Abstention contract (new in v2.2.0)
ollama_research returns structured abstention fields: weak: boolean, abstained: boolean, sources_address_question: boolean | null. An empty citations[] with a non-empty answer is no longer silent — abstained: true says the model declined to synthesize because the caller-supplied paths did not address the question. Treat abstention as a success, not a failure: it is the tool refusing to launder weak retrieval into authoritative output.
ollama_corpus_answer accepts an optional min_top_score: number topicality threshold (0.0–1.0). When the top retrieval score for a query falls below min_top_score, the tool short-circuits with abstained: true and skips synthesis — preventing the "5 off-topic chunks at score 0.21 still drive a full answer" failure mode that the v2.1.0 weak: true rule did not catch (weak: true only fired on hits.length < 2). Pair this with the per-citation score field newly surfaced on each citation to audit retrieval quality directly from the envelope.
What's in here — four tiers, 42 tools
Job-shaped means each tool names a job you'd hand to an intern — classify this, extract that, triage these logs, draft this release note, pack this incident. The tool's input is the job spec; the output is the deliverable. No generic run_model / chat_with_llm primitive at the top.
| Tier | Count | What lives here |
|---|---|---|
| Atoms | 28 | Job-shaped primitives. Original 15: classify, extract, triage_logs, summarize_fast / deep, draft, research, corpus_search / answer / index / refresh / list, embed_search, embed, chat. +13 added in v2.1.0: doctor, log_tail, batch_proof_check (ops); code_map, code_citation, multi_file_refactor_propose, refactor_plan (refactor); artifact_prune, hypothesis_drill (artifact/brief); corpus_health, corpus_amend, corpus_amend_history, corpus_rerank (corpus). Batch-capable atoms (classify, extract, triage_logs) accept items: [{id, text}]. |
| Briefs | 3 | Evidence-backed structured operator briefs. incident_brief, repo_brief, change_brief. Every claim cites an evidence id; unknowns stripped server-side. Weak evidence surfaces weak: true rather than fake narrative. |
| Packs | 3 | Fixed-pipeline compound jobs that write durable markdown + JSON to ~/.ollama-intern/artifacts/. incident_pack, repo_pack, change_pack. Deterministic renderers — no model calls on the artifact shape. |
| Artifacts | 7 | Continuity surface over pack outputs. artifact_list / read / diff / export_to_path, plus three deterministic snippets: incident_note, onboarding_section, release_note. |
Total: 28 atoms + 3 briefs + 3 packs + 7 artifact tools = 42.
Freeze lines:
- Atoms: freeze lifted at v2.1.0 (28 today; +13 added in the v2.1.0 feature pass). New atoms still require an audit-justified gap, tests, handbook page, and CHANGELOG entry — no casual additions.
- Packs frozen at 3. No new pack types.
- Artifact tier frozen at 7.
The full tool reference lives in the handbook.
Install
Requires Ollama running locally and the tier models pulled (see Model pulls below).
Claude Code (recommended)
Most users install this by adding it to their Claude Code MCP server config — no global install required. Claude Code runs the server on demand via npx:
{
"mcpServers": {
"ollama-intern": {
"command": "npx",
"args": ["-y", "ollama-intern-mcp"],
"env": {
"OLLAMA_HOST": "http://127.0.0.1:11434",
"INTERN_PROFILE": "dev-rtx5080"
}
}
}
}
Claude Desktop
Same block, written to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Global install (advanced)
Only needed if you want the binary on your PATH for ad-hoc use outside Claude Code:
npm install -g ollama-intern-mcp
Use with Hermes
This MCP was validated end-to-end with Hermes Agent against hermes3:8b on Ollama (2026-04-19). Hermes is an external agent that calls into this MCP's frozen primitive surface — it does the planning, we do the work.
Reference config (hermes.config.example.yaml in this repo):
model:
provider: custom
base_url: http://localhost:11434/v1
default: hermes3:8b
context_length: 65536 # Hermes requires 64K floor under model.*
providers:
local-ollama:
name: local-ollama
base_url: http://localhost:11434/v1
api_mode: openai_chat
api_key: ollama
model: hermes3:8b
mcp_servers:
ollama-intern:
command: npx
args: ["-y", "ollama-intern-mcp"]
env:
OLLAMA_HOST: http://localhost:11434
INTERN_PROFILE: dev-rtx5080
# hermes3:8b is the default ladder in v2.0.0, so tier overrides are
# only needed if you're pinning a different local model.
Prompt shape matters. Imperative tool-invocation prompts ("Call X with args …") are the integration test — they give an 8B local model enough scaffolding to emit clean tool_calls. List-form multi-task prompts ("do A, then B, then C") are capability benchmarks for larger models; don't interpret a list-form failure on 8B as "the wiring is broken." See handbook/with-hermes for the full integration walkthrough + known transport caveats (Ollama /v1 streaming + openai-SDK non-streaming shim).
Model pulls
Default dev profile (RTX 5080 16GB and similar):
ollama pull hermes3:8b
ollama pull nomic-embed-text
export OLLAMA_MAX_LOADED_MODELS=2
export OLLAMA_KEEP_ALIVE=-1
Qwen 3 alternate rail (same hardware, for Qwen tooling):
ollama pull qwen3:8b
ollama pull qwen3:14b
ollama pull nomic-embed-text
export INTERN_PROFILE=dev-rtx5080-qwen3
M5 Max profile (128GB unified):
ollama pull qwen3:14b
ollama pull qwen3:32b
ollama pull nomic-embed-text
export INTERN_PROFILE=m5-max
Per-tier env vars (INTERN_TIER_INSTANT, INTERN_TIER_WORKHORSE, INTERN_TIER_DEEP, INTERN_EMBED_MODEL) still override profile picks for one-offs.
Uniform envelope
Every tool returns the same shape:
{
result: <tool-specific>,
tier_used: "instant" | "workhorse" | "deep" | "embed",
model: string,
hardware_profile: string, // "dev-rtx5080" | "dev-rtx5080-qwen3" | "m5-max"
tokens_in: number,
tokens_out: number,
elapsed_ms: number,
residency: {
in_vram: boolean,
size_bytes: number,
size_vram_bytes: number,
evicted: boolean
} | null
}
residency comes from Ollama's /api/ps. When evicted: true or size_vram < size, the model paged to disk and inference dropped 5–10× — surface this to the user so they know to restart Ollama or trim loaded-model count.
In Ollama Cloud mode the envelope also carries backend ("cloud" | "local") and, on a cloud→local fallback, degraded: true + degrade_reason. These fields are absent in the default local-only path, so existing consumers are unaffected. residency is null for cloud-served calls (the stateless cloud has no local-VRAM residency).
Every call is logged as one NDJSON line to ~/.ollama-intern/log.ndjson. Filter by hardware_profile to keep dev numbers out of publishable benchmarks.
Hardware profiles
| Profile | Instant | Workhorse | Deep | Embed |
|---|---|---|---|---|
dev-rtx5080 (default) | hermes3 8B | hermes3 8B | hermes3 8B | nomic-embed-text |
dev-rtx5080-qwen3 | qwen3 8B | qwen3 8B | qwen3 14B | nomic-embed-text |
m5-max | qwen3 14B | qwen3 14B | qwen3 32B | nomic-embed-text |
Default dev collapses all three work tiers onto hermes3:8b — the validated Hermes Agent integration path. Same model top to bottom means there is one thing to pull, one residency cost, one set of behavior to understand. Users who prefer Qwen 3 (with its THINK_BY_SHAPE plumbing) opt into dev-rtx5080-qwen3. m5-max is the Qwen 3 ladder sized for unified memory.
Ollama Cloud (optional)
Local 8B models are the hardware bottleneck most people hit. Ollama Cloud serves 600B-class models behind the same /api/* surface, so you can route the heavy tools to a far stronger model and free up local VRAM — while keeping local as an always-on fallback.
This is opt-in and off by default. The package stays local-first with zero egress unless you set both of these. Anyone who doesn't opt in is unaffected.
{
"mcpServers": {
"ollama-intern": {
"command": "npx",
"args": ["-y", "ollama-intern-mcp"],
"env": {
"OLLAMA_CLOUD_PRIMARY": "1",
"OLLAMA_API_KEY": "sk-...your-key...",
"INTERN_PROFILE": "dev-rtx5080"
}
}
}
}
The key is a runtime env var, not a CI secret. A GitHub Actions secret is only visible inside CI runs — it never reaches the running server. Create a key at ollama.com/settings/keys and put it in your MCP client's
envblock (or your shell environment).
How routing works. When cloud is on, the generative tiers (instant / workhorse / deep) go to the cloud model; embeddings always stay local (Ollama Cloud serves no embedding models, so the corpus/embed tools are unaffected). A circuit breaker tries cloud first and falls back to your local profile on timeout / 5xx / 429 / network errors. A bad key (401/403) trips a sticky breaker that surfaces loudly rather than degrading silently. The local profile (INTERN_PROFILE) is the fallback ladder, so keep its models pulled.
You're never silently downgraded. Every envelope reports which backend served the call:
{ ...envelope, backend: "cloud" | "local", degraded?: true, degrade_reason?: "cloud_timeout" | "cloud_5xx" | "cloud_rate_limited" | "cloud_unreachable" | "cloud_auth_failed" | "circuit_open" }
A backend_fallback line lands in ~/.ollama-intern/log.ndjson on every cloud→local fallback (ollama_log_tail --filter_kind backend_fallback), and ollama-intern-mcp doctor shows a Cloud (primary) block with reachability + auth status.
Latency vs quality. Big cloud models run far slower per token than a local 8B (seconds, not milliseconds) — a quality upgrade, not a speed one. Cloud tiers use a generous timeout ladder (instant 30s / workhorse 120s / deep 300s by default).
Cloud env vars
| Var | Default | Purpose |
|---|---|---|
OLLAMA_CLOUD_PRIMARY | (unset) | The opt-in switch. 1/true/yes/on enables cloud-primary. Unset = local-only, zero egress. |
OLLAMA_API_KEY | (unset) | Bearer key for Ollama Cloud. Required when cloud is enabled (fail-fast at startup if missing). |
OLLAMA_CLOUD_HOST | https://ollama.com | Cloud base host. |
INTERN_CLOUD_MODEL | minimax-m3:cloud | Cloud model for instant + workhorse + deep. |
INTERN_CLOUD_DEEP_MODEL | (= INTERN_CLOUD_MODEL) | Optional deep-tier-only override, e.g. deepseek-v3.1:671b. |
INTERN_CLOUD_TIMEOUT_{INSTANT,WORKHORSE,DEEP}_MS | 30000/120000/300000 | Per-tier cloud-attempt timeouts. |
INTERN_CLOUD_NUM_CTX | 32768 | Context-window cap for cloud calls (cloud bills by GPU-time; cap controls cost). |
Model availability changes. Ollama periodically retires cloud models.
minimax-m3:cloud,deepseek-v3.1:671b,gpt-oss:120b, andqwen3-coder:480bare current picks; check ollama.com/search?c=cloud before pinning an id.
Privacy note. Routing to Ollama Cloud sends prompts to a third party. Ollama's privacy policy states cloud prompts are processed transiently, not retained beyond the request, and not used for training — but it is still egress, which is why it's opt-in and disclosed. Local-only mode (the default) sends nothing off the box.
Evidence laws
These are enforced in the server, not the prompt:
- Citations required. Every brief claim cites an evidence id.
- Unknowns stripped server-side. Models that cite ids not in the evidence bundle have those ids dropped with a warning before the result returns.
- ID-validated, not content-validated. Server checks that every cited
evidence_refpoints to a real evidence id in the assembled set. It does NOT verify that the claim text is derivable from the cited evidence — that is the model's job, and weak briefs sometimes contain unsupported claims with valid refs. Useweak: true+ coverage_notes + the includedexcerptfield to spot-check. - Weak is weak. Thin evidence flags
weak: truewith coverage notes. Never smoothed into fake narrative. - Investigative, not prescriptive.
next_checks/read_next/likely_breakpointsonly. Prompts forbid "apply this fix." - Deterministic renderers. Artifact markdown shape is code, not a prompt.
draftstays reserved for prose where model wording matters. - Same-pack diffs only. Cross-pack
artifact_diffis refused loudly; payloads stay distinct.
Artifacts & continuity
Packs write to ~/.ollama-intern/artifacts/{incident,repo,change}/<slug>.(md|json). The artifact tier gives you a continuity surface without turning this into a file-management tool:
artifact_list— metadata-only index, filterable by pack, date, slug globartifact_read— typed read by{pack, slug}or{json_path}artifact_diff— structured same-pack comparison; weak-flip surfacedartifact_export_to_path— writes an existing artifact (with provenance header) to a caller-declaredallowed_roots. Refuses existing files unlessoverwrite: true.artifact_incident_note_snippet— operator-note fragmentartifact_onboarding_section_snippet— handbook fragmentartifact_release_note_snippet— DRAFT release-note fragment
No model calls in this tier. All render from stored content.
Threat model & telemetry
Data touched: file paths the caller explicitly hands in (ollama_research, corpus tools), inline text, and artifacts the caller asks to be written under ~/.ollama-intern/artifacts/ or a caller-declared allowed_roots.
Data NOT touched: anything outside source_paths / allowed_roots. .. is rejected before normalize. artifact_export_to_path refuses existing files unless overwrite: true. Drafts targeting protected paths (memory/, .claude/, docs/canon/, etc.) require explicit confirm_write: true, enforced server-side.
Network egress: off by default. Out of the box the only outbound traffic is to the local Ollama HTTP endpoint — no cloud calls, no update pings, no crash reporting. Opt-in exception: if you enable Ollama Cloud (OLLAMA_CLOUD_PRIMARY=1 + OLLAMA_API_KEY), prompts for the generative tiers are sent to ollama.com over HTTPS with a Bearer key. This is explicit, disclosed, and off unless you set both vars; embeddings still never leave the box. See SECURITY.md §11.
Telemetry: none. Every call is logged as one NDJSON line to ~/.ollama-intern/log.ndjson on your machine. The server itself phones home to nothing.
Errors: structured shape { code, message, hint, retryable }. Stack traces are never exposed through tool results.
Full policy: SECURITY.md.
Standards
Built to the Shipcheck bar. Hard gates A–D pass; see SHIP_GATE.md and SCORECARD.md.
- A. Security — SECURITY.md, threat model, no telemetry, path-safety,
confirm_writeon protected paths - B. Errors — structured shape across all tool results; no raw stacks
- C. Docs — README current, CHANGELOG, LICENSE; tool schemas self-document
- D. Hygiene —
npm run verify(full vitest suite), CI with dep scanning, Dependabot, lockfile,engines.node
Roadmap (hardening, not scope creep)
- Phase 1 — Delegation Spine ✓ shipped: atom surface, uniform envelope, tiered routing, guardrails
- Phase 2 — Truth Spine ✓ shipped: schema v2 chunking, BM25 + RRF, living corpora, evidence-backed briefs, retrieval eval pack
- Phase 3 — Pack & Artifact Spine ✓ shipped: fixed-pipeline packs with durable artifacts + continuity tier
- Phase 4 — Adoption Spine ✓ v2.0.1: three-stage health pass hardened corpus (TOCTOU, 50 MB file cap, symlink rejection, atomic writes, per-file failure capture), tool path traversal, observability (semaphore wait events, timeout error context, profile env-override logging, prewarm cold-start signal), test safety (module-load env snapshot across 10 files,
tools/callE2E). Troubleshooting handbook + hardware minimums added for operators. - Phase 5 — M5 Max benchmarks — publishable numbers once the hardware lands (~2026-04-24)
Phase by hardening layer. Pack and artifact tiers stay frozen at 3 and 7. The atom freeze was lifted at v2.1.0 — new atoms require an audit-justified gap, tests, handbook page, and CHANGELOG entry.
License
MIT — see LICENSE.