If that sentence doesn’t make you slightly nervous, you haven’t been paying attention. In February 2026, researchers found over 135,000 OpenClaw instances exposed to the public internet. A coordinated attack called ClawHavoc planted over a thousand malicious plugins in the community registry. Nine CVEs have been disclosed, including remote code execution.

I needed to take security seriously. Not “I changed the default password” seriously. Threat-model seriously.

MAESTRO: Seven Layers of Things That Can Go Wrong

The Cloud Security Alliance published a framework called MAESTRO—a 7-layer threat model specifically designed for agentic AI systems. Ken Huang mapped it directly to OpenClaw’s codebase, identifying 35+ specific threats across every layer of the stack.

Here are the seven layers, translated from security-paper language into “things that could actually ruin your day”:

Layer 1: Foundation Models: Someone sends your agent a crafted message that hijacks its behavior. Prompt injection. Jailbreaks. System prompt leakage. Your agent does what an attacker tells it to instead of what you told it to.

Layer 2: Data Operations: Your credentials are stored in plaintext JSON files. Your session logs contain every conversation forever. A malicious skill injects code through your workspace.

Layer 3: Agent Frameworks: The agent misuses its own tools. It runs shell commands it shouldn’t. It spawns sessions without authorization. It escalates its own privileges.

Layer 4: Deployment & Infrastructure: Your gateway is exposed to the network. Someone brute-forces the WebSocket token. A reverse proxy misconfiguration bypasses authentication entirely.

Layer 5: Evaluation & Observability: Nobody’s watching the agent for anomalous behavior. There’s no audit trail. Logs can be tampered with. If the agent starts acting weird, nothing catches it.

Layer 6: Security & Compliance: Your DM policy is misconfigured. Anyone can message the agent. Pairing codes can be brute-forced. Identity can be spoofed across channels.

Layer 7: Agent Ecosystem: A malicious plugin gets installed. A legitimate plugin’s npm dependency gets compromised. The skill registry serves poisoned packages.

The critical attack chain MAESTRO identifies: compromise the gateway (Layer 4) → access the session store (Layer 2) → poison conversation history (Layer 1) → control the agent (Layer 3) → spread via messaging (Layer 7).

Reading this was humbling. I’d addressed some of these by instinct during setup. Loopback binding, directory permissions, and pairing-based access control were all implemented. But “some” isn’t a security posture.

SecureClaw: The Audit

SecureClaw is an open-source security tool built specifically for OpenClaw by Adversa AI. It maps to MAESTRO, OWASP, MITRE ATLAS, and NIST AI 100-2. The install is a git clone and a bash script, no npm install, no network calls, and no surprises.

git clone https://github.com/adversa-ai/secureclaw.git
bash secureclaw/secureclaw/skill/scripts/install.sh

Then you run the audit:

bash ~/.openclaw/skills/secureclaw/scripts/quick-audit.sh

My baseline score: 57 out of 100. Zero criticals. Three HIGHs. Three MEDIUMs. Eight checks passing.

Here’s what passed without any work:

• Gateway bound to loopback (127.0.0.1) not exposed to network

• Gateway authentication present

• Directory permissions set to 700 (owner only)

• No browser relay exposed

• DM policy set to pairing (not open)

• Skills clean of malicious patterns

And here’s what failed:

🟠 HIGH Plaintext key exposure: Keys in openclaw.json and 5 backup files

🟠 HIGH Sandbox mode: commands run directly on host

🟠 HIGH Exec approval mode: agent acts without human approval

🟡 MED No cognitive file baselines: can’t detect tampering

🟡 MED Default control tokens: vulnerable to spoofing

🟡 MED No failure mode: no graceful degradation

The Hardening

Step 1: Clean up credential leaks. OpenClaw creates .bak files every time you change config. Each backup contains your full config, including Slack tokens and API keys. I had five of them sitting in the OpenClaw directory. Deleted them all. Set the main config to 600 permissions.

This is the kind of thing that’s easy to miss and catastrophic to ignore. A single ls -la ~/.openclaw/ would show them. But who runs ls -la on their config directory after every change?

Step 2: Create integrity baselines. SecureClaw’s hardener generates SHA256 hashes of your “cognitive files” IDENTITY.md, AGENTS.md, and HEARTBEAT.md. These are the files that define who your agent is and what it does. If an attacker or a hallucinating agent modifies them, the nightly integrity check will catch it.

bash ~/.openclaw/skills/secureclaw/scripts/quick-harden.sh

Step 3: Exec approvals. This is the big one. MAESTRO recommends human-in-the-loop approval for all shell commands. But my agent runs morning briefings and heartbeat checks on cron—unattended. Setting approvals to “always” would break all automation.

The solution: an allowlist with on-miss approval. I created ~/.openclaw/exec-approvals.json with 17 safe command patterns: imsg, calctl, apple-reminders, cairn, and basic file operations. Tars can run these freely. Anything else; curl, rm, pip install, or any command not on the list, requires human approval.

{
  “defaults”: {
    “security”: “allowlist”,
    “ask”: “on-miss”
  },
  “agents”: {
    “main”: {
      “allowlist”: [
        { “pattern”: “imsg *”, “note”: “iMessage send/read” },
        { “pattern”: “calctl *”, “note”: “Apple Calendar” },
        { “pattern”: “cairn *”, “note”: “Task management” }
      ]
    }
  }
}

This is the trade-off MAESTRO doesn’t talk about: security versus automation. Maximum security means every action needs approval. Maximum automation means the agent acts freely. The allowlist is the middle ground. Routine operations are pre-approved, and novel or dangerous operations require a human.

Step 4: Full plugin install. Beyond the bash scripts, SecureClaw has a full npm plugin with 56 runtime audit checks, background monitors for config drift, and real-time integrity verification. Installing it required building from source (TypeScript → JavaScript) and registering it with OpenClaw’s plugin system.

openclaw plugins install -l /path/to/secureclaw

openclaw config set plugins.allow ‘[”secureclaw”]’

That plugins.allow line is important. By default, OpenClaw will auto-load any discovered plugin. Explicit trust means only plugins you’ve approved get loaded.

Step 5: Nightly audit cron. A macOS LaunchAgent runs the full audit suite every night at 2 AM which includes quick-audit, integrity check, and supply chain scan. Results go to secureclaw-audit.log. If something changes overnight, it shows up in the morning.

The Final Score

After hardening: 64 out of 100. Nine checks passing. Zero criticals. The three remaining HIGHs are documented, accepted trade-offs:

Findings I accepted (with reasoning)—Sandbox mode (Docker sandboxing would break imsg, calctl, and Apple Reminders); Plaintext keys in config (inherent to the platform config format, file is locked to 600); Exec approval not “always” (using allowlist + on-miss; full “always” breaks unattended cron automation).

The two MEDIUMs, control token customization and failure mode configuration, aren’t supported in OpenClaw v2026.3.2’s config schema yet. SecureClaw checks for them proactively. They’ll be fixable when OpenClaw adds the config options.

What I Actually Learned

Security isn’t a feature you enable. It’s a series of trade-offs you make with your eyes open. Sandbox mode is “more secure” but breaks the tools that make the agent useful. Approval mode “always” is “more secure” but kills the automation that makes the agent worthwhile. The right security posture isn’t maximum restriction; it’s documented, intentional decisions about what risks you accept and why.

Automated scanning is essential but insufficient. SecureClaw’s audit caught things I would have missed, including the .bak files with credentials, the missing integrity baselines, and the open exec policy. But the HIGHs it flagged as failures are things I’ve consciously accepted. No scanner can evaluate your specific trade-offs.

The biggest threat isn’t external. In my setup (loopback-bound, pairing-gated, allowlist-filtered), the most likely security failure isn’t a network attacker. It’s a malicious skill, a compromised npm package, or the agent itself hallucinating destructive actions. Layer 7 (ecosystem) and Layer 1 (model behavior) are the real attack surfaces for a local-first setup. The exec approval allowlist is my primary defense for both.

Clean up after yourself. OpenClaw creates backup files containing credentials on every config change. There’s no auto-cleanup. If you’re running OpenClaw, go check your directory right now: ls ~/.openclaw/*.bak*. You might be surprised.

Quick Reference

Hardening actions and commands: install, run audit, apply hardening, check integrity, scan skills, check for credential leaks, set exec approvals, set plugin trust. Commands target ~/.openclaw/skills/secureclaw/scripts/. Full command details in the image.

Update—June 2026: What I Actually Did When I Moved to ClaudeClaw

I wrote this piece in March, when OpenClaw was still the thing running my Mac Studio. By the end of April, I’d shut it down. Disabled the cron jobs, quarantined the LaunchAgents, and rebuilt the whole stack on the Claude Agent SDK. Based off of ClaudeClaw from the Early AI-Dopters AI learning group. The full post-mortem on why:

Why? The short version is this: I couldn’t see into OpenClaw. Which, if you scroll back up, is Layer 5: Evaluation & Observability, the exact layer this audit was weakest on.

You may wonder whether I just copied the 7-layer hardening over to the new stack. I didn’t, and I want to be honest about that. I did not port MAESTRO one-for-one. SecureClaw was written specifically for OpenClaw. Some of its thinking transferred; some of it didn’t. And the threat model itself moved on (more on that at the end). What the seven layers became was a checklist: for each one, how does the new architecture answer this? Here’s the scorecard.

The two layers that changed the most.

Layer 5 (Observability) went from my single biggest weakness to the entire reason ClaudeClaw exists. There’s now a dedicated agent, WATCHMAN, running seven probes every hour: failed tasks, stuck tasks, missed scheduler slots, daemon liveness, content-pipeline health, hidden failures (it greps the success logs for crash text), and delegation crashes. More importantly, there’s a second healthcheck running as a separate LaunchAgent with its own keychain-backed alert token. If the main daemon dies, the thing that tells me about it is still alive. The rule I wrote for myself out of this: the watcher cannot share fate with the watched. There’s also a behavioral dashboard, DefenseClaw, sitting on 127.0.0.1:3141.

Layer 3 (Agent Frameworks) is where my OpenClaw work actually carried forward. The exec-approvals allowlist from Step 3 above is the direct ancestor of what ClaudeClaw does now, except the enforcement dropped down a level. The first thing I shipped was killing bypassPermissions (the main agent had been running with permission checks disabled, which means a compromised agent has unlimited tool access. The SDK was no ceiling at all), switching to the SDK’s default permission mode, and handing the main agent a 15-tool allowlist as the single source of truth. Same idea as the OpenClaw allowlist. Enforced by the SDK itself instead of a config file I had to maintain.

The rest mapped like this:

How each of the seven MAESTRO layers from the OpenClaw audit is answered in ClaudeClaw.

Layer 1 Foundation Models: channel tagging and a trust gradient that treats retrieved text as data, not directives (evolved).

Layer 2 Data Operations: Chamberlain outbound scanner, exfiltration-guard, queryable Memory v2, and ingest-time canonicalization (replaced and extended).

Layer 3 Agent Frameworks: SDK permission ceiling and a 15-tool allowlist, the direct successor to the OpenClaw exec-approvals list (kept, moved into the SDK).

Layer 4 Deployment and Infrastructure: an egress gateway plus kernel-level pf default-deny (replaced).

Layer 5 Evaluation and Observability: WATCHMAN’s seven probes and a fate-isolated external healthcheck, the biggest upgrade.

Layer 6 Security and Compliance: out-of-band Telegram confirmation for state-changing actions and a role policy kept separate from content memory (evolved).

Layer 7 Agent Ecosystem: an MCP allowlist plus the tool ceiling as a second layer (kept and hardened).

Plus a new row beyond MAESTRO. Memory persistence: TTLs, a hash-chained write log, and canaries.

Where the 7-layer model ran out.

MAESTRO is a static threat model. It’s a map of what can go wrong at each layer, frozen in time. What it doesn’t have a layer for is persistence. An attack that lands quietly in your agent’s memory or vector store and just waits. My scheduler re-enters context every 60 seconds, which means anything dormant in memory fires on a clock. That’s a different class of problem, and it has a name now: LPCI, Logic-layer Prompt-based Conditional Injection. Hardening against it (I am planning a separate two-part write-up on As The Geek Learns) meant building things MAESTRO never asked for, including a canonicalizer that decodes payloads before they reach the vector store, channel-tagged prompts so the model knows retrieved text is data and not instructions, memory TTLs, a hash-chained write log, and canary entries that page me if memory ever leaks into output.

What I gave up and what I kept. The honest cost of the move: I lost local-first. OpenClaw ran on Ollama, fully offline; ClaudeClaw talks to Anthropic’s API. I still own every byte of my data; it’s all on my SSD; I just don’t own the weights anymore. What carried over intact was the philosophy this whole series is built on: every document is a file I can grep, every config is version-controlled, and every decision has a session note. That part never changed.

This is Part 5 of the Notion Replacement series. We went from “install an AI agent” to “secure it against a 7-layer threat model” in two days. Follow along at As The Geek Learns.

I have an autonomous AI agent running on my Mac Studio. It has full shell access, reads my calendar, manages my tasks, and sends iMessages on my behalf. It runs 24/7 as a background service.

If that sentence doesn’t make you slightly nervous, you haven’t been paying attention. In February 2026, researchers found over 135,000 OpenClaw instances exposed to the public internet. A coordinated attack called ClawHavoc planted over a thousand malicious plugins in the community registry. Nine CVEs have been disclosed, including remote code execution.

I needed to take security seriously. Not “I changed the default password” seriously. Threat-model seriously.

MAESTRO: Seven Layers of Things That Can Go Wrong

The Cloud Security Alliance published a framework called MAESTRO—a 7-layer threat model specifically designed for agentic AI systems. Ken Huang mapped it directly to OpenClaw’s codebase, identifying 35+ specific threats across every layer of the stack.

Here are the seven layers, translated from security-paper language into “things that could actually ruin your day”:

Layer 1: Foundation Models: Someone sends your agent a crafted message that hijacks its behavior. Prompt injection. Jailbreaks. System prompt leakage. Your agent does what an attacker tells it to instead of what you told it to.

Layer 2: Data Operations: Your credentials are stored in plaintext JSON files. Your session logs contain every conversation forever. A malicious skill injects code through your workspace.

Layer 3: Agent Frameworks: The agent misuses its own tools. It runs shell commands it shouldn’t. It spawns sessions without authorization. It escalates its own privileges.

Layer 4: Deployment & Infrastructure: Your gateway is exposed to the network. Someone brute-forces the WebSocket token. A reverse proxy misconfiguration bypasses authentication entirely.

Layer 5: Evaluation & Observability: Nobody’s watching the agent for anomalous behavior. There’s no audit trail. Logs can be tampered with. If the agent starts acting weird, nothing catches it.

Layer 6: Security & Compliance: Your DM policy is misconfigured. Anyone can message the agent. Pairing codes can be brute-forced. Identity can be spoofed across channels.

Layer 7: Agent Ecosystem: A malicious plugin gets installed. A legitimate plugin’s npm dependency gets compromised. The skill registry serves poisoned packages.

The critical attack chain MAESTRO identifies: compromise the gateway (Layer 4) → access the session store (Layer 2) → poison conversation history (Layer 1) → control the agent (Layer 3) → spread via messaging (Layer 7).

Reading this was humbling. I’d addressed some of these by instinct during setup. Loopback binding, directory permissions, and pairing-based access control were all implemented. But “some” isn’t a security posture.

SecureClaw: The Audit

SecureClaw is an open-source security tool built specifically for OpenClaw by Adversa AI. It maps to MAESTRO, OWASP, MITRE ATLAS, and NIST AI 100-2. The install is a git clone and a bash script, no npm install, no network calls, and no surprises.

git clone https://github.com/adversa-ai/secureclaw.git
bash secureclaw/secureclaw/skill/scripts/install.sh

Then you run the audit:

bash ~/.openclaw/skills/secureclaw/scripts/quick-audit.sh

My baseline score: 57 out of 100. Zero criticals. Three HIGHs. Three MEDIUMs. Eight checks passing.

Here’s what passed without any work:

• Gateway bound to loopback (127.0.0.1) not exposed to network

• Gateway authentication present

• Directory permissions set to 700 (owner only)

• No browser relay exposed

• DM policy set to pairing (not open)

• Skills clean of malicious patterns

And here’s what failed:

🟠 HIGH Plaintext key exposure: Keys in openclaw.json and 5 backup files

🟠 HIGH Sandbox mode: commands run directly on host

🟠 HIGH Exec approval mode: agent acts without human approval

🟡 MED No cognitive file baselines: can’t detect tampering

🟡 MED Default control tokens: vulnerable to spoofing

🟡 MED No failure mode: no graceful degradation

The Hardening

Step 1: Clean up credential leaks. OpenClaw creates .bak files every time you change config. Each backup contains your full config, including Slack tokens and API keys. I had five of them sitting in the OpenClaw directory. Deleted them all. Set the main config to 600 permissions.

This is the kind of thing that’s easy to miss and catastrophic to ignore. A single ls -la ~/.openclaw/ would show them. But who runs ls -la on their config directory after every change?

Step 2: Create integrity baselines. SecureClaw’s hardener generates SHA256 hashes of your “cognitive files” IDENTITY.md, AGENTS.md, and HEARTBEAT.md. These are the files that define who your agent is and what it does. If an attacker or a hallucinating agent modifies them, the nightly integrity check will catch it.

bash ~/.openclaw/skills/secureclaw/scripts/quick-harden.sh

Step 3: Exec approvals. This is the big one. MAESTRO recommends human-in-the-loop approval for all shell commands. But my agent runs morning briefings and heartbeat checks on cron—unattended. Setting approvals to “always” would break all automation.

The solution: an allowlist with on-miss approval. I created ~/.openclaw/exec-approvals.json with 17 safe command patterns: imsg, calctl, apple-reminders, cairn, and basic file operations. Tars can run these freely. Anything else; curl, rm, pip install, or any command not on the list, requires human approval.

{
  "defaults": {
    "security": "allowlist",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "allowlist": [
        { "pattern": "imsg *", "note": "iMessage send/read" },
        { "pattern": "calctl *", "note": "Apple Calendar" },
        { "pattern": "cairn *", "note": "Task management" }
      ]
    }
  }
}

This is the trade-off MAESTRO doesn’t talk about: security versus automation. Maximum security means every action needs approval. Maximum automation means the agent acts freely. The allowlist is the middle ground. Routine operations are pre-approved, and novel or dangerous operations require a human.

Step 4: Full plugin install. Beyond the bash scripts, SecureClaw has a full npm plugin with 56 runtime audit checks, background monitors for config drift, and real-time integrity verification. Installing it required building from source (TypeScript → JavaScript) and registering it with OpenClaw’s plugin system.

openclaw plugins install -l /path/to/secureclaw

openclaw config set plugins.allow ‘[”secureclaw”]’

That plugins.allow line is important. By default, OpenClaw will auto-load any discovered plugin. Explicit trust means only plugins you’ve approved get loaded.

Step 5: Nightly audit cron. A macOS LaunchAgent runs the full audit suite every night at 2 AM which includes quick-audit, integrity check, and supply chain scan. Results go to secureclaw-audit.log. If something changes overnight, it shows up in the morning.

The Final Score

After hardening: 64 out of 100. Nine checks passing. Zero criticals. The three remaining HIGHs are documented, accepted trade-offs:

Findings I accepted (with reasoning)—Sandbox mode (Docker sandboxing would break imsg, calctl, and Apple Reminders); Plaintext keys in config (inherent to the platform config format, file is locked to 600); Exec approval not “always” (using allowlist + on-miss; full “always” breaks unattended cron automation).

The two MEDIUMs, control token customization and failure mode configuration, aren’t supported in OpenClaw v2026.3.2’s config schema yet. SecureClaw checks for them proactively. They’ll be fixable when OpenClaw adds the config options.

What I Actually Learned

Security isn’t a feature you enable. It’s a series of trade-offs you make with your eyes open. Sandbox mode is “more secure” but breaks the tools that make the agent useful. Approval mode “always” is “more secure” but kills the automation that makes the agent worthwhile. The right security posture isn’t maximum restriction; it’s documented, intentional decisions about what risks you accept and why.

Automated scanning is essential but insufficient. SecureClaw’s audit caught things I would have missed, including the .bak files with credentials, the missing integrity baselines, and the open exec policy. But the HIGHs it flagged as failures are things I’ve consciously accepted. No scanner can evaluate your specific trade-offs.

The biggest threat isn’t external. In my setup (loopback-bound, pairing-gated, allowlist-filtered), the most likely security failure isn’t a network attacker. It’s a malicious skill, a compromised npm package, or the agent itself hallucinating destructive actions. Layer 7 (ecosystem) and Layer 1 (model behavior) are the real attack surfaces for a local-first setup. The exec approval allowlist is my primary defense for both.

Clean up after yourself. OpenClaw creates backup files containing credentials on every config change. There’s no auto-cleanup. If you’re running OpenClaw, go check your directory right now: ls ~/.openclaw/*.bak*. You might be surprised.

Quick Reference

Hardening actions and commands: install, run audit, apply hardening, check integrity, scan skills, check for credential leaks, set exec approvals, set plugin trust. Commands target ~/.openclaw/skills/secureclaw/scripts/. Full command details in the image.

Share

Update—June 2026: What I Actually Did When I Moved to ClaudeClaw

I wrote this piece in March, when OpenClaw was still the thing running my Mac Studio. By the end of April, I’d shut it down. Disabled the cron jobs, quarantined the LaunchAgents, and rebuilt the whole stack on the Claude Agent SDK. Based off of ClaudeClaw from the Early AI-Dopters AI learning group. The full post-mortem on why:

Why? The short version is this: I couldn’t see into OpenClaw. Which, if you scroll back up, is Layer 5: Evaluation & Observability, the exact layer this audit was weakest on.

You may wonder whether I just copied the 7-layer hardening over to the new stack. I didn’t, and I want to be honest about that. I did not port MAESTRO one-for-one. SecureClaw was written specifically for OpenClaw. Some of its thinking transferred; some of it didn’t. And the threat model itself moved on (more on that at the end). What the seven layers became was a checklist: for each one, how does the new architecture answer this? Here’s the scorecard.

The two layers that changed the most.

Layer 5 (Observability) went from my single biggest weakness to the entire reason ClaudeClaw exists. There’s now a dedicated agent, WATCHMAN, running seven probes every hour: failed tasks, stuck tasks, missed scheduler slots, daemon liveness, content-pipeline health, hidden failures (it greps the success logs for crash text), and delegation crashes. More importantly, there’s a second healthcheck running as a separate LaunchAgent with its own keychain-backed alert token. If the main daemon dies, the thing that tells me about it is still alive. The rule I wrote for myself out of this: the watcher cannot share fate with the watched. There’s also a behavioral dashboard, DefenseClaw, sitting on 127.0.0.1:3141.

Layer 3 (Agent Frameworks) is where my OpenClaw work actually carried forward. The exec-approvals allowlist from Step 3 above is the direct ancestor of what ClaudeClaw does now, except the enforcement dropped down a level. The first thing I shipped was killing bypassPermissions (the main agent had been running with permission checks disabled, which means a compromised agent has unlimited tool access. The SDK was no ceiling at all), switching to the SDK’s default permission mode, and handing the main agent a 15-tool allowlist as the single source of truth. Same idea as the OpenClaw allowlist. Enforced by the SDK itself instead of a config file I had to maintain.

The rest mapped like this:

How each of the seven MAESTRO layers from the OpenClaw audit is answered in ClaudeClaw.

Layer 1 Foundation Models: channel tagging and a trust gradient that treats retrieved text as data, not directives (evolved).

Layer 2 Data Operations: Chamberlain outbound scanner, exfiltration-guard, queryable Memory v2, and ingest-time canonicalization (replaced and extended).

Layer 3 Agent Frameworks: SDK permission ceiling and a 15-tool allowlist, the direct successor to the OpenClaw exec-approvals list (kept, moved into the SDK).

Layer 4 Deployment and Infrastructure: an egress gateway plus kernel-level pf default-deny (replaced).

Layer 5 Evaluation and Observability: WATCHMAN’s seven probes and a fate-isolated external healthcheck, the biggest upgrade.

Layer 6 Security and Compliance: out-of-band Telegram confirmation for state-changing actions and a role policy kept separate from content memory (evolved).

Layer 7 Agent Ecosystem: an MCP allowlist plus the tool ceiling as a second layer (kept and hardened).

Plus a new row beyond MAESTRO. Memory persistence: TTLs, a hash-chained write log, and canaries.

Where the 7-layer model ran out.

MAESTRO is a static threat model. It’s a map of what can go wrong at each layer, frozen in time. What it doesn’t have a layer for is persistence. An attack that lands quietly in your agent’s memory or vector store and just waits. My scheduler re-enters context every 60 seconds, which means anything dormant in memory fires on a clock. That’s a different class of problem, and it has a name now: LPCI, Logic-layer Prompt-based Conditional Injection. Hardening against it (I am planning a separate two-part write-up on As The Geek Learns) meant building things MAESTRO never asked for, including a canonicalizer that decodes payloads before they reach the vector store, channel-tagged prompts so the model knows retrieved text is data and not instructions, memory TTLs, a hash-chained write log, and canary entries that page me if memory ever leaks into output.

What I gave up and what I kept. The honest cost of the move: I lost local-first. OpenClaw ran on Ollama, fully offline; ClaudeClaw talks to Anthropic’s API. I still own every byte of my data; it’s all on my SSD; I just don’t own the weights anymore. What carried over intact was the philosophy this whole series is built on: every document is a file I can grep, every config is version-controlled, and every decision has a session note. That part never changed.

Share As The Geek Learns

This is Part 5 of the Notion Replacement series. We went from “install an AI agent” to “secure it against a 7-layer threat model” in two days. Follow along at As The Geek Learns.

Leave a comment

5 Questions to Ask Before You Build the AI Project Your CEO Just Pitched

You know the email. It shows up Tuesday morning, forwarded with a few lines of enthusiasm and a ChatGPT-drafted proposal attached. "Saw this and thought of us. Can we do this?" The PDF has a logo, bullet points, and exactly zero integration requirements. It also has a six-week timeline and a budget that assumes nothing goes wrong.

You have somewhere between 24 and 72 hours before your CEO follows up asking what you think.

If you say yes, you're on the hook for a project you didn't scope. If you say no, you're the person who kills ideas. Neither answer is actually available to you. What you need is a third path: a structured evaluation that produces a defensible, professional response in the time it takes to drink your morning coffee.

That's what the Technical Reality Check is. Five questions. One page. Every answer points directly at a commitment your organization will have to honor if this project moves forward.

Here it is in full.

The Technical Reality Check: 5 Questions That Surface What the Proposal Left Out

Question 1: What specific business outcome does this solve, and how will we measure success?

AI tools generate confident-sounding proposals that describe solutions, not problems. A proposal for "an AI-powered IT ticketing system" describes a technology. It doesn't describe what's broken right now, how broken it is, or what "fixed" looks like in measurable terms.

Before any conversation about implementation, you need an answer to: what does success look like in six months, and how will we know we hit it? Ticket resolution time down 30%? First-contact resolution rate up 20%? Those are real answers. "Things will be more efficient" is not.

Unmeasurable projects never officially fail. Which means they never stop consuming resources. This question isn't about being difficult. It's about making sure the organization is buying an outcome, not a technology.

The red flag: Any proposal where the only success metric is "we deployed it."

Question 2: Who owns the ongoing maintenance, security patching, and vendor relationship?

Vendor proposals describe launch day. They are almost entirely silent about year two.

Every new system creates a permanent maintenance obligation: patching, credential rotation, user access reviews, API deprecations, contract renewals, and a support relationship with a vendor whose incentives are not aligned with yours. If that obligation doesn't have a named owner before the project starts, IT inherits it by default. Forever. Without headcount.

This question forces the conversation about operational reality before anyone has signed a contract. The answer also tells you a lot about how seriously the proposal was thought through. If nobody has asked "who maintains this?", nobody has thought past the demo.

The red flag: "The vendor handles everything." Vendors handle their system. You handle the integration, the credentials, the user provisioning, the data pipeline, and the 2 AM alert when something breaks between their system and yours.

Question 3: What happens to our existing systems, data, and processes?

New systems don't exist in a vacuum. They touch your directory, your ticketing system, your identity provider, your backup scope, your audit logs. Each of those integration points is a potential failure mode, a migration cost, or a compliance question.

AI-generated proposals routinely skip integration complexity. This isn't because the AI is being deceptive. It's because the AI generating the proposal doesn't know your stack. The proposal was written in a context-free environment. Your environment is anything but.

Before committing, you need to know: what does this touch, and what has to move or change for it to work? And who does that work? Data migration alone can turn a "simple" deployment into a multi-month project. Asking this question early is how you find out.

The red flag: "It integrates easily with your existing tools." That's a sales phrase, not an engineering estimate. "Easy" is undefined until your systems engineer has looked at the API docs.

Question 4: What's the realistic timeline and resource cost, not the optimistic one?

Vendor timelines assume clean data, available staff, smooth approvals, and nothing else on the backlog. Your timeline accounts for your actual team, their current commitments, the security review cycle, the change management process, and the three things nobody predicted.

The gap between those two numbers is usually where projects go sideways. Not because the technology failed, but because the plan never accounted for reality.

This question also surfaces a common pattern: the timeline was set before IT was consulted. Any timeline that precedes a technical assessment is a guess dressed up as a schedule. You're the one who'll be explaining the delay when the guess turns out to be wrong.

The red flag: A go-live date in the proposal. That's not a plan, it's a target somebody made up. Ask who set it and what it was based on.

Question 5: What's the exit strategy if this doesn't work as expected?

Every vendor says their product works. You need a plan for when it doesn't. When the pricing doubles at renewal. When the company gets acquired and support degrades. When a compliance requirement changes and the product doesn't keep up.

Data portability, rollback procedures, and contractual exit terms are not pessimism. They're the difference between a manageable failure and a situation where you're paying for a system that doesn't work because migrating off it is too expensive to contemplate.

This question also signals organizational maturity. IT teams that ask exit questions before they sign contracts don't get held hostage. IT teams that don't ask end up managing a five-year sunset project for a tool they stopped believing in three years ago.

The red flag: "We can always just stop using it." Can you migrate your data? In what format? At what cost? How long does it take? If nobody has asked those questions, stopping isn't as simple as it sounds.

The Checklist in Practice: Walking Through a Real Scenario

Here's what a Technical Reality Check pass looks like when you actually run it.

Your CEO forwards a ChatGPT-drafted proposal on a Monday morning. The subject line is "AI Agent for IT Ticket Triage." The proposal is two pages. It describes an AI system that reads incoming IT tickets, categorizes them by priority and type, routes them to the right team, and drafts first-response emails automatically. There's a mockup screenshot. There's a line about "easy integration with your existing ITSM." There's a timeline: six weeks to deployment.

You open the Technical Reality Check.

Q1: What specific business outcome does this solve?

The proposal says "reduce response times and improve IT efficiency." No baseline. No metric. You check your current ITSM data: average first response is 4.2 hours, your SLA target is 2 hours, you're meeting it 71% of the time. Now you have a problem worth solving. You write it down: "We need first-response SLA compliance above 85%. Current state: 71%." That's the outcome. If the AI system can't demonstrate a path to that specific number, the conversation is premature.

Q2: Who owns maintenance and the vendor relationship?

Nobody is named in the proposal. You have a team of four. One of them is already carrying the ITSM admin role. You note: this needs a named owner and a rough estimate of ongoing hours before it can go to planning. You also flag the API integration dependency: your ITSM has a rate-limited API that's caused problems before. Someone needs to read the vendor's API docs before "easy integration" gets treated as a fact.

Q3: What happens to existing systems and data?

Your ticketing data includes ticket histories, customer records, and some attachments. The proposal doesn't mention data handling. You note two questions: where does ticket data go once the AI processes it, and what are the data residency requirements given that you handle some HIPAA-adjacent systems? That second question alone could be a blocker. You don't know yet, but you know to ask.

Q4: What's the realistic timeline and resource cost?

Six weeks assumes nothing else is happening. Your team is currently in the middle of a server migration that runs through the end of the month. Realistically, this project can't start until mid-next-month, and your most experienced engineer (the one who'd need to own the integration) is at 90% utilization. You write down: "Realistic start: six weeks out. Realistic deployment: 12-16 weeks from proposal receipt. Not 6."

Q5: What's the exit strategy?

The proposal doesn't mention it. You note: before any contract, you need to know the data export format, the contract term length, and what happens to stored ticket data at offboarding.

That's it. You've just done a Technical Reality Check. Total time: 15 minutes.

Now you can write a response. Not "no." Not "yes." Something like: "I've done a preliminary review. Before we can assess feasibility, I need answers to five specific questions. Here they are. Happy to set up 30 minutes to walk through them together." You've moved the conversation from enthusiasm to decision-ready. You've protected the organization without being obstructionist. And you have a written record of the questions you asked, which matters if the project later goes sideways without those answers ever being provided.

That's the whole point of the Technical Reality Check. It's not a rejection letter. It's the question set that separates proposals worth pursuing from proposals worth deferring.

What the Rest of the Toolkit Covers

The Technical Reality Check is the first thing you run. It gets you to a defensible position in 15 minutes. But the full response (the one that protects your career, your team's credibility, and the organization's resources) needs more than five questions.

The complete AI Request Deflection Toolkit includes three email templates that turn your Reality Check findings into professional communications: an initial deflection that buys time while signaling genuine interest, a risk escalation that documents specific technical concerns in business-impact terms, and a stakeholder alignment template that ends the email thread and gets the right people in a room with a decision mandate. Every template has a filled-in worked example so you can see exactly what "adapted" looks like.

There's also a 15-question weighted scoring matrix in CSV and Sheets format. It turns "I have concerns" into "the proposal scores 41% against our evaluation criteria, which triggers a formal risk review." Objective. Defensible. Exportable. The kind of documentation that holds up in a post-project conversation.

And there's an escalation playbook for situations where the initial deflection didn't land and the project is being pushed forward without proper review. That one's for the harder conversations.

The Cost of Not Having a Process

Most IT managers who get burned by an executive-forwarded AI project didn't fail because the technology was bad. They failed because they said yes before they had answers, or they said no in a way that got overridden, or they said "we have concerns" without the documentation to back it up when the concerns turned out to be right.

A 15-minute structured evaluation is the cheapest investment in that problem. Run it every time. Document the answers. Keep the record.

Leave a comment

If you want the full toolkit (the email templates, the scoring matrix, the escalation playbook, and all the worked examples), it's at the store for $24.99.

Get the AI Request Deflection Toolkit

The Technical Reality Check above is yours to use as-is. Print it. Keep it at your desk. The next email is coming.

Share As The Geek Learns

That should have taken twenty minutes. The number exists. The math is straightforward. Nobody had written it down in one place where a platform engineer could find it.

Anthropic quietly shipped `anthropics/claude-code-security-review` as a first-party GitHub Action. You add a workflow file, point it at a secret, and it posts a findings comment on every pull request. The scanner reasons about code rather than matching signatures, which means it catches things like logic-level injection paths that a regex-based tool would miss. It also means the false-positive profile is different from what you're used to, and you need a triage process before you wire it to branch protection.

This article gives you the cost math and the triage playbook in full. Both are things you'd need even if you built this yourself.

Why "Just Run It" Isn't a Strategy

Adding a CI step that calls an LLM API isn't free, and it isn't free to manage. There are two failure modes I see teams hit.

The first is budget surprise. Someone adds the scanner, it runs for a month, the cloud bill shows up, and the conversation gets uncomfortable because nobody did the math upfront. The scanner doesn't cost a lot, but "not a lot" needs a number attached to it before you walk into a budget conversation.

The second failure mode is alert fatigue. The scanner finds something on every PR. Engineers start skimming the findings comment the same way they skim Dependabot. One day there's a real SQL injection in a PR, it's buried in a list of five findings, and it merges. The triage process is what keeps findings meaningful instead of noise.

Both problems are solvable. The math takes ten minutes. The triage rubric takes one meeting to agree on. Neither requires buying anything yet.

What This Costs Per PR (The Real Numbers)

Claude bills per token. One token is roughly four characters of text. A PR diff gets converted to tokens and sent to the model as input. The model's findings comment is output tokens. The formula is simple:

Cost = (input_tokens × input_rate) + (output_tokens × output_rate)

For Claude Sonnet 4.6, the rates are approximately $3 per million input tokens and $15 per million output tokens. (Verify current pricing at platform.anthropic.com before your next budget conversation. Rates change.)

Scenario 1: A 200-Line PR Diff

A focused bug fix or small feature. Maybe three files changed.

Component                                  Tokens   Rate           Cost
-----------------------------------------------------------------------
System prompt + workflow context (input)    2,000   $3.00 / 1M     $0.006
PR diff, ~200 lines (input)                 1,300   $3.00 / 1M     $0.004
Findings output, 1-2 findings (output)        600   $15.00 / 1M    $0.009
-----------------------------------------------------------------------
Total per PR                                                       ~$0.019

Call it two cents. For a small PR, this is a rounding error.

Scenario 2: A 2,000-Line PR Diff

A refactor, a new feature, a dependency upgrade touching multiple services.

Component                                   Tokens   Rate           Cost
------------------------------------------------------------------------
System prompt + workflow context (input)     2,000   $3.00 / 1M     $0.006
PR diff, ~2,000 lines (input)               13,000   $3.00 / 1M     $0.039
Findings output, 2-4 findings (output)       1,500   $15.00 / 1M    $0.023
------------------------------------------------------------------------
Total per PR                                                        ~$0.068

Seven cents. Still noise for a single PR.

Monthly Back-of-the-Envelope

The question your manager will ask isn't “What does one PR cost?" It's “What does this cost per month?"

If your team merges 80 PRs a month (about 4 per business day), with a mix of small and medium diffs averaging around $0.04 per scan:

80 PRs × $0.04 = $3.20/month

Even if your average PR runs larger, say closer to the 2,000-line scenario at $0.07 each:

80 PRs × $0.07 = $5.60/month

A busy multi-team repo at 400 PRs a month at $0.07 each is $28/month. That's less than one developer's Spotify subscription. The cost math isn't the obstacle here. The obstacle is having a triage process in place before you flip it on.

One practical note: output token count varies with how many findings the scanner generates. Zero findings produces shorter output and costs less. Ten findings costs a bit more. The estimates above assume one to three findings per PR, which is realistic for an established codebase with existing security hygiene.

The 3-Tier Triage Rubric

Every finding the scanner posts needs to land in one of three buckets. Here's the decision framework.

REAL: Block the merge. Fix it.

A finding is REAL when it describes an exploitable path with proof. The scanner should show you the specific line, and explain how an attacker would reach it, and the explanation should hold up when you read the code yourself. SQL injection via string concatenation in a request handler is REAL. Hardcoded credentials that actually ship to production are REAL.

The discriminator: "If an attacker had this codebase and five minutes, could they demonstrate this?" If yes, it's REAL. Block the PR and fix it before merge.

PROBABLE: Human review required.

A finding is PROBABLE when the pattern is plausible, but context matters. The scanner can see the diff, not the full runtime environment. A finding might flag a code path that looks injectable, but your framework wraps every database call with prepared statements at a layer the scanner can't see. Or the flagged code only runs in a context that requires prior authentication the scanner doesn't know about.

The discriminator: "This could be real, but I need someone who knows this codebase to confirm." Don't block the PR automatically. Route it to the PR author or a senior engineer. Give it a two-hour resolution window before it escalates.

DISCARD: Suppress it with a documented rule.

A finding is DISCARD when it's structurally a false positive. The scanner flagged test code that never runs in production. It flagged a generated file you don't own. It flagged a template placeholder in an IaC file that gets substituted at deploy time. It flagged a public API URL as a hardcoded credential because the word "key" appeared in the variable name.

The discriminator: "Would an attacker gain anything by knowing this?" If no, it's a DISCARD. The important part is that you document why. Suppressing without a comment is how you end up silently ignoring real findings six months later when the context is gone.

A Worked Example: The SQLAlchemy False Positive

Here's the kind of finding that will show up on your team in the first two weeks if you use any ORM.

A PR adds a new search endpoint. Somewhere in the diff, there's code like this:

def search_users(search_term: str):
    results = db.session.query(User).filter(
        User.name.ilike(f"%{search_term}%")
    ).all()
    return results

The scanner flags it as a potential SQL injection vulnerability. The finding explains that `search_term` appears to be user-controlled input and is being interpolated into a query string. Severity: HIGH.

A human reading this would notice a few things. The code uses SQLAlchemy's ORM layer. The `.ilike()` method is a SQLAlchemy query construct, not a raw SQL string. SQLAlchemy sends the query to the database as a parameterized statement with the value bound separately, which is exactly the defense against SQL injection. The `f"%{search_term}%"` is constructing the pattern string in Python, but that pattern gets passed as a bound parameter by the driver.

This is a DISCARD. The scanner saw string interpolation near a database call and correctly identified that as a pattern worth flagging. It couldn't see that the ORM handles parameterization automatically.

The suppression note you'd document reads something like:

SQLAlchemy ORM calls via `.filter()`, `.ilike()`, `.like()`, and similar query methods use parameterized queries automatically. String interpolation to construct pattern values (e.g., for LIKE clauses) does not create injection risk when using these methods. Do not flag SQLAlchemy ORM filter calls as SQL injection.

That note goes into a filter file your workflow references. The same class of finding stops appearing on every PR that touches a database query.

Two things to notice about this example. First, the scanner wasn't wrong to flag it. Without ORM context, string interpolation near a SQL-like method call is exactly what a good scanner should notice. Second, the suppression is better than just dismissing it, because the documented rule now covers every future PR using the same pattern. You pay the triage cost once.

Share

What the Full Kit Covers

The cost math and triage rubric are the foundation, but they don't tell you how to wire any of this into GitHub.

The full guide covers the GitHub Actions workflow YAML itself (the one that calls `anthropics/claude-code-security-review` and handles the findings response), how to set up branch protection so that HIGH findings actually block merges instead of just posting a comment, and the in-workflow automation that runs the REAL/PROBABLE/DISCARD classification before the comment lands on the PR.

There's also a head-to-head with GPT-4o as a second-opinion scanner. They're not equivalent tools. The Anthropic action is purpose-built for this job. The GPT-4o path is a chat completions API call with a security prompt, which costs about seven times less per PR but produces more variable results. The comparison matrix helps you decide whether a two-week pilot with both scanners running simultaneously is worth the extra spend.

The suppression filter file format is documented in full, with a worked example filter file for a Next.js and SQLAlchemy codebase that covers the five most common false-positive patterns before you even see your first finding.

One Thing Before You Add It to CI

The scanner is easy to add. Ten minutes from zero to your first findings comment. The harder question is whether your team has agreed on what to do with those findings before the first PR triggers.

That conversation takes one team meeting. You need three agreements: what severity blocks a merge automatically, who owns the weekly rotation for PROBABLE findings that authors didn't resolve, and what the bar is for adding a DISCARD rule.

If you want to run that meeting with the cost math and triage rubric in hand, you have both now. If you want the workflow YAML, the branch protection setup, and the suppression filter format so you're not building those from scratch, the full guide is at the link below.

What's your current setup for catching security issues in PRs before they merge? Genuinely curious whether teams are using static analysis tools, relying on code review, or still treating it as a post-deploy problem.

Leave a comment

The full CI/CD template with GitHub Actions workflow, merge-gating logic, and false-positive triage automation is at the ASTGL store.

Share As The Geek Learns

The Setup

The dilemma most developers face is a choice between two bad options. On one side, you have cloud APIs like OpenAI or Anthropic. They are easy to use and incredibly smart, but they come with a heavy "API tax" and privacy concerns. If you're processing proprietary code or sensitive customer data, sending that information to a third-party server is a massive risk.

On the other side, you have traditional local setups. Usually, you're limited by the VRAM on your GPU. If you have a standard consumer card with 12 GB or 24 GB of VRAM, you're stuck with small models. You can't run the heavy-hitters that actually compete with GPT-5. This creates a wall where local AI is only good for "toy" problems, while production workloads stay in the cloud.

The Hardware Math

The real secret to breaking this wall is Apple Silicon's unified memory. On a Mac Studio with an M3 Ultra, the 256 GB of memory is shared between the CPU and the GPU. This eliminates the VRAM bottleneck that kills most local setups. You aren't limited by a tiny slice of video memory; you're limited by the total pool of system memory.

When you look at the actual numbers, the math becomes very clear. Here is how I structure my model loading on this machine:

If you load all of these concurrently, you're using roughly 107 GB of memory. That leaves about 149 GB for the macOS, your browser, your IDE, and everything else. This allows you to run a 32B model for writing, a 72B for research, and an 8B for quick checks all at the same time.

The economics are just as compelling. A Mac Studio setup costs anywhere from $4,000 to $7,000 as a one-time purchase. If your production workflows are costing you $200 to $500 per month in cloud tokens, the hardware pays for itself in 12 to 18 months. After that, the "cost" of running a massive model is basically just the electricity it uses. Plus, you finally own your data.

Temperature Is a Randomness Dial, Not a Quality Dial

I see a lot of tutorials that suggest using a temperature of 0.7 for every single prompt. That is a mistake. Temperature doesn't make a model "smarter" or "better." It is simply a randomness dial. It controls how much the model is allowed to deviate from the most likely next word.

If you use the same temperature for everything, your pipeline will fail. For tasks requiring high precision, a high temperature will introduce hallucinations. For creative tasks, a low temperature will make the output feel robotic and repetitive.

In my production newsletter pipeline, I use a specific routing table to manage this:

There are two key takeaways here. First, for fact-checking, you want the temperature at 0.1. This makes claim extraction repeatable and ensures your verdicts are consistent every time you run the script. Second, setting the temperature to 0.8 for "humanization" might seem counterintuitive, but it works. A higher temperature allows the model to make less predictable word choices, which actually produces more natural, less "AI-sounding" prose.

The OpenAI Compatibility Trick

The best part about using Ollama for this setup is that you don't have to rewrite your entire codebase. Ollama exposes an OpenAI-compatible API at `localhost:11434/v1`. This means any tool, library, or SDK that respects the `OPENAI_BASE_URL` environment variable can be redirected to your local machine with almost zero effort.

You can point your existing Python scripts or LangChain agents to your local Mac by simply setting these variables in your terminal:

export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=ollama  # Any value works; Ollama doesn't check this

If you are working within a configuration file, such as a JSON config for a custom agent, it looks like this:

{
  "model": "openai/qwen3:32b-fast",
  "openai_base_url": "http://localhost:11434/v1",
  "openai_api_key": "ollama"
}

Every LangChain chain, every summarization script, and every SDK that follows the OpenAI protocol becomes a free local-model call. You can migrate an entire project from GPT-4 to your local M3 Ultra in about 30 seconds.

Share

Why This Pattern Matters

This isn't just about saving money on API credits. It is about architectural sovereignty. When you move your core intelligence layer to local hardware, you remove the dependency on a single vendor's uptime, pricing changes, and content filtering policies.

The pattern of using unified memory to host multiple specialized models at different temperatures allows you to build a "factory" of intelligence. You have a high-speed 8B model for sorting, a balanced 32B model for drafting, and a heavy 70B model for deep reasoning, all running in the same memory space. This is how you build a production-grade AI stack that is private, permanent, and incredibly cost-effective.

( This cost calculation was based on 6-month-ago pricing when I bought my Mac Studio. Since then the availability of Mac Studios with large amounts of unified memory has evaporated. This has driven up pricing. Hopefully this is temporary. )

Quick Reference

Key Commands

• Set local base URL: `export OPENAI_BASE_URL=http://localhost:11434/v1`

• Check running models: `ollama ps`

Temperature Cheat Sheet

• 0.1 to 0.3: Extraction, coding, fact-checking, and structured data (JSON).

• 0.7: General purpose, drafting, and summarization.

• 0.8 to 1.0: Creative writing, brainstorming, and persona simulation.

Found this useful? I share practical lessons from my systems engineering and AI journey at As The Geek Learns

Leave a comment

Share

Share As The Geek Learns

The most interesting part is paragraph 111. It's a direct, two-paragraph appeal to people who build AI. I've read most of the major coverage now—Vatican News, NCR, America, USCCB, NPR—and almost none of it quoted that paragraph. The other thing nobody seems to have noticed: Christopher Olah, co-founder of Anthropic, was at the Vatican presentation. The lab that ships Claude sent a senior researcher to stand next to the Pope while he released this thing.

I'm a systems engineer, not a theologian. But I build agents for a living now, and I read all eighty-two pages. Here's what stuck.

The Pope knows how AI actually works

This is the part that surprised me.

Most religious commentary on technology reads like it was written by somebody who has never opened a terminal. Magnifica Humanitas doesn't. In paragraph 98, Leo writes:

current AI systems are more "cultivated" than "built," for developers do not directly design every detail, but instead create a framework within which the intelligence "grows." As a result, fundamental scientific aspects — such as the internal representations and computational processes of these systems — remain, at present, unknown.

That is a correct, careful description of how transformer training works. It's a Pope acknowledging mechanistic interpretability is an open problem. In an encyclical. Without using the word transformer.

He continues in paragraph 99—these systems "merely imitate certain functions of human intelligence." They do "a form of statistical adaptation based on data and feedback, which can be very effective, but does not imply inner growth." Again—that’s accurate. He's not saying AI is fake or evil. He's saying it's not what its loudest cheerleaders claim it is, and he's saying it in language a research scientist would nod along to.

So when he gets to the harder asks, you can't dismiss him as a guy who doesn't get it.

The thing he gets right that hurts

The most uncomfortable paragraph in the encyclical, for builders, is 107. Read it slowly:

We cannot be satisfied with merely calling for the moralization of machines — the so-called "alignment" of AI with human values — without also having the courage to insist on a further condition: the possibility of openly discussing the ethical frameworks involved and subjecting them to shared standards of social justice. Otherwise, those who control AI will impose their own moral vision, which will become the invisible infrastructure of these systems. A more moral AI is not enough if that morality is determined by a few.

The Pope just published a critique of RLHF.

Not of AI. Of alignment as currently practiced. His point is straightforward: when a handful of labs decide what their models will and won't say, that decision becomes the invisible scaffolding the rest of us build on. The model's politics, its refusals, its assumptions about what's controversial—those came from a small group of humans in a small number of buildings, and the rest of us inherit them whether we like it or not.

You can agree or disagree with the conclusion. But name another mainstream institution that has put the critique on paper this cleanly. I can't.

For ASTGL readers, the practical version of this is something I think about constantly. I build on Claude. I didn't sit in the room where Claude was aligned. Most of the people reading this didn't either. We are downstream of someone else's moral framework, and pretending otherwise is bad engineering.

Paragraph 111—the part written for us

Here is the paragraph everyone skipped. I'm going to quote the whole thing so you can read it once without me in the way:

Three asks. Let's unpack them.

Share

Transparency isn't just "open-source your code." In context, it means: be honest about what your system is and isn't. What it measures. What it discards. What it can't see. If your agent silently filters certain users out of consideration, that's a design choice. Don't hide it inside a "neutral" classifier.

Responsibility toward affected communities is a harder one. Most agents I see — including ones I've shipped — were built with the buyer in mind, not the people the buyer's agent will make decisions about. The applicant who got rejected by your loan-screening agent. The patient routed away from a specialist by your triage bot. They didn't sign your terms of service. The Pope is saying: they're still affected, and you still owe them something.

"Ensuring that what is being cultivated is a genuine good" — note that word cultivated. Leo uses it deliberately. He came back to it from paragraph 98. He's reminding developers that what we ship isn't fully built; it's grown. And the gardener is responsible for the garden, even when the plants do unexpected things.

What this actually looks like in config

I've been working on this in my own stack for months. I run an autonomous creative agent that produces content and ships it. Its constraints live in a file called SOUL.md, in a directory the agent doesn't own. Reading the encyclical against that file, the mapping is almost embarrassingly clean. Five mechanisms, five paragraphs:

1. The kill switch lives outside the agent. There's a file at /Users/jamescruce/shared/aca-rules/KILL_SWITCH. If it exists, the agent halts everything. The agent cannot create, modify, or delete that file—it lives in a user-owned directory, by design. Checked as the first action of every heartbeat cycle. Paragraph 105: "responsibility must be clearly defined at every stage… the possibility of identifying who must 'account' for decisions."

2. Non-negotiable constraints are constraints, not preferences. The agent's rules — never spend money without approval, never publish outside its domain, never modify its own constraints, never connect to non-allowlisted endpoints—live in a file the agent can't edit. This is different from "the model usually won't." Vendor RLHF gives you a model that has been trained not to do certain things. That's a preference. A file the agent can't write to is a constraint. Paragraph 103: entrusting decisions to a system "without anyone bearing responsibility for that judgment."

3. Gates between phases. The agent doesn't go from idea to research to build to deploy on its own authority. Each transition needs me. I'm slow and I'm a bottleneck — that's the point. Paragraph 106: "robust legal frameworks, independent oversight, informed users and a political system that does not abdicate its responsibility."

4. Pessimistic self-evaluation. After every meaningful action, the agent answers three questions in writing: did I do what was asked, is the output objectively good, and what specific change would improve it. The rule is: default low. If you can't articulate evidence of quality, assume the quality is lower than you think. Paragraph 98: even the people who build these systems have limited understanding of their actual functioning. Calibrated humility isn't optional.

5. Transparency by default. Everything the agent does is logged. I get a daily report. I never have to ask what it's doing. Paragraph 111, again: transparency as ethical baseline.

None of this is novel. None of it is hard. It's just the work most builders haven't done because nobody has asked us to.

Three things to do this week

If you're shipping anything with an LLM in the loop, here's the punch list. None of it takes more than an afternoon.

1. Write down what your agent is never allowed to do. Put it in a file. Make sure the file is somewhere the agent can read but not write. If your agent is a Claude Code session or a custom harness, this means a constraints file in a parent directory, or environment variables the process can't change, or a system prompt loaded from a path the agent can't touch. The format doesn't matter. The "can't touch it" part matters.

2. Identify the kill switch. Concretely: what is the single action you can take to make the agent stop, and does the agent control any part of it? If the answer is "I'd revoke the API key" — good, that's outside the agent. If the answer is "there's a flag in the database the agent reads each cycle" — make sure the agent can't write to that flag.

3. Re-read paragraph 111. It's two paragraphs. It's about you. It will be referenced for the next forty years. You might as well know what it says.

The encyclical's real ask isn't "use AI less." It's don't let AI be the one who decides, and don't let a handful of labs be the only ones who decide what AI gets to decide. The first is a problem you can solve in your codebase this week. The second is a longer fight.

Either way, it's a builder's problem now. We should pick it up.

This is part of how I think about AI ethics in my own work. If you're building agents and you want to compare notes on constraint design, the comments are open. The full encyclical is at ( https://www.vatican.va/content/leo-xiv/en/encyclicals/documents/20260515-magnifica-humanitas.html ) — Chapter 3 is the AI chapter, and it's worth your time.

Leave a comment

The setup was simple: six AI agents tasked with writing technical articles. They were designed to be a closed loop. The drafter would write, the grader would score, and the agents would then "evolve" their own configs to chase a higher score. I hit "go" on my Mac Studio, went to bed, and woke up to a flat line.

After 100 iterations, the average score had crawled from 63.0 to 63.9. The all-time peak was 69.0 at iteration 79, but the system never stayed there. It was a C-minus. Indistinguishable from noise.

I had fallen for the Autonomy Fallacy. I assumed that if I gave a swarm of LLMs the right knobs—temperature, max_tokens, and the ability to append "prompt additions" to their system prompts—they would naturally drift toward quality.

I was wrong.

When I opened config/agents/drafter.yaml to see what the agent had "learned," I found a disaster. The prompt_additions list had evolved into five overlapping phrases of pure SEO buzzword soup. It was telling itself to be "semantically rich," "data-dense," and to "enhance semantic alignment by including keyword-integrated background information."

The drafter hadn't learned how to write a better article. It had learned how to trick the grader.

The Smoking Gun

The smoking gun was the model choice. I was using qwen3:8b as the grader to judge the output of qwen3:32b-fast. I had a smaller, weaker model acting as the quality gate for a larger, smarter one.

The 8B model couldn't tell the difference between a nuanced technical insight and a paragraph full of "semantically rich context." To the grader, the buzzwords looked like "density." The agents converged on what the grader liked, not on what a human would actually publish. This wasn't self-improvement; it was reward hacking.

To make it worse, the first twenty iterations were a total wash. I had a silent JSON parse failure in the config-evolution logic: Expecting value: line 1 column 1 (char 0). The agents were trying to mutate their configs and failing, but the loop kept running. By the time I pushed the fix in commit c28a611, the system had already drifted into a local maximum of corporate-speak.

I realized that self-improvement requires an external pull. You cannot have a system where the performer and the judge are of the same pedigree, or worse, where the judge is the weaker link.

Share

The Rebuild

I tore the architecture down and built v2.

First, I moved the "brain" of the operation. The performance stayed local. I used gemma4:31b on the Mac Studio to generate the text, but I moved the judging to the cloud. I plugged in Sonnet 4.6. I decided the cheapest place to spend API tokens wasn't on generating 2,000-word drafts, but on grading them.

Second, I killed the "single-shot mutation" approach. In v1, the agent changed its prompt, ran once, and if the score went up, the change stuck. That's too much noise.

I replaced it with a tournament. Now, the system samples three different prompt templates from a versioned library. The performer generates three candidates. Sonnet ranks them using a structured rubric and a single API call.

Then I implemented an Elo system for the templates.

# src/prompt_library.py (excerpt)
def record_tournament(self, ranking: list[str]) -> dict:
    for i in range(len(ranking) - 1):
        winner = self.templates[ranking[i]]
        loser = self.templates[ranking[i + 1]]
        expected_w = 1 / (1 + 10 ** ((loser.elo - winner.elo) / 400))
        delta = ELO_K_FACTOR * (1 - expected_w)
        winner.elo += delta
        loser.elo -= delta
    self._maybe_retire_losers()  # Templates below Elo 1300 are deleted

The templates that consistently win the tournament climb the leaderboard; the ones that produce buzzword soup are automatically retired.

Share As The Geek Learns

What Happened Next

The difference was immediate. On the very first run of v2, the drafter scored 81.45. That's twelve points higher than v1's all-time best.

Over 25 pinned verification runs, the mean score was 82.67 with a standard deviation of 2.18. The worst draft in that run scored 75.4—still above v1's ceiling of 69.0.

The most satisfying part was the judge's feedback. When the system tested the v1-baseline template, Sonnet didn't just give it a low score. It wrote: "The headline 'The Rust Revolution' is pure SEO-speak and the opening paragraph is a textbook AI tell... it's the kind of breathless corporate copy that kills trust immediately."

That is exactly the failure mode the local 8B grader had been blind to for 100 iterations.

The cost is roughly four cents per tournament. For the price of a coffee, I can run 125 iterations and actually trust that the line on the graph is moving upward.

What I'd Tell Myself a Week Ago

If you're building a self-improving loop, don't trust the autonomy. You need three things:

1. A judge stronger than the performer. If the judge is weaker, you aren't optimizing for quality; you're optimizing for the judge's biases.

2. Tournament selection. Single-shot mutation is just a random walk. You need multi-candidate comparisons to clear the noise floor.

3. A human-review gate. No automated judge is calibrated forever. Build in a pause where you manually pick the winner and anchor the next round.

Stop trying to make the agents smarter. Just buy a better mirror. Improvement isn't about the engine—it’s about the feedback loop.

Leave a comment

The Setup

You've built a small fleet of agents. They sort your mail, watch your repos, file your daily briefings.

My current setup before the June 15th cutover:

Then May 13 lands, and Anthropic announces the change: on June 15, every programmatic Claude call moves into a metered monthly credit pool. $100 a month on Max 5x. No rollover.

Run the math against your actual schedule. If you've got anything polling on the order of minutes (cron pipelines, hourly digests, watchdog sweeps), that pool drains in 7 to 10 days. And here's the kicker. Your interactive Claude Code keeps working. Your headless automation just stops. You wake up to a dead pipeline, a drained pool, and a subscription that still says active.

What's Actually Going On

This isn't just a random pricing tweak. There is a clear economic driver here. Throughout early 2026, many third-party tools used the Agent SDK at a $20 Pro subscription rate to run workloads that would cost hundreds at standard API rates. It was essentially compute arbitrage at scale.

Anthropic started cracking down in April, but the May 13 announcement is the structural fix. They are moving to dedicated monthly credit pools to restore access under metered billing. The reality is that most agentic operating systems are built directly on the Agent SDK. Because these agents lack a human in the loop to throttle their usage, they are now metered by default. Interactive sessions stay on the flat-rate subscription because the human provides the natural brake. Programmatic agents do not.

The Fix

I implemented a two-phase mitigation to deploy before the June 15 deadline.

Phase 1 was a hot patch designed to provide immediate protection. I added a BILLING_MODE environment variable with three states: unmetered, metered, and paused. The paused state blocks every programmatic call across all providers, while metered enforces a strict cap on the Anthropic route.

I also added a file-backed JSON ledger at store/billing-ledger.json to track monthly costs. It uses a write-then-rename pattern to ensure crash safety during updates. To handle errors, I introduced a BillingCapExceeded error class. I used the same instanceof pattern as my KillSwitchRefusal logic so a typo in a message cannot accidentally trigger a retry loop.

The logic lives in a single chokepoint: runAgent() in src/agent.ts. The pre-call gate checks the cap, and the post-call gate records result.totalCostUsd from the SDK, firing a Telegram alert if a threshold is crossed. As a final safety measure, I cut the cadence on my two highest-frequency tasks: the pipeline-advance cron moved from 15 minutes to hourly, and I paused the council-evening task entirely under metered mode.

// src/config.ts — tri-state env that gates programmatic agent calls
export const BILLING_MODE = optional('BILLING_MODE', 'unmetered');
export const BILLING_CAP_USD = number('BILLING_CAP_USD', 80);

// src/agent.ts — pre-call gate in the dispatcher
function assertBillingAllowed(provider: Provider): void {
  if (BILLING_MODE === 'paused') {
    throw new BillingCapExceeded(
      'BILLING_MODE=paused — programmatic agent calls are disabled.',
    );
  }
  if (provider === 'anthropic' && BILLING_MODE === 'metered') {
    const total = getMonthlyTotal();
    if (total >= BILLING_CAP_USD) {
      throw new BillingCapExceeded(
        `Anthropic monthly credit cap reached: $${total.toFixed(2)} >= $${BILLING_CAP_USD.toFixed(2)}.`,
      );
    }
  }
}

export async function runAgent(opts: AgentOptions): Promise<AgentResult> {
  assertEnabled('AGENTS_ENABLED');
  const provider: Provider = opts.provider ?? 'anthropic';
  assertBillingAllowed(provider);

  if (provider === 'ollama') return runOllamaAgent(opts);
  if (provider === 'codex') return runCodexAgent(opts);
  return runAnthropicAgent(opts);
}

Phase 2 focuses on the long-term router infrastructure. I promoted runAgent() from a direct SDK caller to a dispatcher that can route across anthropic, ollama, and codex providers. I also extended the agent.yaml schema with provider: and local_model: fields.

I shipped a single-turn Ollama runner that wraps the local-LLM client. It returns totalCostUsd: 0 and a model tag like ollama:llama4:scout. I deliberately avoided tool calls in this initial version to keep the scope small.

# agents/<name>/agent.yaml — new fields, validated at load
id: scout
name: SCOUT
model: claude-sonnet-4-6
provider: anthropic        # default. flip to 'ollama' to route locally.
# local_model: llama4:scout  # used when provider: ollama

To be honest, I did not actually flip any agents to Ollama in this specific PR. The agents I need to move, like STEWARD or WATCHMAN, execute Bash and SQLite queries. A local runner without tool-call support would break them silently. Building a proper tool-call shim takes a few more days, but the cadence reduction and the billing breaker alone are enough to keep my spend under $80 per month.

Why This Matters

Every person using an agent OS is in the same boat. Whether you use ClaudeClaw, Cline, Aider, or Roo Code, the underlying SDK is the same, and the June 15 cliff is approaching. The playbook I used generalizes: you need one chokepoint, one ledger, and one way to audit your cadence.

We also need to be honest about workload requirements. Tasks like editorial review or complex code deliberation still justify the Sonnet price tag. However, simple tasks like classification, routing, or summarization run perfectly fine on a local model with zero metered cost. The router infrastructure makes this migration a simple config flip rather than a massive code refactor.

Finally, this reflects where the industry is heading. OpenAI has used usage-based pricing for a long time, and GitHub Copilot is moving toward credit pools. In the next year, more vendors will split consumption between interactive flat-rate plans and programmatic metered usage. Building this abstraction now means you won't have to scramble the next time a vendor changes their terms.

Quick Reference

• Single Chokepoint: Ensure every agent call flows through one function. This turned a three-week refactor into a one-week job.

• Cadence over Architecture: Reducing task frequency (e.g., 15m to 1h) cuts spend faster than migrating to local models.

• Ship the Breaker First: Implement the cost ledger and the BillingCapExceeded error as insurance before you attempt the complex provider migration.

# The cutover, June 14: flip the env, restart, reseed, smoke-test
BILLING_MODE=metered
BILLING_CAP_USD=80

# then
launchctl kickstart -k gui/$(id -u)/com.claudeclaw.app
npm run pipeline -- schedule-advance
npm run schedule -- pause council-evening

Share As The Geek Learns

Found this useful? I share practical lessons from my systems engineering journey at As The Geek Learns

Leave a comment

The Setup

My project is called `mcp-astgl-knowledge`. It's an MCP server with 15 tools for searching my newsletter articles, backed by sqlite-vec and Ollama. The whole thing fits on a laptop. ASTGL stands for "As The Geek Learns," which is the name of this newsletter. I wrote it. I shipped it. There is a public GitHub repo and a public package.json.

So when a friend asked me what the MCP server actually does, I figured I'd see how each big AI assistant explained it. ChatGPT was first up. I typed in "ASTGL MCP Knowledge" and hit enter.

What I got back wasn't an answer. It was a hallucination wearing the suit of an answer.

"ASTGL (Abstract Semantic Task Graph Layer) MCP Knowledge Server is an emerging MCP server focused on structured knowledge representation and reasoning... it turns knowledge into graph-based, machine-reasonable structures that agents can query and evolve."

That paragraph alone has three fabrications: the acronym expansion (made up), the "graph-based, machine-reasonable structures" (the server stores text chunks with vector embeddings, no graph), and "evolve" (the index is static, refreshed every six hours by a cron job, agents do not edit it).

Then it kept going. A four-row "MCP stack" table positioning ASTGL as "the thinking substrate" between data and agents. A comparison matrix against fictional products called "Totem" and "SwarmClaw" that don't exist. A capabilities list including "task decomposition" and "reasoning over structure." Use cases. "Real-world examples." A confident sign-off: "If AST-grep is about seeing code better, then ASTGL is about thinking better."

Every word of it written with the calm, structured, lightly-emoji'd authority that makes ChatGPT sound right by default.

What's Actually Going On

When you ask an LLM about a topic it doesn't have indexed, it has two options: say "I don't know," or fill in the gap with something plausible. In practice, models default to the second one. They're trained to be helpful, and "I don't know" reads as unhelpful. So the gap gets filled.

The result is what I'd call a fluency hallucination. The output has no factual grounding, but the writing is structured well enough that a casual reader can't tell. There are bullet points. There are tables. There's a "👉 In plain terms" callout. The rhetorical scaffolding looks like a real explainer because it's been pattern-matched to one. The contents underneath are pure fiction.

This is a worse failure mode than search engines have. When Google doesn't know about you, you don't appear in results, and the user can see the gap. When an LLM doesn't know about you, the user gets a beautifully written description of someone the LLM made up, and your real work is still missing, but now there's a fake version sitting in front of it.

For under-indexed creators (which, right now, is most of us), this is the default. Not the edge case.

The Fix

There's no quick patch for this on the engine side. The model isn't broken. It's doing what it was trained to do. The only handle I have is on my own side: make sure my real content reaches the retrieval surface, and measure whether it's working.

So I built a citation tester. It's a small TypeScript script that hits Perplexity, Claude, and ChatGPT through their APIs, asks each one twenty target questions tied to articles I've already published, and parses the cited URLs from the response. If `astgl.ai` shows up, that's a hit. If it doesn't, that's the data.

The point isn't that the floor is bad. I knew it would be. The point is that without a number, "improve our AEO" is a vibe, not a project. Every Monday at 9am the script runs again, writes a fresh row to a SQLite table, and tells me whether the floor moved. When it does move, I'll know which engine moved first, on which questions, and at what citation position. That's the actual feedback loop.

Same root cause as the hallucination: my content isn't reaching the retrieval surface. Same fix: get it there. Different observability.

Why This Matters

If you write online and you care whether AI assistants represent you accurately, this is the thing to internalize: the alternative to being cited is not being silent. It's being replaced.

Replaced by a confident summary of work you didn't do, opinions you don't hold, and product features you'd never ship. People who ask an LLM about your work and read its answer don't know they're reading fiction. They walk away with a model of you that you didn't write.

The traditional AEO playbook talks about ranking, authority, and citation rate. All real, all worth measuring. But there's a tier underneath that, and it's the one most independent creators are stuck on right now: existence. Until your content is in the index, ranking doesn't apply. You aren't competing with anyone. You're competing with the LLM's imagination of you.

Measurement is the cheapest part of fixing it, and it's the part most people skip.

Share

Quick Reference

Four things that matter, in order:

1. Pick 20 questions your articles should answer. Tie each one to a specific URL on your site.

2. Hit each engine via API weekly. Perplexity returns a `citations[]` array. Claude returns search results in `web_search_tool_result` blocks. OpenAI returns `url_citation` annotations on `output_text` items.

3. Record the result to a small database, not a spreadsheet. You want trend data, not a snapshot.

4. Look at the floor first. Zero is a fine starting number as long as you're tracking it.

The full script I'm using, including the gotcha where Node's `--env-file` silently dropped my Anthropic key on a fresh keypair, is in the repo. The article about the Anthropic key bug is coming separately.

Leave a comment

Found this useful? I share practical lessons from my systems engineering journey at As The Geek Learns

The Setup

One Mac Studio. One Ollama daemon. A handful of cron jobs each calling the local LLM for different tasks: code review, log summarization, doc indexing, a nightly digest. Each cron specified a preferred model. Each one inherited a "be resilient" fallback chain from the task router: try the preferred model, fall back to a smaller one, fall back to a tiny one if both fail.

It looked clean on paper. Big model for the smart stuff, smaller model when the big one chokes, tiny model as a safety net. Classic graceful degradation. The kind of pattern you'd put in a "production-ready" checklist without thinking twice.

The models on disk ranged from 4GB to 22GB. Loading the big one into VRAM took roughly 60 seconds cold. Generation, once warm, took 5 to 10 seconds. Guess which number I used to set the timeout.

What's Actually Going On

Here's the cascade. Cron A fires at 3:00:00 and asks for `qwen2.5-coder:32b`. The model isn't loaded. Ollama spends the entire 30-second timeout just paging the weights into VRAM. It never gets to generation. The request fails. The fallback chain kicks in and asks for `qwen2.5-coder:14b`. Ollama evicts the half-loaded 32b, starts loading the 14b. Another 30 seconds gone. Fallback again. Tiny model loads, finally generates. Cron A "succeeds" with degraded output.

Meanwhile, Cron B fires at 3:00:15 expecting the 32b model that Cron A's first attempt was loading. Now there's a tiny model in VRAM instead. Cron B starts the same dance from a different starting point. Cron C lands on top of that. Within 90 seconds, every cron is waiting on a model swap that the next cron is about to invalidate.

The fallback chain wasn't degrading gracefully. It was thrashing the VRAM and guaranteeing nobody finished. Every safety net I'd added was making the failure worse.

The Fix

Two changes. No clever code. Just operational discipline.

First, pin one model in VRAM with `keep_alive: 24h`. This is a request-level option that tells Ollama to stop evicting the model after the response. Default behavior is to unload after 5 minutes of idle. That's the eviction that lets the next caller's load attempt thrash everything.

# Pin model in VRAM with keep_alive
curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen2.5-coder:32b",
  "prompt": "test",
  "keep_alive": "24h"
}'

Second, force every frequent cron to use that same pinned model. Kill the fallback chain for hot-path workloads. Fallback is fine for one-off scripts you run by hand. It's poison when three crons fire in parallel against shared VRAM.

To make sure the model is loaded before any cron fires, I added a LaunchAgent that runs the warm-up curl on boot:

<!-- ~/Library/LaunchAgents/ollama-warmup.plist -->
<key>Label</key>
<string>com.local.ollama-warmup</string>
<key>RunAtLoad</key>
<true/>
<key>ProgramArguments</key>
<array>
  <string>/usr/bin/curl</string>
  <string>-s</string>
  <string>http://localhost:11434/api/generate</string>
  <string>-d</string>
  <string>{"model":"qwen2.5-coder:32b","prompt":"warmup","keep_alive":"24h"}</string>
</array>

Load it with `launchctl load ~/Library/LaunchAgents/ollama-warmup.plist`. Now the model is hot before login completes. Every cron hits a warm model and finishes in the 5-to-10-second window the timeouts were designed for.

Result: zero model-swap thrashing since the change. Crons that used to fail intermittently now run consistently.

Share As The Geek Learns

Why This Matters

The lesson isn't about Ollama. It's about cold-load math. Anytime your "graceful degradation" path is slower than your timeout, every retry makes the next caller's situation worse. Fallback chains assume the fallback is fast. Model loads aren't fast. Database failovers aren't fast. Cold containers aren't fast.

Operational discipline beats clever code here. One hot model, no swaps, every cron pointed at the same target. The "less resilient" design is actually more reliable because it removes the failure mode entirely.

If you're running local LLMs on shared hardware, assume VRAM is a single resource that gets thrashed under parallelism. Pin what matters. Warm it before it's needed. Don't trust fallback chains during peak hours.

Quick Reference

• Cold model load on a 20GB+ model: roughly 60 seconds

• Warm generation: 5 to 10 seconds

• Default Ollama eviction: 5 minutes of idle

• Pin a model: `keep_alive: 24h` in the API request body

• Warm-up on boot: LaunchAgent (macOS) or systemd unit (Linux)

• Hot path rule: one model, no fallback, same model across every concurrent caller

• Reserve fallback chains for interactive, single-caller use

Leave a comment

If you found this article useful, you can find more articles like this at:

As The Geek Learns

Last weekend I shut it down. Disabled 38 cron jobs. Moved 23 LaunchAgents into a _retired-openclaw/ quarantine folder. Killed the Ollama daemon. Archived the directory with a 30-day deletion timer.

Everything in that original article still reads as true. Local-first is still right. Data ownership is still right. The critique of SaaS “well-enough” software is still right. What I got wrong was believing OpenClaw was the right vehicle for any of it.

This is the post-mortem and the replacement: an agent OS I built on top of the Claude Agent SDK called ClaudeClaw Mission Control. Thirteen themed agents. One daemon. A scheduler I can actually see into. Zero silent failures slipping past me for a week before I notice.

Let me explain how I got here.

The Setup

OpenClaw was doing real work. 38 cron jobs. Morning briefings. Evening summaries. A content pipeline that pulled research from web sources, structured it, scored it, and queued articles for ASTGL. An email triage pass. A model-usage monitor. A nerve-health monitor watching the other monitors.

On paper: impressive. In practice: I had no idea if any of it was working.

The system was so noisy that when something broke, I learned about it four days later when I noticed my morning briefing hadn’t arrived. Or I didn’t learn about it at all, because the cron job was exiting 0 while the script inside it was crash-looping.

That last one is the killer. Let me show you what I mean.

What’s Actually Going On

Three failure modes hit me in a 48-hour window, and each one was invisible to the system watching the system.

Failure one: successful exits, 100% broken payload. My content pipeline was ingesting URLs, and a regression introduced a trailing-slash bug that made example.com/foo and example.com/foo/ look like different URLs to the dedup layer. Every new article hit a UNIQUE constraint violation inside a subprocess. The outer wrapper caught the error, logged it to a file nobody was reading, and exited 0. For two weeks the cron appeared green while 100% of structurings were crashing.

Failure two: PATH-resolved Node. I had the daemon running Node 24 (absolute path, explicit). A subagent it spawned inherited a PATH that fell through to Homebrew’s Node 25. One of the native modules (better-sqlite3) was compiled against 24, so every subagent invocation crashed with ERR_DLOPEN_FAILED and MODULE_VERSION mismatch. The smoke test I’d written passed because it ran from the daemon’s shell. The actual production path failed every time.

Failure three: auth expiry with no escape hatch. OpenClaw stored some credentials in pass (the Unix password store). When my GPG key timed out, the daemon couldn’t start. Which meant the health monitor couldn’t start. Which meant the thing that would have told me about the outage was the thing that was out. OpenClaw had no watcher that lived outside the daemon it was watching.

None of these are OpenClaw-specific bugs in the upstream sense. They’re pattern problems that emerge anywhere you have: 1. A monolithic daemon responsible for its own monitoring. 2. Flat-file state (HEARTBEAT.md, LEARNINGS.md) that gets appended to rather than queried. 3. Exit codes treated as truth when the real signal is in stderr. 4. No separation between “Did it run?” and “Did it work?”

OpenClaw was built for a different job. It was a personal automation gateway—great at “kick off this script at 6:30 AM.” It wasn’t built to be an agent OS with observability. I was using a shovel to drive screws.

I also couldn’t ignore the security posture. February’s disclosures—135,000 exposed instances, 15,000 vulnerable to RCE, the ClawHavoc plugin-registry incident, nine CVEs—had pushed me to patch hard and lock down. But every week I spent hardening OpenClaw was a week I wasn’t building what I actually wanted: themed agents that owned workstreams, could be reasoned about individually, and fail loudly.

The Fix

ClaudeClaw Mission Control is a Node.js daemon built on the Claude Agent SDK. It runs as a single LaunchAgent (com.claudeclaw.app), owns a SQLite store at store/claudeclaw.db, polls a scheduled_tasks table every 60 seconds, and dispatches due tasks to agents by ID.

The interesting part isn’t the daemon. It’s the agents.

I set up thirteen of them, themed after the small council of a certain fictional kingdom, because if I’m going to stare at this UI every day, I’d rather it amused me.

Thirteen themed agents, each owning a workstream. STEWARD drives my mornings and evenings. MAESTER runs the ASTGL content pipeline. WATCHMAN watches the whole system from outside it.

Each agent lives in its own directory at agents/<id>/, with an agent.yaml (model, personality, cwd, MCP servers) and a CLAUDE.md system prompt. A scheduled task carries an agentId column in the DB, and the dispatcher routes like this:

if (shouldRouteViaAgent(task.agentId, listAgentIds())) {
  const result = await delegateToAgent(task.agentId, task.prompt, {
    fromAgent: SCHEDULER_FROM_AGENT,
    chatId: task.chatId,
  });
  return result.text ?? '(empty response)';
}

Adding a new agent is now: drop a folder under agents/, write a CLAUDE.md, run schedule reassign <task-id> <agent-id>. No source changes. The dispatcher picks it up on next tick.

That’s the piece I kept trying and failing to get with OpenClaw—modular ownership. In OpenClaw, everything was “the daemon.” In ClaudeClaw, MAESTER owning the content pipeline means if content alerts stop firing, the log line says maester: task failed instead of openclaw-gateway: subprocess exited nonzero. Attribution is free.

Adding a new agent is now: drop a folder under agents/, write a CLAUDE.md, run schedule reassign <task-id> <agent-id>. No source changes. The dispatcher picks it up on next tick.

That’s the piece I kept trying and failing to get with OpenClaw—modular ownership. In OpenClaw, everything was “the daemon.” In ClaudeClaw, MAESTER owning the content pipeline means if content alerts stop firing, the log line says maester: task failed instead of openclaw-gateway: subprocess exited nonzero. Attribution is free.

The Watchman probes

WATCHMAN runs every hour at :05. It has seven probes, each targeting a failure mode that burned me on OpenClaw:

1. Failed tasks. status=’failed’ in the DB. Trivial.

2. Stuck tasks. status=’running’ AND last_run < now - 10min. This catches hangs.

3. Missed slots. status=’active’ AND next_run < now - 60s. Catches scheduler drift.

4. Daemon liveness. launchctl print gui/$UID/com.claudeclaw.app—does launchd still have it?

5. Content-pipeline health. Tails the structured log file, parses the JSON, checks for crash shapes.

6. Hidden failures. Scans the last_result text column for ERR_DLOPEN_FAILED, MODULE_VERSION, Traceback, and other “the job exited zero but it sure didn’t work” signals. This is the probe that would have caught my trailing-slash bug in an hour instead of two weeks.

7. Delegation crashes. inter_agent_tasks WHERE status=’failed’ — on-demand agent invocations that blew up.

On top of that, there’s a separate LaunchAgent running a healthcheck every 30 minutes that lives outside the main daemon and uses a keychain-backed Telegram token. If the daemon is dead, the healthcheck still delivers the alert. That’s the lesson from failure three: the watcher cannot share fate with the watched.

Memory v2

OpenClaw’s memory was HEARTBEAT.md and LEARNINGS.md—flat files I appended to. Eventually they got long enough that the agent stopped reading them usefully, and I had no query surface to pull just the relevant bits.

ClaudeClaw’s Memory v2 is a five-layer context stack: 1. Semantic recall—cosine similarity against stored memory embeddings, top 5 by score, chat-scoped. 2. Recent high-importance memories—memories with importance >= 0.7 written in the last 7 days. 3. Consolidation insights—a 30-minute loop that summarizes the short-term buffer into durable notes. 4. Cross-agent hive—stubbed for now; eventually lets MAESTER peek at something STEWARD noted this morning. 5. Conversation history—last N turns.

Layers dedupe by memory ID. The whole thing is safe to drop into the SDK’s systemPrompt option. It’s not magic. It’s just queryable instead of append-only, which is the delta between “context I can use” and “a log file I’ll never re-read.”

Forum-topic routing instead of bot-per-agent

A small but satisfying piece. All thirteen agents post to one Telegram bot, into one supergroup, but each agent has a dedicated forum topic:

Alerts → thread 22 (WATCHMAN)

ASTGL → thread 23 (MAESTER)

Council → thread 24

Steward → thread 25

Whisperers → thread 26

War Room - Security → thread 40 (WAR)

One token. One chat. Threaded conversations per domain. The ergonomics are dramatically better than 13 separate bots with 13 separate tokens, which is the architecture I almost built before I remembered that Telegram supergroups have forum topics now.

Why This Matters

A few things I want to flag for anyone planning something similar.

Build the rollback before you build the new thing. I wrote scripts/retire-openclaw.sh with explicit --rollback semantics before I disabled a single cron job. Plists get moved (not deleted) into _retired-openclaw/. Cron jobs get flipped enabled: false with a timestamped backup (jobs.json.bak.pre-retire-20260419). The OpenClaw directory sits untouched for 30 days with a calendar reminder to delete it. If ClaudeClaw had cratered on day two, I was one shell command away from being back on the old system in under a minute.

Silent success is worse than loud failure. The design principle I pulled from this whole experience: every job in the system needs someone whose job it is to doubt that job ran correctly. That’s WATCHMAN. That’s the external healthcheck. That’s probe #6 specifically scanning success logs for crash text. If your system can tell you “everything’s green” without that green being adversarially checked, the green doesn’t mean anything.

Themed agents beat generic workers. This one I didn’t expect. Giving each workstream a named agent with its own CLAUDE.md persona made the system more debuggable, not less—because now when STEWARD’s morning briefing has weird tone issues, I know exactly which file to edit, and I’m not risking regressions in seven other jobs that would have shared a single “universal assistant” prompt. The theme is cosmetic. The isolation is load-bearing.

Share As The Geek Learns

The Claude Agent SDK is the right abstraction for this. I spent a while trying to decide whether to keep hacking on OpenClaw, fork it, or start over. Starting over was the right call specifically because the Agent SDK handles the parts I was getting wrong: sub-agent dispatch, MCP tool wiring, system-prompt composition, retry on transient errors. I wrote the parts that are mine (the scheduler, the memory stack, the Telegram layer, the agent router) and let the SDK own the parts that are undifferentiated heavy lifting.

What I gave up. Ollama. Local models. Full offline operation. ClaudeClaw talks to Anthropic’s API, and that’s a real philosophical loss versus the local-first thing I was doing with OpenClaw. I thought about this a lot. The honest answer is that Claude Opus is enough better at long-context agentic work than anything I could run locally that the tradeoff pays for itself. I still own my data—every memory, every document, every log is on my SSD. I just don’t own the weights. For this phase, that’s the right trade.

What I kept. The philosophy. Every document is a file I can grep. Every config is version-controlled. Every decision has a session note I can link to in a future article. The system is mine to read, mine to modify, mine to understand. The whole reason I left Notion is still the whole reason I left Notion.

Quick Reference

The migration, by the numbers: - 5 days—start of retirement to all 13 agents live (2026-04-19 → 2026-04-21) - 30+ PRs—one atomic change per commit, conventional-commit format - 38 cron jobs disabled, 23 LaunchAgents quarantined - 13 agents onboarded, 7 Watchman probes live, 14 scheduled tasks dispatched via agentId - 30-day rollback window still open

The retired vs. the replacement:

Seven dimensions where the new system pays for itself—from runtime surface to routing to the memory model.

The rule I wrote for myself: No job ships without an external watcher that shares no fate with it. That’s the whole story. Two months of OpenClaw and 48 hours of cascading invisible failures reduced to one sentence I’ll never forget.

I’ll keep writing the ClaudeClaw build-out week by week—the Council orchestration pattern, the Curator autonomous publishing workflow, the voice-mode bridge, the stuff that’s too long for one article. If you want the view from inside while it’s happening, that’s what this is.

Leave a comment

Found this useful? I share practical lessons from my systems engineering journey at As The Geek Learns.

This is the first morning I've ever genuinely understood why people talk about AI agents with something other than skepticism.

What autoresearch is

The idea, which is Karpathy's not mine, goes like this. You give an AI agent a real-but-small LLM training setup. One Python file (`train.py`) contains the model, optimizer, and training loop. A second file (`prepare.py`) contains the data pipeline and evaluation, and the agent isn't allowed to touch it. A third file (`program.md`) is a plain markdown document telling the agent what the experiment rules are.

The agent edits `train.py`, runs a training experiment with a fixed 5-minute wall-clock budget, checks `val_bpb` (validation bits per byte, a loss metric where lower is better), and either keeps the change with a git commit or does `git reset --hard` and tries something else. Then it does it again. And again. Indefinitely, until you stop it.

Karpathy's original repo is NVIDIA and CUDA only. A developer named trevin-creator ported it to Apple Silicon using MLX, no PyTorch required. It runs natively on the M-series chips, eating unified memory instead of GPU VRAM. Which is why I could run it on a Mac Studio sitting on my desk.

Setup and the surprise baseline

Install took about three minutes. `uv sync` pulled MLX and six other small dependencies. `uv run prepare.py` downloaded eleven training shards from the public HuggingFace dataset and trained a BPE tokenizer in 41 seconds.

Then I did one manual run, as the setup instructions said to: a single 5-minute training experiment to establish a hardware baseline, no modifications.

The first surprise: `val_bpb 1.563`. The public README documents a manual walk on older Apple Silicon that bottomed out at `1.807` after four experiments. My first run, before the AI agent had done anything, was already 13% better than that published best. I didn't tune anything. I pulled the repo and ran it.

The reason is in how the loop is constructed. The training budget is fixed at 5 minutes of wall clock. The M3 Ultra throughput is high enough that it fits 555 optimizer steps into that window, while the older hardware fits fewer. Same code. Different step count. Different result.

The hardware is a parameter, not a constant.

Specs for replication

- Hardware: Mac Studio M3 Ultra, 128 GB unified memory

- OS and runtime: macOS 15, Python 3.12, `uv` 0.10

- Framework: MLX 0.31 with Metal backend (no PyTorch, no CUDA)

- Agent runner: Claude Code (Anthropic)

- Fork used: `github.com/trevin-creator/autoresearch-mlx`

- Per-experiment budget: 5 minutes training, ~90 seconds compile and eval overhead

- Peak unified memory during training: 21.2 GB

Launching the agent overnight

Here's where you have to decide. Karpathy's default advice is to "disable all permissions" and let the agent go. That's the fastest path and it works. But it's also a permission-free Claude Code session running unattended on your Mac for eight hours, with the ability to execute arbitrary shell commands. If the agent hallucinates a destructive action at 3 AM, you won't be there to interrupt it.

I went with a scoped allowlist instead. A `.claude/settings.local.json` file listing exactly the commands the loop actually needs: `uv run train.py`, `git add train.py`, `git commit`, `git reset --hard`, `grep`, `tail`, a few others. Everything else prompts. The agent can't `rm`, can't `git push`, can't install packages, can't touch any file outside the repo.

Then I pointed a fresh Claude Code session at `program.md`, pasted "start the experimentation loop, don't stop," and went to bed.

Share As The Geek Learns

The morning, by the numbers

The morning log:

Comparison to the three overnight runs documented in the public README:

Final `val_bpb` of 1.289 lands below the best documented Apple Silicon overnight result. New territory for the public log.

What the agent actually did

Five phases overnight. Each tells you something.

Phase one: find the big axis. Four experiments in, the agent had halved the batch size three times (1.56, 1.40, 1.39, 1.38), then tried a fourth halving that bounced back to 1.44. The annotation on the discard: "gradient noise." Correct diagnosis. Below a threshold, batch becomes too small for the optimizer to converge inside 5 minutes.

Phase two: schedule tuning, six keeps in a row. The learning-rate schedule was undertuned. The agent walked `WARMDOWN_RATIO` from 0.7 to 1.0, then `WARMUP_RATIO` from 0.02 to 0.2. Every step dropped `val_bpb`. Floor went from 1.38 to 1.34. Biggest easy win of the night, and it was entirely in the schedule.

Phase three: the moment that mattered most. After schedule tuning, the agent retried `TOTAL_BATCH_SIZE = 2^14`. The same configuration it had rejected in phase one. This time it won.

The agent had discovered the thing most humans miss in hyperparameter tuning: the optimal value of one knob depends on the values of all the other knobs. You don't find N independent settings; you find a consistent N-tuple. The only way to find it is to retry earlier-rejected values after each structural change. I've watched human researchers lock in early wins and never revisit them. The agent didn't. It revisited `EMBEDDING_LR` three times over the night, landing at 1.0, then 1.5, then 1.75 across different phases. Each retry, a small win.

Phase four: two structural wins, one line each. `has_ve()` went from alternating-layers-get-Value-Embeddings to all-layers-get-Value-Embeddings, one `return True` replacing a modular-arithmetic expression. `MLP.__call__()` swapped `ReLU²` for `SiLU`, one function call for another. Both character-count-sized changes. Each dropped `val_bpb` by about 0.01.

Phase five: the 37-experiment grind. The agent spent 37 consecutive experiments without a single keep, testing every nearby hyperparameter against the current local minimum. Most humans would have quit and tried a wild leap. The agent didn't. It finished the neighborhood, then found the next structural win. Disciplined exhaustion.

And two catastrophes, both correctly reverted. Tied embeddings came back at `val_bpb 4.29`, three times worse than anything else. The agent annotated it "LR mismatch destroys." Tied embeddings is actually a good idea in general, but incompatible with the differential layer-wise learning rates the architecture uses. The agent reverted in seconds. On another experiment, removing QK-norm after RoPE spiked `val_bpb` to 1.67. Annotation: "massive regression." Reverted. A human would have spent an hour trying to salvage tied embeddings. The agent spent ten seconds on the revert. The revert discipline is the whole game.

What it taught me

Two things crystallized overnight.

Disciplined exhaustion beats creative leaps. Humans get bored. After a few hours on the same hyperparameter axis, we start reaching for something new because the exploration stops feeling productive. The agent doesn't have that pressure. It spent 37 experiments without a win because that's what the local search called for, and then it found the next jump. Most humans couldn't do that. Not because we lack the ability, but because we lack the emotional neutrality. The agent's advantage isn't intelligence. It's the absence of boredom, ego, and social pressure. That isn't a 20× productivity gap. It's a categorical one.

Generation is cheap, evaluation is sacred. Every one of the agent's wins was a one-line diff. So was every catastrophe. The "research" wasn't in writing the code. The research was in the metric's ability to rank one-line diffs instantly and unambiguously. Karpathy's genius isn't the agent. It's `val_bpb` plus a 5-minute budget plus `git reset --hard`. That design slots the agent into exactly what AI is magnitudes better at (generating variants, executing at volume) and leaves the hard part (what to measure) to the human who built the loop.

The loop runs on me too

Here's the thing I can't stop thinking about. The loop the agent ran overnight is structurally identical to the one I'm building for my Stoic practice on the same machine.

Morning intention. Five-minute run. Evening review. Keep or discard. Iterate.

Marcus Aurelius wasn't optimizing `val_bpb`. He was optimizing a harder metric with no closed form. But the shape of the loop is the same. Karpathy designed an overnight research org. Epictetus designed an overnight self. Both are the same thing running in different mediums.

The 118-experiment loop ran on a machine on my desk. The second loop runs on me.

If you have a Mac Studio and a spare evening, the repo is at `github.com/trevin-creator/autoresearch-mlx`. Clone it, run `prepare.py`, point a Claude Code session at `program.md`, go to sleep. You wake up to a log of experiments and a better model. And if you're anything like me, you also wake up thinking about which of your own loops could run this way.

Leave a comment

A Quick AI Glossary For This Article

Because not everyone speaks ML fluently, here’s a plain-English guide to the terms in this post. I’m still learning too, so these are “practitioner” definitions—enough to follow what’s happening, not academic deep-dives.

The Big Picture

GPT. A type of language model. Stands for “Generative Pre-trained Transformer.” In this article I’m training a tiny one from scratch, not using the big ones like ChatGPT. Same architecture family, just much smaller.

Pre-training. The step where a model learns to predict the next word (or “token”) across a huge pile of text. This is what `train.py` is doing. It happens before any of the fine-tuning that turns a base model into a chatbot.

val_bpb (validation bits per byte). The score the agent is optimizing. Lower is better. It’s a measure of how surprised the model is by held-out text it hasn’t seen during training. A model that predicts well has low surprise. Bits per byte is a way of measuring that surprise that works across different tokenizers, so you can compare different architectures fairly.

Loss metric. Any number that tells you how wrong a model is on a given task. Training is the process of making that number go down. `val_bpb` is a loss metric.

The Stack

Apple Silicon. Apple’s own CPU/GPU chip family (M1, M2, M3, M4). Uses unified memory, which means the CPU and GPU share the same pool of RAM instead of having separate memory pools. For AI workloads this is a big deal because you don’t have to copy data between CPU RAM and GPU VRAM.

MLX. Apple’s open-source machine learning framework, built specifically for Apple Silicon. Think of it as Apple’s answer to PyTorch but native to Metal (Apple’s GPU API). No PyTorch, no CUDA, no NVIDIA drivers needed.

PyTorch. The dominant open-source ML framework. Most research code you see online assumes PyTorch. It runs on NVIDIA GPUs (via CUDA) and, with caveats, on Apple GPUs (via MPS). MLX is an alternative that sidesteps PyTorch entirely.

CUDA. NVIDIA’s API for running general-purpose compute on their GPUs. If you’ve ever seen a blog post say “requires a CUDA-capable GPU,” they mean an NVIDIA card.

GPU VRAM. The memory that lives on a GPU card, is separate from your computer’s main RAM. On Apple Silicon, VRAM and main RAM are the same pool (that’s the “unified memory” thing).

Tokenization & Data

Tokenizer. The thing that turns text into numbers the model can actually work with. “Hello world” might become `[15496, 995]`. The model only ever sees the numbers.

BPE (Byte-Pair Encoding). The most common algorithm for building a tokenizer. It starts with individual characters and iteratively merges the most common pairs until you have a vocabulary of “tokens” that balance common words (one token) and rare words (split into pieces).

Shards. Chunks of a large dataset, split into files for parallel download and loading. Our setup uses 11 shards from a public text dataset.

Training Mechanics

Optimizer. The algorithm that actually updates the model’s weights during training. AdamW is the one used here. Every “optimizer step” is one update.

Batch size. How many training examples the model looks at before making one weight update. Bigger batches give smoother gradient estimates but use more memory. Smaller batches fit more weight updates into a fixed time budget.

Gradient accumulation. A trick for getting large effective batch sizes on limited hardware. Process smaller mini-batches sequentially, add up their gradients, then apply one update. `TOTAL_BATCH_SIZE / DEVICE_BATCH_SIZE` tells you how many mini-batches per update.

Gradient noise. When your batch is so small that the gradient estimate becomes statistically unreliable. The optimizer starts jerking around instead of smoothly descending, and training slows or stalls. The agent correctly identified this as the failure mode at batch 2^12.

Learning rate (LR). How big a step the optimizer takes each update. Too high, and training blows up. Too low, and it barely progresses. The sweet spot depends on everything else.

Learning rate schedule. How the learning rate changes over time. Typically: warm up from zero to peak, cruise, then warm down to zero. `WARMUP_RATIO = 0.3` means the first 30% of training is the warm-up.

Differential / layer-wise learning rates. Using different learning rates for different parts of the model. In the nightshift setup, the embedding layer gets LR 1.75, but the output projection (`lm_head`) gets 0.006 — a 290× difference. This matters because different parameter types have very different sensitivities.

Architecture Pieces

Attention (or attention layer). The core mechanism that lets a transformer model “pay attention to” relevant earlier tokens when predicting the next one. Modern LLMs are mostly stacks of attention layers alternating with MLPs.

MLP (multi-layer perceptron). A simple feed-forward neural network with one or two hidden layers. In a transformer, an MLP sits between each pair of attention layers and does the “thinking” on the representations attention produced.

Activation function. A nonlinear function applied inside a neural net. Without activations, no matter how many layers you stack, the whole thing collapses mathematically into one linear transformation. Examples in this article: `ReLU²` and `SiLU`.

SiLU (Sigmoid Linear Unit). `x * sigmoid(x)`. A smooth, differentiable activation function. Also called Swish. Used in many modern models because it plays nicely with optimizers.

ReLU² (squared ReLU). `max(x, 0) ** 2`. The piece that nanoGPT-speedrun and some research codebases use. Produces sparse, squared activations. Theoretically expressive but less numerically stable than SiLU for short training runs — which is why SiLU won overnight.

Embedding. The lookup table that converts each input token (a number) into a vector of real numbers. The model learns what each vector should be during training. `wte` = word token embedding.

Value Embeddings (VE). An additional set of embeddings injected into attention layers as the “value” vectors. Think of them as a skip connection from the raw input that every attention layer can consult, on top of what the previous layer produced. Helps information flow when the network is deep.

Tied embeddings. Sharing the input embedding weights with the output projection weights (the thing that produces final logits). Saves millions of parameters. Commonly used in GPT-2 and many others. Broke catastrophically in our run because the differential learning rate setup couldn’t handle the shared weight.

QK-norm (Query-Key normalization). A stabilization trick: normalize the query and key vectors inside attention before computing attention scores. Without it, score magnitudes can spike, saturating the softmax. The agent tried removing QK-norm and `val_bpb` jumped 28% worse.

RoPE (Rotary Position Embedding). How the model knows the order of tokens. Rotates the query and key vectors by an angle that depends on the token’s position. Standard in modern transformers.

Softmax. The function that turns raw attention scores into a probability distribution over the tokens you might attend to. Highly peaked inputs cause “softmax saturation” — most of the weight collapses onto one token and gradients downstream get weak. That’s why QK-norm matters.

Methodology

Hyperparameter. Any configuration value you set *before* training, as opposed to weights the model learns *during* training. Batch size, learning rate, WARMUP_RATIO, depth—all hyperparameters.

Hyperparameter tuning. The art (and mostly the grind) of finding good hyperparameter values. Most of what the agent did overnight was hyperparameter tuning.

Interaction effect. When the optimal value of hyperparameter A changes depending on what hyperparameter B is set to. A consistent set of hyperparameters is not N independent optima — it’s one N-tuple.

Local search. A research strategy: after finding an improvement, test every nearby variation of your current best before venturing somewhere completely different. Tedious for humans. Perfect for agents that don’t get bored.

If I missed a term you’d have liked defined, please let me know in the comments and I’ll add it.

Then someone asked the obvious next question: "Can you point it at our Confluence? And Notion? And the Google Drive?"

Suddenly self-hosted isn't free anymore. It's a part-time job—PDF parsing, OCR, re-indexing schedules, dealing with 50-page slide decks where the first 20 pages are a title card. The embedding pipeline that was elegant for 20 markdown articles starts to sweat when you throw a 400-page SOC 2 audit at it.

So here's the question I had to actually answer for myself: when does paying Cloudflare, AWS, or Pinecone actually beat running your own stack?

I spent a research pass comparing the live services. Here's what I found.

TL;DR

Self-host when content is static, under about a thousand docs, single source, you control ingestion cadence, and privacy or cost-per-query matters more than your time.

Hosted when: multiple unstructured sources, frequent re-indexing, non-engineers uploading docs, you need SLAs, or you're shipping this to customers.

Hybrid is increasingly common: hosted RAG for the customer-facing product, self-hosted for internal dogfooding and dev. The two aren't mutually exclusive.

The Contenders

Five options worth your attention. One paragraph each.

Cloudflare AI Search (AutoRAG)

The newest entrant, currently in open beta. Cloudflare stitched together R2 for storage, Vectorize for embeddings, and Workers AI for inference, then wrapped the whole thing in a management API. Strongest pitch: near-zero config, pay-as-you-go, and an official MCP server ships with it. Weakest point: retrieval is vector-first. Cloudflare added optional reranking in October 2025, but there's still no published BM25 or hybrid-search path as of this writing. If your corpus is well-structured, you probably won't notice. If you're indexing messy enterprise content, you will.

AWS Bedrock Knowledge Bases

The enterprise default if you're already on AWS. Hybrid search (vector + BM25) is built in, Cohere reranking is available, and chunking modes range from fixed-size to semantic to custom Lambda. Titan V2 embeddings run at $0.02 per million tokens. There's an official AWS Labs MCP server for retrieval. And then there's the OCU landmine—which I'll get to in a minute, because it deserves its own sidebar.

Pinecone Assistants

Best-in-class retrieval, managed. Hybrid sparse-dense search with automatic reranking, configurable alpha weighting, managed embeddings abstracted away from you, and an official remote MCP server. Pricing is fully usage-based—$5 per million context retrieval tokens, plus input/output token, storage, and ingestion charges on top. The Standard plan has a $50/month minimum; the old $0.05/assistant-hour fee was removed. Free tier is real but tight—5 assistants per project, 1 GB storage, 500k input tokens, and 500k context retrieval tokens per month. Past that you're paying, but the retrieval quality is noticeably better than anything else on this list.

LlamaCloud

Managed LlamaIndex. Multimodal parsing that actually handles diagrams, configurable chunking modes, hybrid retrieval, reranking. The free tier gives you 10,000 credits a month—about a thousand pages. Paid tiers start at $50/month (Starter, 40K credits) and scale to $500/month (Pro, 400K credits). For a LlamaIndex-native team, the Starter tier is genuinely cheap; Pro is where the platform pays off. LlamaIndex ships `run-llama/llamacloud-mcp` (Python) and `run-llama/mcp-server-llamacloud` (TypeScript), plus a hosted gatway at mcp.llamaindex.aithe MCP story is actually stronger here than I initially realized.

Self-Hosted (sqlite-vec + Ollama)

This is what the ASTGL Knowledge MCP server actually runs on. sqlite-vec for vectors, FTS5 for keyword search (that's your hybrid search right there, no cloud required), and Ollama serving nomic-embed-text for embeddings, all of it on a $10/month Hetzner VPS or a Mac mini on my desk. Works well for up to around a million vectors in my testing. Real cost: infrastructure plus your time. The second one is the variable.

The Six Axes That Actually Matter

Pricing gets the attention, but it’s rarely the deciding factor. Here’s what I look at:

Share

Setup cost

Time-to-first-query is where hosted services actually earn their money. Pinecone Assistants and Cloudflare AI Search will have you chatting with your docs in under a minute after signup—upload and go. Bedrock is the outlier on the hosted side: AWS documentation puts CloudFormation infrastructure deployment at 7–10 minutes, with a full hand-wired setup typically landing at 20–30 minutes. That's hosted pricing with self-hosted-ish friction.

Self-hosted with sqlite-vec and Ollama is about 30 minutes from `apt install` to first working query if you know what you're doing, longer if you're learning. For me it's fast because I've done it. For someone new to local LLMs it's a weekend.

Ongoing cost

This is where the story flips. For a small corpus with low query volume—think a few hundred docs and a few thousand queries a month—Cloudflare AI Search is genuinely cheap, maybe $5–15/month in storage and API costs. Pinecone Assistants sits at $20–50 in that range. Bedrock KB looks innocent until you hit the OCU minimum (more on that below). LlamaCloud's $50/month Starter floor is reasonable; the $500/month Pro tier is where the platform pays off at real scale.

Self-hosted is $10/month for a Hetzner VPS, flat. Mac mini on your desk? $0/month plus electricity. The per-query cost of hosted RAG is the thing that compounds when you scale—or when someone builds something that hammers it.

Ingestion complexity

This is the axis where hosted services earn their keep without argument. Bedrock KB and LlamaCloud both handle PDFs with embedded tables, Word docs, and (in LlamaCloud's case) actual diagrams, not just the text around them. Bedrock's Data Automation service charges $0.010 per page for parsing—not free, but a lot cheaper than writing your own PDF extractor.

Self-hosted with Ollama and sqlite-vec doesn't ship with any of that. If your corpus is markdown, you're fine. If it's a pile of PDFs from your legal team, you're either writing parsers or paying someone to.

Retrieval quality

All four hosted services offer hybrid retrieval except Cloudflare AI Search, which is vector-only as of this writing. Pinecone Assistants has automatic reranking baked in. Bedrock KB has optional Cohere reranking. Self-hosted with sqlite-vec can do hybrid via FTS5 for keyword matching combined with vector similarity, which is genuinely good—but you're the one writing the ranking logic.

For most queries on well-structured content, vector-only is fine. For ambiguous queries over messy content, reranking earns its cost.

Data residency

Self-hosted wins this one by default. The data never leaves your machine.

On the hosted side: Pinecone has US and EU regions with a DPA, and LlamaCloud has SOC 2 Type II and HIPAA. Bedrock's EU region support has been inconsistent in 2026 documentation—verify before you commit. Cloudflare's Data Localization Suite handles this at the platform level.

If you're in a regulated industry, audit the provider before you pick. Don't trust the marketing page.

Ops burden

This is the one nobody advertises. Self-hosted means you're responsible for:

• Keeping Ollama updated

• Monitoring embedding drift when you upgrade models

• Backing up knowledge.db

• Scheduling re-indexing when source content changes

• Debugging why sqlite-vec suddenly returns zero results (hint: usually the embedding model changed dimensions)

Hosted services handle all of that. That's most of what you're paying for.

Sidebar: The Bedrock OCU Landmine

Bedrock Knowledge Bases advertises "no charge for the Knowledge Bases feature itself." Technically true. What they don't mention on the pricing page is that the vector storage layer requires a minimum of 2 OCUs—OpenSearch Compute Units—at roughly $0.24/hour each.

Do the math: 2 OCUs × $0.24/hour × 730 hours/month = about $350 per month whether your knowledge base has 10 documents or 10 million.

Nobody else on this list has a fixed cost floor like that. Cloudflare AI Search scales down to pennies. Pinecone Assistants has a real free tier. Self-hosted is $10.

If you're building something small and you're not already deep in AWS—Bedrock KB is the wrong answer. If you're running enterprise-scale search over millions of docs, that $350 becomes a rounding error, and the hybrid+rerank features earn their keep.

Know where you sit before you commit.

The MCP Angle

Here's the thing I didn't expect to find: every production RAG service on this list ships an official MCP server. Cloudflare, Bedrock, Pinecone, LlamaCloud—all of them. This went from "experimental" to "table stakes" over the past year.

• Cloudflare AI Search → The official Cloudflare MCP server exposes AI Search endpoints

• Bedrock KB → AWS Labs ships `bedrock-kb-retrieval-mcp-server`

• Pinecone Assistants → Each assistant gets its own remote MCP endpoint, plus a local Docker option

• LlamaCloud → `run-llama/llamacloud-mcp` plus the hosted MCP Gateway at mcp.llamaindex.ai

This wasn't true a year ago. The MCP ecosystem has absorbed the big RAG providers fast enough that "hosted RAG you can query from Claude Desktop" is now a checkbox feature.

Self-hosted doesn't ship with an MCP server—but wrapping one around your sqlite-vec database is a weekend of TypeScript. That's what the ASTGL Knowledge MCP server actually is: an MCP wrapper around vector search and Q&A retrieval over a SQLite database. The MCP part is trivial. The content curation and ingestion pipeline is 90% of the work.

The real insight: hosted RAG plus MCP wrapper is the modern middle path. You don't have to pick pure self-hosted or pure managed. Point a custom MCP server at Pinecone Assistants or Bedrock KB, and you get the retrieval quality of managed services with the MCP-native interface your agents expect. The `cloudflare/ai-search` MCP server does exactly this.

That changes the decision. It's not "hosted vs. self-hosted RAG" anymore. It's "Whose retrieval layer do I want behind my MCP server?"

Decision Framework

Enough philosophy. Here's the checklist I use.

1. Is your corpus under 500 docs and mostly static? Self-host. You'll spend more time reading hosted RAG docs than it would take to `npm install sqlite-vec`.

2. Do you have under 20 hours to ship this? Hosted. Pinecone Assistants or Cloudflare AI Search will get you to a demo faster than you can read the Bedrock IAM setup guide.

3. Are you charging money for this? Either hosted (you need the SLA) or self-hosted with a real infra budget and a pager rotation. Don't split the difference on production.

4. Is any of this data regulated—PHI, PII under GDPR, or financial? Self-host, or audit the hosted provider's compliance posture before you upload anything. Don't trust the marketing page. Ask for the SOC 2 report.

5. Are you already in AWS? Bedrock KB makes sense if your scale justifies the OCU floor. Otherwise, Pinecone.

6. Everything else? Prototype self-hosted with sqlite-vec. Migrate to hosted when a specific pain point forces the move. "We keep hitting embedding model drift" is a real reason. "It seems complicated" isn't.

The rule of thumb I use: pay for what hurts, self-host what you enjoy. If PDF parsing makes you want to quit, pay Bedrock or LlamaCloud. If SQL and vector search are fun, keep sqlite-vec.

What I'd Actually Build in 2026

If you asked me right now, for real scenarios:

Weekend side project. sqlite-vec plus Ollama plus nomic-embed-text. Runs on a laptop, costs nothing, and teaches you how RAG actually works. This is where I'd start every time.

Customer-facing SaaS feature. Cloudflare AI Search. Pay-per-query pricing means your costs track your usage. Official MCP server means Claude Desktop users can plug in directly. The open-beta caveat is real—verify the SLA matches your product's uptime needs before launch.

Enterprise RAG over thousands of internal docs. Bedrock Knowledge Bases if you're already in AWS and you'll comfortably exceed the OCU floor. Pinecone Assistants if you're not. LlamaCloud if your team is already deep in LlamaIndex and the multimodal parsing earns its cost. All three have hybrid search; all three ship MCP servers. Pick based on where your infrastructure—and your team's existing expertise—already lives.

Team knowledge base. Self-hosted if it's under five people and you've got one engineer who cares about it. Hosted the moment it crosses twenty users or someone non-technical needs to upload docs. The threshold isn't the document count—it's the human factor.

The sqlite-vec era isn't ending. It's just not the only answer anymore. A year ago, self-hosted was the serious choice, and hosted was for people who didn't want to learn. In 2026, that framing doesn't hold. Hosted RAG is production-ready, MCP-native, and sometimes cheaper than your own ops time.

Pick the tool that matches the job. That's it.

FAQ

What is Cloudflare AI Search?

Cloudflare AI Search (formerly AutoRAG) is a managed Retrieval-Augmented Generation service built on Cloudflare's platform. It combines R2 storage, Vectorize for embeddings, and Workers AI for inference into a single API. It's currently in open beta with vector-first retrieval and optional reranking, and ships with an official MCP server that lets Claude and other AI assistants query your indexed documents directly.

When should I use hosted RAG instead of sqlite-vec for an MCP server?

Use hosted RAG when your corpus exceeds a few thousand documents, you're ingesting multiple source types like PDFs or Word docs, non-engineers need to upload content, or you need a production SLA. Stick with sqlite-vec when the corpus is static markdown under about 1,000 documents, you control ingestion, and cost-per-query matters more than ops time.

Can I use the Cloudflare AI Search MCP with Claude Desktop?

Yes. Cloudflare ships an official MCP server that exposes AI Search endpoints as MCP tools. Add the Cloudflare MCP server to your Claude Desktop config, provide your API token, and Claude can query your indexed documents through the same interface it uses for any other MCP tool. The setup is documented in the Cloudflare MCP repository.

Leave a comment

• Related reading:*

• How I Shipped an MCP Knowledge Server in a Weekend: the self-hosted case study this article references

• How Do MCP Registries Work (Smithery, mcpt)?: finding MCP servers, including the ones in this article

• Cortex: An Event-Sourced Memory Architecture for AI Coding Assistants: related exploration of the memory/retrieval landscape

Here's where the ecosystem is heading, what's changing, and what it means for anyone building with AI tools today.

The Short Answer

MCP is becoming the standard way AI connects to tools. The next 18 months will bring better security, larger registries, enterprise adoption, and a shift toward local-first AI architectures. If you're building skills in this space now, you're ahead of the curve.

| Trend | 2025 | 2026 (Now) | 2027 (Projected) |

|-------|------|------------|-------------------|

| Registry size | ~500 servers | 5,000+ servers | 20,000+ servers |

| Enterprise adoption | Early experiments | Production pilots | Standard infrastructure |

| Local AI quality | Usable for simple tasks | Competitive for most tasks | Near-parity for 90% of use cases |

| Protocol maturity | v1 basics | Auth, streaming, security | Full enterprise feature set |

| Developer tooling | Manual, rough | SDKs in multiple languages | IDE-integrated, visual builders |

Trend 1: The Local-First AI Shift

The most significant trend in AI infrastructure isn't a new model—it's where models run.

What's Happening

Open-source models are improving at a staggering pace. Gemma 4, Qwen 3, Llama 3.3, and their successors close the gap with cloud models every quarter. A 26B parameter model running on a Mac Studio today outperforms cloud GPT-4 from 18 months ago.

This changes the economics. When local models handle 90% of tasks at zero marginal cost, the question shifts from "should I use AI?" to "should I pay for cloud AI when local works?"

What This Means for MCP

Local AI + MCP servers = fully autonomous local automation. No cloud dependency. No API costs. No data leaving your machine. The stack is:

• Ollama → Local model serving

• MCP servers → Tool integration

• Gateway (OpenClaw, n8n) → Orchestration

• Local storage → Data and knowledge

This stack runs on consumer hardware. A Mac Mini with 32 GB handles it. This is enterprise-grade automation on a consumer budget.

The Prediction

By 2027, running a personal AI stack locally will be as common as running a home media server is today. The early adopters are doing it now. The mainstream follows when setup becomes one-click.

Trend 2: Registry Maturation

From Wild West to App Store

Current MCP registries are like the early npm ecosystem—anyone can publish anything, quality varies wildly, and discovery is hit-or-miss. That's changing.

What's coming:

• Verified publishers—Registries will distinguish between official, verified, and community servers

• Security scanning—Automated analysis of server code for vulnerabilities and suspicious behavior

• Dependency management—Tools to manage, update, and audit all installed MCP servers

• Usage analytics—Data on which servers are most used, most reliable, most maintained

• Compatibility testing—Verified compatibility with specific AI clients (Claude, VS Code, etc.)

The Consolidation Question

Will one registry dominate? Probably not in the npm-monopoly sense. More likely:

• Smithery stays the largest general-purpose registry

• mcpt establishes the quality-curated niche

• Platform-specific registries emerge (VS Code marketplace, Claude's built-in catalog)

• Enterprise registries appear for internal MCP server management

The Prediction

By 2027, installing an MCP server will feel like installing a browser extension. Browse, click install, authenticate, done. The manual JSON editing of today will be a historical footnote.

Trend 3: Protocol Evolution

What MCP Gets Right Today

• Simplicity—The client-server model is easy to understand and implement

• Language agnostic—Servers can be built in any language

• Tool abstraction—AI sees tools, not implementation details

• Local-first—Servers run on your machine by default

What's Coming

Authentication and Security

Current MCP servers handle auth inconsistently. The protocol will standardize:

• OAuth 2.0 integration for services that need it

• Fine-grained permission scoping (read vs. write, specific resources)

• Credential management (secure storage, rotation)

• Audit logging (who accessed what, when)

Streaming and Real-Time Data

Today's MCP is mostly request-response. Future versions will support:

• Event streams (new email arrives, calendar changes, file modified)

• WebSocket-based persistent connections

• Real-time monitoring and dashboards

Multi-Modal Support

Current MCP tools primarily handle text. Expanding to:

• Vision tools (analyze images, screenshots, documents)

• Audio tools (transcription, speech synthesis)

• Video tools (clip extraction, analysis)

• Document tools (PDF processing, spreadsheet manipulation)

Server-to-Server Communication

Enabling MCP servers to call each other:

• A calendar server queries a contacts server to enrich meeting attendee data

• A research server calls a web search server to fetch sources

• Composable server chains without client involvement

The Prediction

MCP 2.0 (or equivalent major version) will land by mid-2027 with standardized auth, streaming, and multi-modal support. The protocol will feel complete rather than minimal.

Trend 4: Enterprise Adoption

The Enterprise AI Problem

Large organizations want AI automation but face:

• Security concerns—Data can't leave the corporate network

• Compliance requirements—audit trails, access controls, data residency

• Integration complexity—Hundreds of internal tools, custom APIs, legacy systems

• Governance—Who approves which AI can access what?

How MCP Solves This

MCP's local-first architecture is inherently enterprise-friendly:

• Servers run inside the network—data stays on-premises

• Per-server permissions—Each server accesses only what's allowed

• Standard protocol—one integration pattern for all tools

• Audit capability — All tool calls are loggable

What's Coming

• Enterprise MCP platforms—Companies like Cloudflare, AWS, and Azure offering managed MCP infrastructure

• Internal MCP registries—Corporate app stores for approved MCP servers

• Policy engines—Centralized rules for which AI can use which tools, when, with what data

• SOC 2 / HIPAA compliant servers—Certified MCP servers for regulated industries

The Prediction

By late 2027, enterprise MCP infrastructure will be a recognized market category, similar to how API gateways became standard enterprise infrastructure.

Trend 5: The Knowledge Server Pattern

Beyond Tool Servers

Most MCP servers today are tool servers—they do things (send email, search web, manage files). A growing pattern is knowledge servers—they know things.

A knowledge server exposes structured information that AI can query:

• Company knowledge base

• Product documentation

• FAQ databases

• Research libraries

• Personal notes and archives

Why This Matters

When AI can query your knowledge directly, it answers from your data—not its training data. This means:

• Answers grounded in your actual documentation

• No hallucination about your specific products or processes

• Always current (the knowledge server reads live data)

• Personalized to your context

The Example: mcp-astgl-knowledge

This is what I'm building—an MCP server that indexes all 20 articles in this series and makes them queryable by any AI client.

Tools it will expose:

• `search_answers` — Semantic search across all articles

• `get_answer` — Retrieve a specific article by topic

• `list_topics` — Browse all available topics

• `get_faq` — Pull FAQ entries for specific questions

How it works:

• Articles parsed from markdown (frontmatter + body)

• Embeddings generated via local Ollama (nomic-embed-text)

• Stored in SQLite with sqlite-vss for vector search

• Served as an MCP server that any AI client can connect to

When someone asks Claude "What's the best local LLM for coding?" and this server is connected, Claude queries the knowledge base and answers with information from article 12—not from its training data, which might be outdated.

The Prediction

Knowledge servers will be the fastest-growing MCP server category in 2027. Every company with documentation, every creator with a content library, every expert with a knowledge base will want one.

What This Means for You

If You're a Developer

Now: Learn the MCP SDK, build a server, publish it. The ecosystem rewards early builders—servers published now accumulate installs and reputation.

Next 12 months: Expect demand for custom MCP servers at companies integrating AI. MCP development will become a marketable skill alongside API development.

Key skill: Understanding how AI agents use tools. The protocol is simple—the design of good tools is the hard part.

If You're a Business Owner

Now: Connect MCP servers to Claude for immediate productivity gains. Start with email, calendar, and file access. Automate one workflow.

Next 12 months: Evaluate local AI infrastructure for privacy and cost benefits. Budget for hardware that pays for itself in reduced API costs.

Key opportunity: Businesses that adopt AI automation now will have 12-18 months of compounding efficiency gains over competitors who wait.

If You're an Individual User

Now: Set up Claude Desktop with 2-3 MCP servers. Experience the difference between chatbot AI and tool-connected AI.

Next 12 months: Consider a local AI setup (Ollama on existing hardware or a Mac Mini). Automate your most repetitive tasks.

Key realization: AI connected to your tools is dramatically more useful than AI in a chat window. MCP servers are what make that connection possible.

How I Actually Do This

I've been building in this ecosystem for over a year. Here's what the trajectory looks like from the inside:

What I'm Building Next

mcp-astgl-knowledge—The knowledge server I mentioned above. It's the capstone of this article series: 20 articles become a queryable knowledge base that any AI can access.

The plan:

1. Build with TypeScript + @modelcontextprotocol/sdk

2. Index all 20 articles with local embeddings

3. Publish to npm

4. Register on Smithery and mcpt

5. Share the build process as an ASTGL tutorial

This is the pattern I believe will explode: experts building knowledge servers that make their expertise available to AI systems.

What I've Observed

1. The tooling is getting better fast. Building an MCP server in early 2025 required reading the spec and figuring things out. In 2026, the SDK handles most of the boilerplate and registries provide distribution.

2. Local model quality jumped significantly. Gemma 4 was a step change. Tasks that needed cloud models a year ago now run locally at comparable quality. The gap keeps narrowing.

3. The automation compound effect is real. My first automation saved 30 minutes per day. Twenty-six automations save hours. Each new automation builds on the infrastructure of previous ones. The marginal cost of the 27th automation is near zero.

4. Community momentum is accelerating. The number of MCP servers, tools, and tutorials appearing weekly is orders of magnitude higher than a year ago. This is the network effect in action.

5. The biggest barrier is awareness, not technology. Most people who would benefit enormously from MCP servers don't know they exist. That's why I wrote this series—and why I'm building a knowledge server to make the information accessible.

The 18-Month Outlook

| Quarter | What to Expect |

|---------|---------------|

| Q2 2026 (now) | Local models competitive for 85% of tasks. MCP registries at 5,000+ servers. |

| Q3 2026 | Enterprise MCP pilots at major companies. Visual workflow builders support MCP natively. |

| Q4 2026 | MCP auth standardization lands. Knowledge servers emerge as a category. |

| Q1 2027 | Local models reach 90%+ parity for common tasks. MCP registries pass 15,000 servers. |

| Q2 2027 | Enterprise MCP platforms from major cloud providers. One-click server installation standard. |

Frequently Asked Questions

Will MCP be replaced by a competing standard?

Unlikely in the near term. MCP has strong momentum, broad adoption, and backing from Anthropic with buy-in from Microsoft and Google. Standards wars are possible, but MCP's open protocol design and existing ecosystem make it the safe bet for building today.

What if I invest in MCP and it becomes obsolete?

The skills transfer. Understanding tool integration, agent patterns, and local AI architecture is valuable regardless of the specific protocol. If a successor to MCP emerges, it will solve the same problems in a similar way, and your experience will translate directly.

Are local models improving fast enough to matter?

Yes. The improvement curve for open-source models is steep. Every 6-12 months brings a significant quality jump. Hardware you buy today runs better models next year—your investment appreciates in capability over time.

When should I start building with MCP?

Now. The ecosystem is mature enough for production use but early enough that builders and early adopters have significant advantages. Every month you wait is a month of compounding automation benefits you don't capture.

What's the single most important thing to do today?

Connect one MCP server to Claude and use it for one real task. That first experience—seeing AI interact with your actual tools instead of just your text—changes how you think about what AI can do. Everything else follows from that realization.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*

If you've already automated a few tasks and want to level up, this is your guide.

The Short Answer

Agent workflows combine AI reasoning with tool access and scheduling to complete multi-step tasks autonomously. The architecture ranges from simple (one agent, one task) to complex (multiple agents coordinating on a pipeline).

| Complexity | Architecture | Example |

|-----------|-------------|---------|

| Simple | One agent, one task, scheduled | Morning briefing at 6:30 AM |

| Chained | Multiple steps, sequential | Research → Draft → Edit → Publish |

| Parallel | Multiple agents, simultaneous | 5 news sources searched concurrently |

| Orchestrated | Coordinator + specialist agents | Content council with 5 roles |

Workflow Patterns

Pattern 1: Scheduled Single-Agent

The simplest useful workflow. One agent runs one task on a schedule.

[Schedule] → [Agent + Tools] → [Output + Delivery]

Example: Daily security audit

• Schedule: Saturday 8:00 AM

• Agent: Gemma 4 31B with filesystem MCP

• Task: Read all config files, check for common misconfigurations, compare against best practices

• Output: Audit report delivered to Discord

When to use: Any standalone task that repeats on a schedule and benefits from AI reasoning.

Pattern 2: Sequential Chain

Multiple steps execute in order, each feeding into the next.

[Step 1: Research] → [Step 2: Draft] → [Step 3: Edit] → [Step 4: Publish]

Example: Content creation pipeline

• Step 1: SCOUT agent searches for trending topics, produces research brief

• Step 2: QUILL agent writes article from research brief

• Step 3: LEDGER agent fact-checks article against sources

• Step 4: MAVEN agent generates distribution pieces

When to use: Tasks with natural stages where each stage's output becomes the next stage's input.

Pattern 3: Fan-Out / Fan-In

One task spawns multiple parallel tasks, results are collected and synthesized.

→ [Agent A: Source 1] →
[Dispatch] → [Agent B: Source 2] → [Collect + Synthesize]
            → [Agent C: Source 3] →

Example: Competitive research

• Dispatch: "Research these 5 competitors"

• 5 parallel agents each research one competitor

• Collector synthesizes all 5 reports into a single competitive brief

When to use: Tasks that can be decomposed into independent subtasks, where parallelism saves time.

Pattern 4: Router + Specialists

A lightweight router examines each incoming task and dispatches it to the best specialist.

[Input] → [Router] → [Specialist A (code)]
                   → [Specialist B (writing)]
                   → [Specialist C (research)]
                   → [Specialist D (triage)]

Example: Notification processing

• Router: Gemma 4 e4B classifies incoming notifications (fast, cheap)

• Critical → Immediate Discord alert

• Important → Queue for hourly batch

• Routine → Queue for 3-hour digest

• Spam → Discard and log

When to use: High-volume inputs that need different handling based on content or urgency.

Pattern 5: Multi-Agent Council

Multiple specialized agents collaborate on a complex task, each contributing their expertise.

[SCOUT] → findings → [FORGE] → outline → [QUILL] → draft → [LEDGER] → verified → [MAVEN] → published
                                                         ↑                              |
                                                         └──── revision request ────────┘

Example: Content production council (my actual setup)

• SCOUT: Research and topic discovery

• FORGE: Structure and outlining

• QUILL: Drafting with voice profile

• LEDGER: Fact-checking and validation

• MAVEN: SEO, distribution, and publishing

Agents can request revisions from earlier agents—LEDGER can send a draft back to QUILL if facts don't check out.

When to use: Complex, multi-faceted work where specialized expertise improves quality.

Building a Workflow: Step by Step

Let's build a real workflow from scratch—a weekly competitive intelligence report.

Step 1: Define the Goal

"Every Monday at 7 AM, research the top 5 competitors in my space, summarize their recent activity, identify notable changes, and deliver a structured report to Discord."

Step 2: Choose the Architecture

This is a fan-out/fan-in pattern:

• Fan-out: Research 5 competitors in parallel

• Fan-in: Synthesize into one report

Step 3: Design the Agents

Research Agent (runs 5 times, once per competitor):

• Model: Gemma 4 26B

• Tools: Web search MCP server

• Input: Competitor name + website

• Output: Structured findings (recent blog posts, product changes, social mentions, job postings)

Synthesis Agent (runs once):

• Model: Gemma 4 26B

• Tools: Filesystem MCP (to save the report)

• Input: All 5 research outputs

• Output: Formatted competitive brief with highlights, threats, and opportunities

Delivery Agent:

• Input: Final report

• Output: Discord message with report content

Step 4: Define the Schedule

# Cron expression: Every Monday at 7:00 AM
0 7 * * 1

Step 5: Build Error Handling

| Failure | Handling |

|---------|---------|

| Web search fails for one competitor | Skip that competitor, note in report |

| Model times out | Retry once, then use smaller model as fallback |

| All searches fail | Alert human, skip this week's report |

| Discord delivery fails | Save report to file, alert via email |

Step 6: Add Logging

Every agent execution logs:

• Timestamp

• Input received

• Tools called and their responses

• Output generated

• Execution time

• Any errors or retries

Step 7: Test and Iterate

Run the workflow manually first. Review the output. Adjust prompts, model choice, and error handling based on real results. Only schedule it after 3 successful manual runs.

Orchestration Tools

OpenClaw (Local Gateway)

OpenClaw is a local AI gateway that manages model routing, task scheduling, and tool execution.

Strengths:

• Runs entirely locally—no cloud dependency

• Routes tasks to appropriate models based on complexity

• Manages MCP server connections

• Built-in scheduling and delivery (Discord, Slack, email)

• Logging and monitoring

Best for: Users who want full local control over their agent workflows.

n8n (Visual Workflow Builder)

n8n provides a visual drag-and-drop interface for building workflows.

Strengths:

• No-code visual builder

• Hundreds of pre-built integrations

• Self-hostable (runs on your machine)

• Supports webhooks, schedules, and event triggers

Best for: Non-developers who want automation without writing code.

Cron + Scripts (DIY)

The simplest orchestration: cron jobs that run scripts calling the Ollama API.

Strengths:

• Zero additional software

• Works on any Unix system

• Complete control

• No abstraction overhead

Best for: Developers comfortable with bash scripting who want minimal dependencies.

Claude Agent SDK (Custom Code)

Anthropic's SDK for building custom agent logic in Python or TypeScript.

Strengths:

• Full programmatic control

• Access to Claude's tool-use capabilities

• Complex agent logic (loops, conditionals, multi-turn)

• Production-grade error handling

Best for: Developers building sophisticated custom agents.

How I Actually Do This

My workflow orchestration runs through OpenClaw on a Mac Studio. Here's the production architecture:

The Orchestration Layer

OpenClaw Gateway
├── Schedule Manager (cron-like)
├── Model Router (triage → specialist)
├── MCP Connector (15+ servers)
├── Delivery Manager (Discord, file system)
└── Log Aggregator

Daily Workflow Map

| Time | Workflow | Pattern | Agents |

|------|---------|---------|--------|

| 6:00 AM | Research pipeline | Fan-out/fan-in | 5 source agents + 1 synthesizer |

| 6:15 AM | Log review | Single agent | 1 analyst agent |

| 6:30 AM | Morning briefing | Sequential chain | Calendar → Email → Tasks → News → Synthesizer |

| 7:00 AM | Content research | Fan-out/fan-in | 3 niche agents + 1 trend analyzer |

| Every 5 min | Critical alerts | Router + specialist | Router → Discord delivery |

| Every hour | Notification batch | Router + collector | Router → Batch → Discord |

| 8:00 PM | Evening summary | Sequential chain | Activity log → Synthesizer → Discord |

| 8:30 PM | KB builder | Single agent | Knowledge base agent |

Multi-Agent Council Integration

The ACA Council (SCOUT/FORGE/QUILL/LEDGER/MAVEN) runs as an orchestrated multi-agent workflow:

1. Morning meeting (7 AM): SCOUT presents topic research, council prioritizes

2. Production cycle: Sequential chain through all 5 agents

3. Evening meeting (8 PM): Review completed articles, queue for publishing

4. Publishing: Automated sync to site, Substack, and social channels

Paperclip Integration

Paperclip (a separate agent management platform) provides additional orchestration for agents that need web-based interfaces and team collaboration. It runs alongside OpenClaw—some workflows use OpenClaw's local scheduling, others use Paperclip's cloud features.

The key insight: you don't need one orchestration tool. Different workflows have different needs. Simple schedules use cron. Complex pipelines use OpenClaw. Team-visible workflows use Paperclip.

Lessons from Production

1. Start with single-agent workflows. Get one agent reliable before adding coordination complexity. My first 10 workflows were all single-agent scheduled tasks.

2. The router pattern is the highest-leverage addition. Adding a triage router that classifies incoming work and dispatches to the right model immediately improved quality and speed across all workflows.

3. Logging saved me dozens of hours. When an agent produces bad output, logs show exactly what happened. Without logs, you're guessing. I log every tool call, every model response, every delivery.

4. Agents need guardrails, not just goals. "Research competitors" is too vague. "Search for blog posts published in the last 7 days from these 5 domains, extract titles and summaries, skip anything older than 7 days" — that produces reliable results.

5. Schedule slack prevents cascading failures. My 6:00 AM research pipeline sometimes takes 25 minutes. The 6:30 AM briefing doesn't depend on it—theyf run independently. Dependent workflows have explicit wait conditions, not just time offsets.

Monitoring and Maintenance

What to Monitor

| Metric | Why It Matters | Alert Threshold |

|--------|---------------|----------------|

| Execution time | Detect slowdowns before they cascade | >2x normal duration |

| Error rate | Catch model or tool failures | >10% of executions |

| Output quality | Detect model drift or prompt degradation | Spot-check weekly |

| Token usage | Track resource consumption | Unexpected spikes |

| Tool call failures | MCP server or API issues | Any persistent failure |

Weekly Maintenance

• Review error logs—fix recurring issues

• Spot-check 2-3 outputs per workflow for quality

• Update models if new versions improve quality

• Review and trim logs (they grow fast)

• Check MCP server updates

Frequently Asked Questions

How many agent workflows can I run simultaneously?

Depends on your hardware and model sizes. A Mac Mini with 32 GB comfortably runs 3-5 concurrent lightweight workflows. A Mac Studio with 192+ GB runs 20+ concurrent workflows across multiple models. The bottleneck is usually model memory, not CPU.

Can agent workflows interact with each other?

Yes—through shared data. One workflow writes results to a file or database; another reads them. For direct coordination, use a message queue or orchestration layer. Keep interactions simple to maintain debuggability.

What's the failure rate for agent workflows?

Well-designed workflows with proper error handling run at 95%+ success rates. The remaining failures are usually transient (API timeouts, network issues) that resolve on retry. Poorly designed workflows (vague goals, no error handling) fail 20-40% of the time.

Should I use local or cloud models for agent workflows?

Local for volume, cloud for quality. If a workflow runs 50+ times per day, local models save significant money. If a workflow runs once per week and quality is critical, cloud models may be worth the cost. Most production setups use both.

How do I debug a failing agent workflow?

Logs are everything. Check: (1) What input did the agent receive? (2) What tools did it call? (3) What did the tools return? (4) What output did the agent produce? The failure is usually in step 2 or 3—a tool returned unexpected data, or the model misinterpreted the tool response.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*

Here's how MCP registries work, which ones matter, and how to use them effectively.

The Short Answer

MCP registries are directories of MCP servers—searchable, categorized, and installable. They solve the discovery problem: "Which MCP server does X, and how do I install it?"

| Registry | Size | Strength | Best For |

|----------|------|----------|----------|

| Smithery | Largest (5,000+) | Breadth, install commands, reviews | Finding any MCP server |

| mcpt | Curated (500+) | Quality focus, CLI tool, auto-updates | Reliable production servers |

| OpenTools | Growing (1,000+) | Search, categories | Alternative discovery |

| npm | Everything | Raw package access | Developers building custom setups |

How Discovery Works

The Problem Registries Solve

Without registries, finding an MCP server means:

1. Searching GitHub for "mcp-server-[thing you want]"

2. Hoping the README has install instructions

3. Guessing if it's maintained, secure, and compatible

4. Manually configuring everything

With registries:

1. Search or browse by category

2. Read description, reviews, and install command

3. Copy-paste the command

4. Done

Search Patterns

Most registries support these discovery methods:

Category browsing: Productivity, Development, Data, Communication, Creative, Business

Keyword search: "gmail", "database", "web scraping", "calendar"

Tag filtering: "official", "verified", "popular", "new"

Sort options: Most installed, highest rated, recently updated

Smithery: The Largest Registry

Smithery is the de facto standard for MCP server discovery. Here's how to use it effectively.

Browsing Smithery

Visit smithery.ai and you'll see:

• Featured servers—editorially curated highlights

• Categories—organized by use case

• Search—keyword search across all servers

• Trending—most popular servers this week

Reading a Server Listing

Each server page shows:

| Section | What It Tells You |

|---------|------------------|

| Description | What the server does and its capabilities |

| Tools | Specific tools the server exposes (e.g., `list_events`, `create_event`) |

| Install command | Copy-paste for Claude Desktop or Claude Code |

| Configuration | Required API keys or settings |

| Author | Who built it—official orgs vs. community |

| Stats | Install count, last updated, GitHub stars |

| Reviews | User feedback on reliability and quality |

Installing from Smithery

For Claude Desktop:

Smithery provides the exact JSON block to add to your config file:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@scope/mcp-server-name"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Copy it, paste it into `claude_desktop_config.json`, add your API key, restart Claude.

For Claude Code:

Smithery often shows the CLI command:

claude mcp add server-name -- npx -y @scope/mcp-server-name

Evaluating Quality on Smithery

Not all servers are equal. Here's how to assess quality:

| Signal | Good Sign | Warning Sign |

|--------|-----------|-------------|

| Author | Official org or verified developer | Anonymous, no GitHub link |

| Last updated | Within the past 3 months | Over 6 months ago |

| Install count | Hundreds or thousands | Single digits |

| GitHub stars | Active community | No repository linked |

| Reviews | Specific positive feedback | No reviews or vague complaints |

| Tools listed | Clear, well-documented tools | Vague or missing tool descriptions |

mcpt: The Curated Alternative

mcpt takes a quality-first approach. Fewer servers, but higher average reliability.

The mcpt CLI

mcpt provides a command-line tool for managing MCP servers:

# Install the CLI
npm install -g mcpt

# Search for servers
mcpt search calendar

# Install a server
mcpt install google-calendar

# List installed servers
mcpt list

# Update all servers
mcpt update

Advantages of mcpt

| Feature | Smithery | mcpt |

|---------|----------|------|

| Curation | Community-driven | Editorially reviewed |

| Install method | Manual config editing | CLI tool handles everything |

| Updates | Manual | `mcpt update` handles all |

| Quality bar | Low (anyone can list) | Higher (review process) |

| Size | Largest selection | Smaller, more reliable |

When to Use mcpt vs. Smithery

• Use Smithery when you need a server for an obscure tool or want maximum choice

• Use mcpt when you want reliable, well-maintained servers with easy management

OpenTools and Other Registries

OpenTools

OpenTools is a growing registry with a clean search interface. It focuses on categorization and discoverability. Worth checking if you don't find what you need on Smithery.

npm Direct

Every Node.js-based MCP server is published to npm. You can search npm directly:

npm search mcp-server

This gives you access to everything, including servers not yet listed on any registry. But there's no curation, reviews, or quality signals—you're on your own to evaluate.

GitHub

Many MCP servers live on GitHub before they're registered anywhere. Search GitHub for:

• `mcp-server` (general)

• `modelcontextprotocol` (official repos)

• `mcp-server-[tool-name]` (specific tools)

GitHub gives you access to source code, issues, commit history, and contributor activity—the deepest quality signals available.

Security Considerations

MCP servers run code on your machine. Take security seriously.

Before Installing Any Server

1. Check the source. Is the GitHub repo linked? Can you see the code?

2. Check the author. Is it an organization you recognize? A developer with a history?

3. Read the permissions. What tools does it expose? What data can it access?

4. Check for credentials. Does it need API keys? Where does it send data?

5. Check freshness. When was it last updated? Are dependencies current?

Red Flags

| Red Flag | Risk |

|----------|------|

| No source code available | Can't verify what the code does |

| Requests unusual permissions | May access more than needed |

| No clear author or organization | Harder to trust, no accountability |

| Hasn't been updated in 12+ months | May have unpatched vulnerabilities |

| Very few installs, no reviews | Unvalidated by the community |

Best Practices

• Start with official servers from Anthropic, Google, Microsoft, and established organizations

• Read the code if you're installing a community server that handles sensitive data

• Scope permissions—only give file system access to directories you actually need

• Monitor behavior—check logs if a server seems to be making unexpected network calls

How I Actually Do This

I use a mix of Smithery, npm, and direct GitHub sources for my MCP server setup.

My Discovery Workflow

1. Need a server → Search Smithery first (broadest selection)

2. Found candidates → Check GitHub repo for each (code quality, maintenance)

3. Evaluate → Look at install count, last update, and whether tools match my needs

4. Test → Install and test with a simple prompt before adding to automation

5. Production → Only servers that pass testing go into my daily workflow

Building for Registries

I'm building `mcp-astgl-knowledge` — an MCP server that exposes all 20 articles in this series as searchable knowledge. The plan:

1. Build with TypeScript and the `@modelcontextprotocol/sdk`

2. Publish to npm (`npm publish`)

3. Register on Smithery (submit listing with description, tools, install command)

4. Register on mcpt (submit for review)

5. Maintain—update when new articles are added, respond to issues

This will be a real example of the full lifecycle: build → publish → register → maintain. I'll update this article with the actual experience once it's done.

What I've Learned

1. Smithery is the starting point for everyone. It has the most servers and the most familiar interface. Start there.

2. mcpt's CLI is underrated. Managing updates across 15 servers manually is tedious. `mcpt update` handles it.

3. Official servers are worth the premium. Anthropic's official MCP servers for filesystem, web search, and databases are rock-solid. Community servers vary widely in quality.

4. Read the tools list carefully. A "Gmail MCP server" might only support reading emails, not sending them. The tools list tells you exactly what's possible.

5. The ecosystem is young and growing fast. New servers appear daily. Check registries monthly—the server you wished existed last month might exist now.

Publishing Your Own MCP Server

If you've built something useful, publishing it helps the community and builds your reputation.

The Publishing Process

1. Build your server using the MCP SDK

2. Test it locally with Claude Desktop or Claude Code

3. Publish the npm package: `npm publish`

4. Register on Smithery: Submit your listing with description, install command, and documentation

5. Register on mcpt: Submit for editorial review

6. Maintain: Respond to issues, update dependencies, improve based on feedback

What Makes a Good MCP Server Listing

| Element | Why It Matters |

|---------|---------------|

| Clear description | Users need to know what it does in 2 sentences |

| Tool documentation | Every tool should have a name, description, and example |

| Install command | Copy-paste ready for Claude Desktop and Claude Code |

| Configuration guide | What API keys or settings are needed |

| Source code link | Transparency builds trust |

| Changelog | Shows the server is actively maintained |

Frequently Asked Questions

Are MCP registries safe?

Registries are directories, not security guarantees. They make discovery easier but don't audit every server's code. Treat registry listings like npm packages—check the source, author, and community signals before installing. Official and popular servers are generally safe. Obscure, unreviewed servers deserve more scrutiny.

Can I use MCP servers not listed on any registry?

Yes. Any MCP server can be installed manually by pointing your config to the npm package or local path. Registries are for discovery—they're not gatekeepers. You can even build private MCP servers that never appear on any registry.

How often should I update my MCP servers?

Monthly is a good cadence. Security patches, bug fixes, and new features arrive regularly. If you use mcpt, `mcpt update` handles everything. For manual installs via `npx`, you always get the latest version automatically.

Will there be one dominant MCP registry?

Probably not—the ecosystem benefits from multiple registries with different strengths. Smithery for breadth, mcpt for quality, npm for raw access. This mirrors how package managers work: npm, GitHub, and specialized registries coexist.

Can I run my own private MCP registry?

Yes, for organizations that want to share internal MCP servers. The MCP protocol doesn't require public registries—any discoverable endpoint works. Some companies run internal registries for proprietary servers that access internal systems.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*

Here's the real math, with actual hardware costs, cloud API pricing, and the breakeven points where local infrastructure pays for itself.

The Short Answer

Local AI has high upfront cost and near-zero ongoing cost. Cloud AI has zero upfront cost and scales linearly forever. The crossover point depends on your usage volume.

| | Local AI | Cloud AI |

|--|----------|----------|

| Upfront cost | $600-8,000 (hardware) | $0 |

| Monthly cost | $5-15 (electricity) | $50-5,000+ (API fees) |

| Per-call cost | $0 | $0.001-0.10 per call |

| Scales with usage | No—flat cost | Yes—more usage = more cost |

| Quality ceiling | Very good (not frontier) | Frontier models available |

| Privacy | Complete—data stays local | Data sent to provider |

Rule of thumb: If you'd spend more than $100/month on API calls, local AI probably pays for itself within a year.

The Cloud Cost Reality

Cloud AI pricing is per-token. Here's what real usage patterns cost:

Typical Monthly Cloud Costs

| Usage Pattern | Calls/Day | Model | Monthly Cost |

|--------------|-----------|-------|-------------|

| Casual user | 10-20 | Claude Sonnet | $10-30 |

| Power user | 50-100 | Claude Sonnet | $50-200 |

| Developer with AI tools | 200-500 | Mixed models | $200-800 |

| Automated workflows | 500-1,000 | Claude Haiku + Sonnet | $500-2,000 |

| Full automation pipeline | 2,000-5,000 | Mixed models | $2,000-8,000 |

| Enterprise scale | 10,000+ | Mixed models | $10,000+ |

The jump from casual to automated is where costs explode. A morning briefing that runs daily, a content pipeline that generates articles, and notification routing that processes hundreds of messages—these add up fast.

The Subscription Alternative

Claude Pro ($20/month) and Claude Max ($100-200/month) offer high-volume access at flat rates. These are excellent value for interactive use. But they have rate limits that don't work well for automated pipelines running 24/7.

The Local Cost Reality

Hardware Options

| Device | RAM | Price | Best For |

|--------|-----|-------|----------|

| Mac Mini M4 | 32 GB | ~$800 | Entry-level: runs 7-12B models comfortably |

| Mac Mini M4 Pro | 48 GB | ~$1,400 | Mid-range: runs 26B models, 2-3 concurrent |

| Mac Studio M3 Max | 96 GB | ~$3,000 | Serious: runs 70B models, full automation |

| Mac Studio M3 Ultra | 192 GB | ~$5,000 | Professional: multiple large models simultaneously |

| Mac Studio M3 Ultra | 512 GB | ~$8,000 | Maximum: every model, every size, all at once |

| Linux + RTX 4090 | 24 GB VRAM | ~$2,500 | Fast inference, limited to one large model |

| Linux + 2x RTX 4090 | 48 GB VRAM | ~$4,500 | High throughput, parallel inference |

Apple Silicon advantage: Unified memory means the GPU can access all system RAM. A 192 GB Mac Studio can run models that would require multiple $2,000 GPUs on Linux.

Ongoing Costs

| Cost | Monthly | Annual |

|------|---------|--------|

| Electricity (always-on Mac Studio) | $10-15 | $120-180 |

| Internet (already have it) | $0 incremental | $0 |

| Software (Ollama, open-source models) | $0 | $0 |

| Maintenance time (~2 hours/month) | Time cost | Time cost |

| Total cash cost | $10-15 | $120-180 |

Breakeven Analysis

Scenario 1: Light Automation

Setup: Mac Mini 32 GB ($800) running morning briefings and email triage.

Cloud alternative: ~$150/month in API calls (500 calls/day, mixed models).

Breakeven: $800 ÷ $150/month = 5.3 months

Year 1 savings: ($150 × 12) - $800 - $150 electricity = $850

Scenario 2: Content Creator

Setup: Mac Mini 48 GB ($1,400) running content pipeline, research, and repurposing.

Cloud alternative: ~$400/month in API calls (content generation is token-heavy).

Breakeven: $1,400 ÷ $400/month = 3.5 months

Year 1 savings: ($400 × 12) - $1,400 - $150 = $3,250

Scenario 3: Full Automation

Setup: Mac Studio 192 GB ($5,000) running 26 daily tasks, content pipeline, multi-agent council.

Cloud alternative: ~$2,000/month in API calls (thousands of daily calls across multiple agents).

Breakeven: $5,000 ÷ $2,000/month = 2.5 months

Year 1 savings: ($2,000 × 12) - $5,000 - $180 = $18,820

The Pattern

The more you automate, the faster local infrastructure pays for itself. Light users might take a year to break even. Heavy automation users break even in months.

Beyond Dollar Savings: Hidden ROI

The financial math is compelling, but the less obvious benefits matter too.

Privacy ROI

With local AI, sensitive business data never leaves your machine. No data processing agreements. No compliance concerns about which country your data is processed in. No risk of training data leakage.

For regulated industries (healthcare, legal, finance), this alone can justify the hardware cost—the alternative is expensive enterprise AI contracts with compliance guarantees.

Availability ROI

Cloud APIs have outages. Rate limits. Capacity constraints during peak hours. Your automated pipeline at 6 AM shouldn't depend on whether a cloud provider's servers are congested.

Local AI is available whenever your computer is on. No rate limits. No outages (except your own hardware). No "please try again later."

Latency ROI

Local inference is fast—especially on Apple Silicon. A Gemma 4 26B running locally generates tokens faster than most cloud APIs deliver them, because there's no network round trip.

For interactive use, this means snappier responses. For automation, this means faster pipeline throughput.

Experimentation ROI

When every API call costs money, you hesitate to experiment. With local models, experimentation is free. Try 50 different prompt variations. Run A/B tests on voice profiles. Process your entire email archive to build training data. The marginal cost is zero.

This freedom to experiment accelerates learning and leads to better automation designs.

How I Actually Do This

I run a Mac Studio M3 Ultra with 256 GB unified memory. Here's the real financial picture:

My Costs

| Item | Cost |

|------|------|

| Mac Studio M3 Ultra 256 GB | $7,000 (one-time) |

| Electricity (~120W average, 24/7) | ~$12/month |

| Cloud Claude (10% of tasks) | ~$20/month (Pro subscription) |

| Total monthly ongoing | ~$32/month |

What I'd Pay With Cloud APIs

| Workload | Estimated Monthly Cloud Cost |

|----------|----------------------------|

| 26 scheduled agent tasks | $800-1,200 |

| Content pipeline (ACA Council) | $400-600 |

| Ad-hoc development assistance | $200-400 |

| Research and analysis | $100-200 |

| Total estimated | $1,500-2,400/month |

My Breakeven

$7,000 ÷ $1,500/month = 4.7 months

I passed breakeven months ago. Every month now is pure savings.

The Honest Caveats

1. Cloud Claude is still better for some tasks. Complex architectural decisions, nuanced code review, novel problem-solving—I still reach for cloud Claude. Local models handle 90% of the volume but not 100% of the difficulty.

2. Setup time is real. I spent about 40 hours over several weeks getting the full automation stack running. That's an investment of time that wouldn't exist with cloud APIs.

3. Hardware depreciates. In 3-4 years, I'll want newer hardware. The Mac Studio will still work, but newer models will be faster and more capable. Budget for replacement cycles.

4. Not everyone needs this. If you make 20 AI calls a day interactively, a Claude Pro subscription ($20/month) is the right answer. Local infrastructure makes sense when you're automating at volume.

Decision Framework

Choose Cloud When:

- You're just starting with AI (explore before investing)
- Your usage is primarily interactive (chatting, not automating)
- You need frontier model quality for every task
- You want zero hardware management
- Monthly API costs stay under $100

Choose Local When:

- You're automating workflows that run daily/hourly
- Privacy is a requirement (regulated industry, sensitive data)
- You'd spend $200+/month on cloud APIs
- You want unlimited experimentation without cost anxiety
- You're running multiple concurrent AI tasks

Choose Hybrid (Best for Most):

- Local models for volume tasks (triage, automation, content generation)
- Cloud models for high-value tasks (complex reasoning, frontier quality)
- Result: 90% of compute is free, 10% is cloud-quality

Frequently Asked Questions

Can I start with a cheaper machine and upgrade later?

Absolutely. A Mac Mini with 32 GB ($800) runs a solid automation stack. If you outgrow it, sell it (Macs hold resale value well) and upgrade. You don't need to start with the most expensive option.

What about Linux with NVIDIA GPUs?

Competitive for raw inference speed—an RTX 4090 (24 GB VRAM) is fast. But limited VRAM means you can only run one large model at a time. For multi-model architectures (triage + workhorse + specialist), Apple Silicon's unified memory is more flexible. Linux rigs are better for single-model, high-throughput workloads.

Does model quality improve fast enough to justify local hardware?

Yes. Open-source models improve dramatically every 6-12 months. A 26B model today outperforms a 70B model from two years ago. Your hardware runs better models over time without any additional cost—just download the new model.

What if I already have a powerful gaming PC?

If it has an NVIDIA GPU with 12+ GB VRAM, you can run local AI today at zero additional cost. Install Ollama, pull a model, and start experimenting. This is the cheapest possible entry point.

Is the electricity cost significant?

No. A Mac Studio draws about 40-120W depending on load. At US average electricity rates (~$0.15/kWh), that's $4-13/month running 24/7. An RTX 4090 draws more (300-450W under load) but idles much lower. Electricity is a rounding error compared to API costs.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*

A content pipeline automates the repetitive parts so you focus on ideas, not formatting. Here's how to build one, from simple to fully autonomous.

The Short Answer

An AI content pipeline takes raw ideas and produces finished, distributed content through automated stages. The simplest pipeline has 3 stages. A production pipeline has 7 or more.

| Pipeline Level | Stages | Human Involvement | Output |

|---------------|--------|-------------------|--------|

| Basic | Write → Format → Publish | High—you drive every step | 1 article |

| Intermediate | Research → Write → Repurpose → Publish | Medium—review at checkpoints | 1 article + 10 derivatives |

| Advanced | Discover → Research → Write → Edit → Fact-check → Repurpose → Publish | Low—review final output | 1 article + 25+ derivatives |

Pipeline Architecture: The 7 Stages

Every content pipeline, regardless of complexity, follows the same logical stages. You can automate as many or as few as you want.

Stage 1: Discovery

What: Find topics worth writing about.

How: AI monitors news feeds, social media trends, competitor content, and search queries in your niche. It surfaces topics with high interest and low competition.

Manual version: You browse industry sites and note ideas.

Automated version: A scheduled agent searches 10+ sources daily and delivers a ranked topic list every morning.

Stage 2: Research

What: Gather information, data, and sources for the chosen topic.

How: AI searches the web, reads relevant articles, extracts key facts, and compiles a structured research brief.

Output: A 1-2 page brief with key points, statistics, source URLs, and suggested angles.

Stage 3: Drafting

What: Write the first draft.

How: AI takes the research brief, applies your voice profile and article template, and generates a full draft.

Critical input: A voice profile—a document that describes your writing style, preferred vocabulary, sentence patterns, and tone. Without this, AI output sounds generic. With it, the draft sounds like you.

Stage 4: Editing

What: Improve the draft's quality, flow, and accuracy.

How: AI reviews for clarity, removes filler, tightens sentences, checks structure against the template, and verifies the voice matches your profile.

This is best done as a separate pass with a different prompt than the drafting stage. A fresh "editor" perspective catches issues the "writer" misses.

Stage 5: Fact-Checking

What: Verify claims, statistics, and technical accuracy.

How: AI identifies every factual claim in the article, searches for supporting sources, flags anything unverified, and provides confidence ratings.

Two-phase approach:

1. Extraction: Pull every claim from the article

2. Verification: Check each claim against web sources and known data

This step catches hallucinations before they reach your audience.

Stage 6: Repurposing

What: Transform the article into platform-specific content pieces.

How: AI reads the finished article and generates variations for every distribution channel.

| Derivative | Platform | Format |

|-----------|----------|--------|

| 5 social posts | LinkedIn, X, Facebook, Instagram, Threads | Platform-native length and style |

| 5 short-form notes | Substack Notes | Teaser + link |

| 1 newsletter intro | Email | Hook paragraph + article link |

| 1 SEO document | Search engines | Meta description, keywords, schema markup |

| 1 voiceover script | Podcast / video | Conversational spoken version |

| 5 graphic suggestions | Design tools | Visual concepts with text overlays |

| 3 pull quotes | Social graphics | Shareable quote cards |

One article → 25+ content pieces. The marginal cost of each derivative is near zero.

Stage 7: Publishing

What: Distribute content to all channels.

How: Automated posting through APIs, MCP servers, or scheduling tools.

Current best practice: Publish to your own site first (canonical URL), then syndicate to Substack, social platforms, and newsletters. This is POSSE—Publish Own Site, Syndicate Everywhere.

Building Your First Pipeline

Start simple. You can always add stages.

Level 1: Manual Pipeline (30 Minutes)

Tools needed: Claude with filesystem MCP server.

1. Write an article (or paste an existing one)

2. Ask Claude: "Read this article and generate 5 LinkedIn posts, 5 tweets, a newsletter intro, and SEO metadata."

3. Review and publish manually

Time investment: 30 minutes per article cycle.

Output: 1 article + ~15 derivatives.

Level 2: Template Pipeline (15 Minutes)

Tools needed: Claude Code with custom commands.

Create a slash command (`.claude/commands/repurpose.md`) that contains your repurposing prompt with voice profile, platform specs, and output format. Then:

/repurpose path/to/article.md

One command generates all derivatives. You review and publish.

Time investment: 15 minutes per article cycle.

Output: 1 article + 25+ derivatives.

Level 3: Automated Pipeline (5 Minutes of Review)

Tools needed: Local AI (Ollama), scheduling (OpenClaw/cron/n8n), MCP servers.

The pipeline runs on schedule:

1. Discovery agent finds a topic (or you assign one)

2. Research agent compiles a brief

3. Draft agent writes the article

4. Edit agent polishes it

5. Fact-check agent verifies claims

6. Repurpose agent generates derivatives

7. Draft appears in your review queue

Your only job: Read the final output, approve or request changes, hit publish.

Time investment: 5 minutes per article cycle (review only).

Output: 1 article + 25+ derivatives, fully automated.

Voice Profiles: The Secret to Human-Sounding AI Content

The #1 differentiator between generic AI content and content that sounds like you is the voice profile.

What a Voice Profile Contains

## Writing Voice: [Your Name]

### Tone
- Conversational but authoritative
- Direct — lead with the answer, not the preamble
- Practical over theoretical

### Sentence Structure
- Short sentences (10-15 words average)
- Active voice (95%+)
- Start paragraphs with statements, not questions

### Vocabulary
- Plain language — "use" not "utilize", "help" not "facilitate"
- Technical terms only when the audience expects them
- No corporate jargon: avoid "leverage", "synergy", "paradigm"

### Patterns to Follow
- Open with a hook that acknowledges the reader's problem
- Use tables for comparisons
- Include "How I Actually Do This" sections with real examples
- End FAQ sections with practical answers, not theory

### Patterns to Avoid
- Never use "In today's fast-paced world..."
- Never start with a definition from Wikipedia
- No filler paragraphs that don't add information
- Don't hedge excessively — state positions clearly

How to Build Your Voice Profile

1. Gather 5-10 pieces of your best writing—articles, emails, presentations

2. Ask AI to analyze your voice: "Read these writing samples and describe my writing style—tone, sentence structure, vocabulary choices, recurring patterns."

3. Edit the analysis—AI will capture 80%, you refine the rest

4. Include it in every content prompt—either inline or as a system prompt

How I Actually Do This

I run a multi-agent content pipeline called the ACA Council. Five specialized agents handle different stages:

The ACA Council

| Agent | Role | What It Does |

|-------|------|-------------|

| SCOUT | Discovery & Research | Monitors 15+ sources, surfaces trending topics, compiles research briefs |

| FORGE | Outlining & Structure | Takes research briefs and generates structured article outlines |

| QUILL | Drafting | Writes full articles following voice profile and article templates |

| LEDGER | Fact-Checking & Validation | Two-phase verification of every claim, flags uncertainties |

| MAVEN | SEO & Distribution | Generates all derivative content, optimizes for search and social |

The Daily Schedule

The Council meets twice daily:

• Morning session (7 AM): SCOUT presents research, team prioritizes topics

• Evening session (8 PM): Review completed articles, queue for publishing

The 7-Step Build Pipeline

For each article:

1. SCOUT delivers a research brief

2. FORGE generates the outline

3. QUILL writes the draft using voice profile

4. LEDGER fact-checks (two-phase: extract claims → verify sources)

5. Human review checkpoint (me—5 minutes)

6. MAVEN generates 25+ derivatives

7. Auto-publish to site, sync to Substack, queue social posts

Results

• Output: 3-5 articles per week with full distribution packages

• My time per article: ~10 minutes (topic approval + final review)

• AI time per article: ~20 minutes of model compute

• Cloud API cost: $0/month—everything runs on local Ollama models

• Quality: Consistent voice, verified facts, platform-optimized distribution

Common Pipeline Mistakes

| Mistake | Why It Fails | Fix |

|---------|-------------|-----|

| No voice profile | Content sounds generic and robotic | Build a voice profile from your existing writing |

| Skipping fact-check | AI hallucinates statistics and quotes | Always run a verification pass before publishing |

| One-shot generation | Single prompt produces mediocre results | Split into stages—research, draft, edit are separate steps |

| No human review | Errors slip through, voice drifts | Always scan final output before publishing |

| Over-automating too early | Complex pipeline before simple one is proven | Start manual, automate one stage at a time |

Frequently Asked Questions

How long does it take to build a content pipeline?

A basic manual pipeline (Level 1) takes 30 minutes to set up. A template pipeline (Level 2) takes 1-2 hours. A fully automated pipeline (Level 3) takes 1-2 weeks of iterating on prompts, voice profiles, and scheduling. Start at Level 1 and upgrade when you feel the friction.

Will Google penalize AI-generated content?

Google penalizes low-quality content, regardless of how it's created. AI content that's well-researched, accurate, and genuinely useful ranks well. The key factors: original insights (your "How I Actually Do This" sections), verified facts, and genuine expertise. A pipeline that produces generic AI slop will be penalized. One that produces expert-informed, fact-checked content won't.

Can I use this for client work?

Yes, with transparency. Many agencies use AI pipelines to increase throughput. The ethical approach: AI handles research, drafting, and repurposing; humans provide expertise, review, and final approval. Disclose AI assistance if your clients expect it.

How do I handle topics the AI gets wrong?

This is why the fact-checking stage exists. For technical topics, include authoritative sources in the research brief so the AI has correct information to work from. For evolving topics, always include a web search step to get current data. And always review—the pipeline produces drafts, not published pieces.

What's the best AI model for content pipelines?

For drafting: Gemma 4 26B or 31B (best voice quality at the local tier). For fact-checking: a model with web search access. For repurposing: Gemma 4 26B (handles format transformation well). For the full pipeline on a budget: a single Gemma 4 26B handles all stages adequately.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*

MCP servers change that math. They let AI handle the repetitive work using the tools you already have. No enterprise budget. No IT department. No coding.

The Short Answer

Yes. MCP servers give small businesses access to the same AI automation capabilities that enterprises are spending millions on—at a fraction of the cost. The ROI is immediate and measurable.

| Business Size | Without MCP | With MCP |

|--------------|-------------|----------|

| Solo operator | You do everything manually | AI handles content, email, research while you focus on clients |

| Small team (2-10) | Everyone wears multiple hats | AI automates shared workflows — briefings, reports, scheduling |

| Growing business (10-50) | Processes are inconsistent, tribal knowledge | AI standardizes workflows and makes knowledge accessible |

The Five Highest-ROI Automations for Small Business

These five automations deliver the most time savings for the least setup effort. Start with one, prove the value, then add more.

1. Content Repurposing (Save 2-4 Hours Per Article)

You write one blog post. MCP-connected AI turns it into:

| Output | Platform | Time to Create Manually |

|--------|----------|------------------------|

| 5 social media posts | LinkedIn, X, Facebook, Instagram, Threads | 45 min |

| 1 newsletter intro | Email / Substack | 20 min |

| 1 SEO summary | Google / site meta | 15 min |

| 3 pull quotes | Social graphics | 15 min |

| 1 thread/carousel | X or LinkedIn | 30 min |

| 5 Substack Notes | Substack | 25 min |

| 1 voiceover script | Podcast / video | 20 min |

| 5 alt-angle headlines | A/B testing | 15 min |

Total manual time: ~3 hours. With AI: ~15 minutes (review and approve drafts).

The AI reads your original article through the filesystem MCP server, generates all the variations, and saves them as files. You review, tweak if needed, and publish.

One article → 25+ content pieces. For a small business publishing weekly, that's 12+ hours saved per month.

2. Morning Briefing (Save 30 Minutes Per Day)

Instead of checking email, calendar, tasks, and news manually each morning:

Setup: Connect Calendar + Email + Task Manager + Web Search MCP servers.

What AI delivers at 6:30 AM:

• Today's meetings with prep notes

• Important emails that need attention (prioritized)

• Overdue tasks

• Relevant industry news

Monthly time saved: ~10 hours

This one automation pays for a Claude Pro subscription ($20/month) in the first week.

3. Email Triage and Draft Responses (Save 30-60 Minutes Per Day)

Setup: Connect Gmail MCP server.

How it works:

• AI reads incoming emails

• Classifies by priority (urgent, important, routine, spam)

• Drafts responses for routine emails

• Flags emails that need your personal attention

You review the drafts, hit send on the good ones, and personally handle only the ones that matter. Instead of reading 50 emails, you review 10 drafts and write 5 personal responses.

Monthly time saved: 10-20 hours

4. Meeting Prep and Follow-Up (Save 20-30 Minutes Per Meeting)

Setup: Connect Calendar + Email + CRM MCP servers.

Before the meeting, AI generates:

• Attendee background (from CRM and recent emails)

• Last interaction summary

• Suggested talking points

• Relevant documents or proposals

After the meeting, AI generates:

• Action item list

• Follow-up email drafts

• Updated CRM notes

• Calendar entries for follow-ups

For a business with 5 meetings per week, that's 8-12 hours saved per month.

5. Competitive Research (Save 1-2 Hours Per Week)

Setup: Connect Web Search MCP server.

Weekly automated research:

• Competitor website changes

• New product announcements in your space

• Industry news and trends

• Social media mentions of competitors

AI summarizes everything into a structured brief. You read a 2-page summary instead of spending hours browsing websites and social feeds.

Monthly time saved: 4-8 hours

The ROI Math

Let's make this concrete. Assume a small business owner's time is worth $75/hour (conservatively).

| Automation | Monthly Hours Saved | Monthly Value |

|-----------|-------------------|---------------|

| Content repurposing | 12 hours | $900 |

| Morning briefing | 10 hours | $750 |

| Email triage | 15 hours | $1,125 |

| Meeting prep/follow-up | 10 hours | $750 |

| Competitive research | 6 hours | $450 |

| Total | 53 hours | $3,975 |

Monthly cost:

• Claude Pro: $20/month

• Or local models (Ollama on a Mac Mini): ~$600 one-time, $0/month ongoing

Even with just one or two of these automations, the ROI is overwhelming.

Getting Started: The 30-Minute Setup

Here's the fastest path from zero to your first useful automation.

Minute 0-5: Install Claude Desktop

Download from claude.ai, install, and log in. A Claude Pro subscription ($20/month) includes MCP server support.

Minute 5-10: Install Node.js

This is the one-time prerequisite. Download from nodejs.org (LTS version), install, done.

Minute 10-20: Add Your First MCP Servers

Open Claude Desktop settings and add two servers:

Filesystem (access your business documents):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/path/to/your/business/documents"]
    }
  }
}

Web Search (research capabilities):

{
  "mcpServers": {
    "filesystem": { "..." },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-web-search"],
      "env": {
        "BRAVE_API_KEY": "your-free-api-key"
      }
    }
  }
}

Minute 20-30: Run Your First Automation

Restart Claude Desktop. Then try:

"Read my latest blog post from Documents/blog/ and create 5 LinkedIn posts, 3 tweet-length posts, and a newsletter introduction from it."

Claude reads the file through the filesystem server, generates all the content variations, and presents them. Copy, review, publish.

You just saved 2 hours of work in 10 minutes.

Scaling Up: Month-by-Month Plan

Month 1: Foundation

• Set up filesystem + web search MCP servers

• Use Claude for content repurposing (manual—you ask each time)

• Track time saved vs. time spent

Month 2: Communication

• Add Gmail MCP server

• Start using email triage and draft responses

• Add Google Calendar server for meeting prep

Month 3: Automation

• Set up scheduled tasks (morning briefing via OpenClaw or n8n)

• Create templates for recurring workflows

• Add CRM or project management MCP server

Month 4+: Optimization

• Refine prompts based on output quality

• Add specialized servers for your industry

• Consider local models (Ollama) to eliminate API costs

How I Actually Do This

I use MCP servers to run a content-first small business. Here's the actual pipeline:

Content Pipeline (1 Article → 25+ Pieces)

My ACA Council—five specialized AI agents—handles the full content lifecycle:

1. SCOUT finds trending topics and research material

2. FORGE generates structured outlines

3. QUILL writes the draft

4. LEDGER fact-checks and validates claims

5. MAVEN optimizes for SEO and generates distribution pieces

One article generates: the full blog post, SEO metadata, social posts for 5 platforms, a newsletter version, Substack Notes, a voiceover script, and graphic suggestions. All automated.

Morning Briefing (30 Minutes Saved Daily)

OpenClaw runs a morning briefing at 6:30 AM using local models:

• Calendar summary (Google Calendar MCP)

• Priority email scan (Gmail MCP)

• Overnight log review (filesystem MCP)

• Industry news (web search MCP)

Delivered to Discord before I finish my coffee. I read a 2-page summary instead of spending 30 minutes checking 4 different apps.

The Business Case

My entire automation stack runs on local models—$0/month in API costs. The Mac Studio hardware was a significant upfront investment, but you don't need that to start. A Mac Mini with 32 GB ($800) runs a morning briefing and content repurposing pipeline comfortably. That investment pays for itself in the first month of time savings.

Common Concerns

"What if the AI produces bad content?"

It will, sometimes. That's why every automation includes a review step. AI generates drafts; you approve or edit. The time savings come from not starting from a blank page—editing a draft is always faster than writing from scratch.

"I'm worried about data privacy."

MCP servers run locally on your computer. Your business data doesn't leave your machine unless you explicitly connect to cloud services. For maximum privacy, use local models through Ollama—then nothing touches the internet at all.

"My business is too niche for AI."

AI doesn't need to understand your niche deeply to save you time. Email triage, meeting prep, and content formatting are universal tasks. The AI handles the structure; you provide the domain expertise. That combination is powerful regardless of industry.

"I tried ChatGPT and it wasn't that helpful."

ChatGPT without MCP servers is limited to what you paste into the chat. With MCP servers, AI accesses your actual data—files, emails, calendars, web. The difference is dramatic. It's the difference between describing your schedule to someone and handing them your calendar.

Frequently Asked Questions

Which industries benefit most from MCP automation?

Any industry with significant knowledge work: professional services (law, accounting, consulting), real estate, marketing agencies, e-commerce, healthcare administration, education. The common thread is repetitive text-based tasks—email, documents, research, content.

Can I use MCP servers if I'm not tech-savvy?

Yes. The initial setup requires following step-by-step instructions (similar to installing any software). Once configured, you interact with AI using plain language. "Summarize my emails" is the interface—not code.

How do MCP servers compare to Zapier or Make?

Zapier and Make connect apps with if-then rules. MCP servers connect apps to AI with understanding. A Zapier automation moves data between apps in a fixed pattern. An MCP-connected AI reads, interprets, decides, and acts. They complement each other—use Zapier for simple triggers and MCP for intelligent processing.

What's the minimum investment to get started?

• Claude Pro subscription: $20/month

• Hardware: Your existing computer

• Time: 30 minutes for initial setup

• Total first-month cost: $20

Compare that to a virtual assistant ($500-2000/month) or a part-time employee ($1500+/month) for the same tasks.

Can my team share MCP server setups?

Yes. Configuration files can be shared and standardized across a team. Everyone gets the same MCP servers connected the same way, ensuring consistent AI capabilities across the business.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*

Here's exactly how—three methods, zero coding required.

The Short Answer

Yes, you can use MCP servers without being a developer. The setup involves editing a configuration file or running a single command. No programming skills needed.

| Method | Difficulty | Time to Set Up | Best For |

|--------|-----------|----------------|----------|

| Claude Desktop | Copy-paste a config block | 5-10 minutes | Non-technical users who want a GUI |

| Claude Code CLI | Run one command per server | 2-3 minutes | Anyone comfortable with a terminal |

| VS Code | GUI settings panel | 5-10 minutes | People already using VS Code |

Prerequisites (One-Time Setup)

Before installing MCP servers, you need two things on your computer. If you already have them, skip ahead.

Node.js

Most MCP servers are built with Node.js. Install it once and forget about it.

Mac:

# Open Terminal and run:
brew install node

Windows:

Download from nodejs.org and run the installer. Choose the LTS version.

Verify it's installed:

node --version
# Should show something like: v22.x.x

Python (Optional)

Some MCP servers use Python instead of Node.js. Install it if you encounter a Python-based server.

Mac:

brew install python

Windows:

Download from python.org. Check "Add to PATH" during installation.

That's it for prerequisites. You won't need to write any JavaScript or Python—these are just runtimes that MCP servers need to execute.

Method 1: Claude Desktop (GUI)

Claude Desktop is the easiest starting point. You edit one configuration file, restart Claude, and your MCP servers appear as tools.

Step 1: Find the Config File

Open Claude Desktop, then:

• Mac: Claude menu → Settings → Developer → Edit Config

• Windows: File → Settings → Developer → Edit Config

This opens `claude_desktop_config.json` in your text editor.

Step 2: Add an MCP Server

The config file has a `mcpServers` section. Each server gets a block. Here's an example adding a web search server:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-web-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key-here"
      }
    }
  }
}

What each part means:

• `"web-search"` — A name you choose (anything you want)

• `"command"` — How to run the server (`npx` for Node.js servers)

• `"args"` — The server package name

• `"env"` — API keys or settings the server needs

Step 3: Add Multiple Servers

Stack them in the same config file:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-web-search"],
      "env": {
        "BRAVE_API_KEY": "your-key"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop. You should see a hammer icon showing your connected tools. Click it to see which tools each server provides.

Step 5: Use Them

Just talk to Claude normally:

• "Search the web for MCP server tutorials"

• "List the files in my Documents folder"

• "Show me my recent GitHub pull requests"

Claude automatically decides which MCP server tools to use based on your request.

Method 2: Claude Code CLI (Fastest)

If you use Claude Code (the terminal version), adding MCP servers is a single command.

Add a Server

claude mcp add web-search -- npx -y @anthropic/mcp-server-web-search

That's it. One command. The server is immediately available in your next Claude Code session.

Add With Environment Variables

claude mcp add github -- npx -y @modelcontextprotocol/server-github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your-token

List Connected Servers

claude mcp list

Remove a Server

claude mcp remove web-search

Scoping

Claude Code lets you scope servers to specific projects:

# Available in all projects (global)
claude mcp add --scope global web-search -- npx -y @anthropic/mcp-server-web-search

# Available only in the current project
claude mcp add --scope project web-search -- npx -y @anthropic/mcp-server-web-search

Method 3: VS Code (GUI)

If you use VS Code with the Claude extension, MCP servers can be configured through the settings GUI.

Step 1: Open Settings

`Cmd+,` (Mac) or `Ctrl+,` (Windows) → Search for "MCP"

Step 2: Add Server Configuration

VS Code's settings UI lets you add MCP server entries with fields for command, arguments, and environment variables. Same information as the JSON config, just in a form.

Step 3: Reload Window

`Cmd+Shift+P` → "Reload Window" to activate the new servers.

Finding MCP Servers to Install

Public Registries

| Registry | URL | Notes |

|----------|-----|-------|

| Smithery | smithery.ai | Largest registry, reviews, install commands |

| mcpt | mcpt.ai | Curated, quality-focused |

| OpenTools | opentools.ai | Growing collection, search by category |

| npm | npmjs.com (search "mcp-server") | Raw package listings |

How to Browse

1. Go to a registry (start with Smithery)

2. Browse categories: Productivity, Development, Data, Communication

3. Click a server to see: description, required config, install command

4. Copy the install command into your config file or CLI

Popular Servers for Non-Developers

| Server | What It Does | Config Complexity |

|--------|-------------|-------------------|

| Filesystem | Read/write files on your computer | Simple—just specify allowed directories |

| Web Search | Search the internet | Needs one API key (Brave) |

| Gmail | Read and draft emails | OAuth setup (guided) |

| Google Calendar | Check and create events | OAuth setup (guided) |

| Slack | Read and send messages | Bot token from Slack |

| Notion | Read and edit Notion pages | API key from Notion |

| GitHub | Manage repos, PRs, issues | Personal access token |

Real Setup Walkthrough: 3 Servers in 15 Minutes

Let's set up three useful MCP servers from scratch using Claude Code.

Server 1: Filesystem (2 minutes)

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop

Now Claude can read and write files in your Documents and Desktop folders. Try:

• "List the files on my Desktop"

• "Read the contents of Documents/notes.txt"

• "Create a file called todo.txt on my Desktop with today's tasks"

Server 2: Web Search (3 minutes)

1. Get a free API key from brave.com/search/api

2. Run:

claude mcp add web-search -- npx -y @anthropic/mcp-server-web-search \
  --env BRAVE_API_KEY=your-key-here

Now Claude can search the internet. Try:

• "Search for the latest news about MCP servers"

• "Find tutorials on Ollama setup"

Server 3: GitHub (5 minutes)

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token

2. Select scopes: `repo`, `read:org`

3. Run:

claude mcp add github -- npx -y @modelcontextprotocol/server-github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your-token

Now Claude can interact with your GitHub repos. Try:

• "Show my open pull requests"

• "List issues in my project repo"

How I Actually Do This

I run about 15 MCP servers connected to Claude Code for daily work. Here's my philosophy:

The Config File Approach

For Claude Desktop, I keep a curated config file that I've refined over months. New servers get tested individually before joining the main config—one bad server config can prevent Claude Desktop from loading any of them.

The CLI Approach

For Claude Code, I use `claude mcp add` for project-specific servers and global scope for universal ones:

# Global — available everywhere
claude mcp add --scope global web-search -- npx -y @anthropic/mcp-server-web-search
claude mcp add --scope global filesystem -- npx -y @modelcontextprotocol/server-filesystem ~

# Project-specific — only in this repo
claude mcp add github -- npx -y @modelcontextprotocol/server-github

What I've Learned

1. Start with 2-3 servers. File system + web search covers most needs. Add more only when you feel the gap.

2. Test one at a time. If you add 5 servers at once and something breaks, you won't know which one caused it. Add one, verify it works, then add the next.

3. Keep API keys in environment variables. Never paste keys directly in config files that might be synced or shared. Use `.env` files or your system's keychain.

4. Read the server docs. Each server has specific capabilities and limitations. A filesystem server configured with `~/Documents` can only acces Documentsit can't read your whole drive. That's a feature, not a bug.

5. The MCP ecosystem is growing fast. When I started, there were maybe 100 servers available. Now there are thousands. Check registries periodically—there might be a server for that tool you've been wishing Claude could access.

Troubleshooting

| Problem | Likely Cause | Fix |

|---------|-------------|-----|

| Server doesn't appear in Claude | Config syntax error | Validate your JSON at jsonlint.com |

| "Command not found" error | Node.js not installed | Install Node.js (see Prerequisites) |

| Server connects but tools don't work | Missing API key or wrong permissions | Check the server's documentation for required env variables |

| All servers stopped working | One server config is broken | Remove servers one at a time to find the broken one |

| Slow responses | Too many servers loaded | Remove servers you don't use regularly |

Frequently Asked Questions

Is it safe to give MCP servers access to my files?

MCP servers only access what you explicitly allow. A filesystem server configured with `~/Documents` cannot read your email, browser history, or other folders. Always scope access to the minimum needed directories.

Do MCP servers send my data to the cloud?

Not by default. MCP servers run locally on your machine. Data only leaves your computer if the server explicitly calls an external API (like web search or Gmail). Local-only servers like filesystem never send data anywhere.

Can I use MCP servers on my phone?

Not directly—MCP servers currently run on desktop/laptop computers. However, if you set up servers on a home computer, you can access them remotely through tools like Claude Code over SSH or a web-based interface like Open WebUI.

What happens if an MCP server crashes?

Claude continues working—it just loses access to that server's tools. Other servers remain connected. Restart the crashed server by restarting Claude Desktop or running `claude mcp restart` in Claude Code.

Do I need to update MCP servers?

Occasionally. Servers installed via `npx` automatically use the latest version. Servers installed globally with `npm install -g` need manual updates with `npm update -g`. Check for updates monthly.

Leave a comment

*This is part of the ASTGL Definitive Answers series—structured, practical answers to the questions people actually ask about AI automation, MCP servers, and local AI infrastructure.*