DEV Community: Gumaro Gonzalez

24 Custom MCP Tools Later: Why Your Agent's Biggest Cost Is Not the Model — It's the Prompt

Gumaro Gonzalez — Tue, 24 Mar 2026 06:17:42 +0000

Every time your agent sends a prompt like "read the file src/routes/ventas.js, find line 45, and tell me what's there", you're paying for 25 tokens of natural language that the model has to interpret, might misunderstand, and will probably hallucinate part of the answer.
When my agent does the same thing, it calls:
{
"tool": "read_file",
"parameters": {
"path": "src/routes/ventas.js",
"offset": 40,
"limit": 10
}
}
The model didn't generate that path from memory. It didn't guess what's on line 45. The MCP tool returned the actual file content with line numbers from the actual file system. Zero interpretation. Zero hallucination. Fewer tokens.
I built 24 custom MCP tools organized in 6 categories. They power an autonomous agent that manages 6 production services for my business. This post is about what I learned building those tools and why MCP is the single biggest lever you have for reducing cost, hallucination, and prompt bloat in any agent system.
What "Native Prompts" Means (And Why It Matters More Than Model Choice)
I use the term "native prompt" to describe something most agent builders overlook: every MCP tool definition is an instruction the model consumes without you writing it in the system prompt.
When you register a tool like this:
@server.tool()
async def search_code(pattern: str, glob: str = "*/", case_insensitive: bool = True) -> str:
"""Regex search across project files using ripgrep.
Returns matching lines with file paths and line numbers.
Use for finding function definitions, variable usage,
import patterns, or error-related code."""
That docstring, those parameter names, those type hints — they are documentation the model actually reads. You don't need to write in your system prompt: "When you need to find code patterns, use regex search. Pass the pattern as the first argument..." The tool schema already communicates this.
This is a fundamental shift in how you think about prompt engineering for agents:
TRADITIONAL AGENT PROMPT:
┌─────────────────────────────────────────────┐
│ System prompt (800 tokens) │
│ ├── Role description │
│ ├── How to read files (150 tokens) │
│ ├── How to edit files (200 tokens) │
│ ├── How to search code (100 tokens) │
│ ├── How to manage processes (120 tokens) │
│ ├── How to use git (130 tokens) │
│ └── Safety rules │
│ │
│ Every instruction = tokens you pay for │
│ Every ambiguity = hallucination risk │
└─────────────────────────────────────────────┘

MCP-BASED AGENT:
┌─────────────────────────────────────────────┐
│ System prompt (200 tokens) │
│ ├── Role description │
│ └── Safety rules │
│ │
│ Tool schemas (consumed natively by model) │
│ ├── read_file: schema + docstring │
│ ├── edit_file: schema + docstring │
│ ├── search_code: schema + docstring │
│ ├── restart_process: schema + docstring │
│ ├── check_health: schema + docstring │
│ └── ... 19 more tools │
│ │
│ Instructions live IN the tools, not │
│ in prose the model might misread │
└─────────────────────────────────────────────┘
The system prompt shrinks from 800 tokens to 200 because the tools carry their own documentation. And that documentation is structured parameter names, types, descriptions not free-text that the model has to parse and might misinterpret.
Native prompts are cheaper, more precise, and harder to hallucinate against.
The 24 Tools: Anatomy of a Custom MCP Server
My MCP server is a single Python file using the MCP SDK. Each production service gets its own instance, parameterized by project root and process name. Here's the full toolbox:
┌──────────────────────────────────────────────────┐
│ MCP PROJECT SERVER │
│ 24 tools · 6 categories │
├──────────────┬───────────────────────────────────┤
│ CODE READ │ read_file (with line #s) │
│ │ list_files (glob patterns) │
│ │ search_code (ripgrep regex) │
│ │ get_project_structure (dir tree) │
├──────────────┼───────────────────────────────────┤
│ CODE WRITE │ edit_file (search & replace) │
│ │ write_file (create/overwrite) │
│ │ delete_file │
│ │ create_directory │
├──────────────┼───────────────────────────────────┤
│ PM2 PROCESS │ get_status (CPU, mem, uptime) │
│ │ view_logs (last N lines) │
│ │ restart_process │
│ │ stop_process │
│ │ start_process │
├──────────────┼───────────────────────────────────┤
│ GIT │ git_status │
│ │ git_diff │
│ │ git_log │
│ │ git_pull │
│ │ git_commit │
│ │ git_add │
├──────────────┼───────────────────────────────────┤
│ TESTING │ run_tests (autodetect runtime) │
│ │ check_health (HTTP status check) │
├──────────────┼───────────────────────────────────┤
│ CONTEXT │ read_claude_md (project docs) │
│ │ get_dependencies (pkg/req files) │
│ │ run_command (shell, with timeout) │
└──────────────┴───────────────────────────────────┘
Every tool has hard constraints baked into the server code, not into the prompt:
edit_file requires old_text to match exactly once in the file. If it's ambiguous, the tool returns an error — the model cannot apply a vague edit.
read_file caps at 500 lines and 500KB — the model can't accidentally dump a 10MB log into context.
run_command has a blocklist of 13 substrings + 5 regex patterns (path traversal, fork bombs, curl|bash piping, DROP TABLE, etc.).
All tools are sandboxed to the project directory — path traversal with ../../ is blocked at the server level.
These constraints would normally be paragraphs in your system prompt that the model might ignore under pressure. As MCP server logic, they are enforced by code, not by hope.
How MCP Tools Reduce Token Consumption
Let's trace a real operation: "Find where producto.precio is used and check if there's a null safety issue."
Without MCP tools (raw prompt approach):
TURN 1 — User prompt:
"Search the codebase for producto.precio usage" (9 tokens)

TURN 1 — Model output:
"I'll search for that pattern. Let me run:
grep -rn 'producto.precio' src/" (22 tokens generated)

TURN 2 — Execution result injected:
raw grep output, 40 lines

TURN 2 — Model output:
"I found it in 3 files. Let me read ventas.js:
cat -n src/routes/ventas.js | head -60" (28 tokens generated)

TURN 3 — Execution result injected:
60 lines of code

TURN 3 — Model output:
"Line 45 has no null check. Here's the fix..." (50 tokens)

TOTAL: ~809 tokens across 3 turns
With MCP tools:
TURN 1 — Model calls tool:
search_code(pattern="producto\.precio", glob="*/.js")
→ Tool returns structured matches (~120 tokens)

TURN 1 — Model calls tool:
read_file(path="src/routes/ventas.js", offset=40, limit=10)

→ Tool returns 10 lines with numbers (~80 tokens)

TURN 1 — Model output:
"Line 45 has no null check. Here's the fix..." (50 tokens)

TOTAL: ~250 tokens in 1 turn
3.2x fewer tokens. 1 turn instead of 3. No generated bash commands. No raw output parsing.
The savings compound across every execution. With structured tool responses, the model receives exactly the data it needs in a predictable format no wasted tokens on grep headers, bash syntax, or conversational padding.
The multiplier effect at scale
Monthly executions: 30,000
Tokens saved per exec: ~550 (809 - 250)
Total tokens saved/month: 16,500,000

At Claude Sonnet API rates ($3 input / $15 output per MTok):
Savings ≈ $150-$300/month just from token compression

At GPT-4o rates ($2.50 / $10):
Savings ≈ $100-$200/month
This is before you factor in the flat subscription model. MCP tools reduce costs on API AND subscription plans on subscriptions because you consume less of your rate-limited quota per operation.
The Cost Equation: Why Flat Beats Per-Token for Agents
My agent runs on claude -p (Claude Code CLI) using a Max subscription at $100/month. No API key. No per-token billing. The CLI invokes Claude with native MCP support it reads mcp-projects.json, connects to the specified servers via stdio, and exposes all tools to the model automatically.
Here's what this looks like compared to API pricing for a moderately active agent (1,000 daily executions, ~2,600 tokens each):
MONTHLY COST COMPARISON — 30,000 executions/month
═══════════════════════════════════════════════════

$100 ██ Claude Max (flat)

$390 ████████ GPT-4o API ($2.50/$10 per MTok)

$408 ████████ Gemini 3.1 Pro ($2.00/$12)

$441 █████████ GPT-5.2 API ($1.75/$14)

$540 ███████████ Claude Sonnet 4.6 API ($3/$15)

$900 ██████████████████ Claude Opus 4.6 API ($5/$25)
The flat model wins by 4-9x. But the real insight is: MCP tools make the flat model even flatter. Because each execution consumes fewer tokens (thanks to tool compression), you fit more executions within the same rate-limited window.
One developer tracked 10 billion tokens of Claude Code usage over 8 months and estimated it would have cost over $15,000 on API pricing. He paid ~$800 total on the Max plan. That's a 93% saving before any MCP optimization.
Dynamic MCP config: only load what you need
Here's an optimization most people miss. Instead of loading all 6 MCP servers (one per project) into every execution, my agent generates a mini-config with only the target project's server:
// claude-runner.js
function generarMiniConfig(proyecto) {
const serverKey = PROYECTOS[proyecto].mcp;
return {
mcpServers: {
[serverKey]: fullConfig.mcpServers[serverKey]
}
};
}
Why does this matter? Because every MCP server loaded = tool schemas injected into context = tokens consumed. If you have 6 servers × 24 tools = 144 tool definitions in context, that's a significant chunk of your prompt budget wasted on tools the model won't use in this execution.
Loading only the relevant server keeps the tool context tight: 24 tools instead of 144. That's ~80% reduction in tool-schema tokens per execution.
MCP as a Code Optimization Pattern
Beyond cost and hallucination, custom MCP tools change how you structure agent code. Here are three patterns I've found most impactful:
Pattern 1: Constraint enforcement via tool design
Instead of writing in your prompt "never edit more than 3 files in a single operation", design the tool to enforce it:
@server.tool()
async def edit_file(path: str, old_text: str, new_text: str) -> str:
"""Edit a file using exact search and replace.
old_text must match exactly ONE location in the file.
If old_text appears 0 or 2+ times, the edit is rejected."""

content = read(path)
count = content.count(old_text)
if count == 0:
    return "ERROR: old_text not found in file"
if count > 1:
    return f"ERROR: old_text found {count} times. Be more specific."

new_content = content.replace(old_text, new_text, 1)
write(path, new_content)
return f"OK: replaced 1 occurrence in {path}"

The constraint is impossible to bypass through prompt manipulation. No amount of creative prompting will make edit_file accept an ambiguous edit.
Pattern 2: Context injection via tool responses
Your read_claude_md tool is not just "reading a file." It's injecting project-specific context into the model's reasoning window at exactly the right moment:
@server.tool()
async def read_claude_md() -> str:
"""Read the project's CLAUDE.md documentation.
Contains architecture decisions, conventions,
known issues, and deployment notes.
Call this BEFORE making changes to understand project context."""

claude_md = project_root / "CLAUDE.md"
if claude_md.exists():
    return claude_md.read_text(encoding="utf-8")[:5000]
return "No CLAUDE.md found for this project."

That docstring "Call this BEFORE making changes" is a native prompt. The model reads it as part of the tool schema and learns when to use the tool, not just how. You didn't write this timing instruction in your system prompt. The tool teaches it.
Pattern 3: One server, N projects
The most powerful code optimization: my entire MCP server is one Python file parameterized by CLI arguments.

Same server.py, different instances

python server.py --root C:\projects\api --pm2 tacos-api --name api
python server.py --root C:\projects\bot --pm2 TacosAragon --name bot
python server.py --root C:\projects\cfo --pm2 cfo-agent --name cfo
Adding a new project to the agent requires zero new code. Three config lines:
"project-new": {
"command": "python",
"args": ["server.py", "--root", "C:\new-project", "--pm2", "new-svc", "--name", "new"]
}
Restart. The agent now has full read/write/git/process/test capabilities over the new project. 24 tools, zero development time.
This is the "N×M problem" that MCP was designed to solve. Without it, adding a new project would mean writing new integration code — bash scripts, API wrappers, custom parsers. With MCP, the protocol is the integration layer.
Sessions: The Forgotten Token Optimization
MCP tools compress tokens per execution. But sessions compress tokens across executions.
My agent uses --session-id UUID to maintain context for 1 hour across up to 8 messages. Here's what this saves:
WITHOUT SESSIONS:
Message 1: system prompt (200 tok) + tool schemas + task → response
Message 2: system prompt (200 tok) + tool schemas + task → response
Message 3: system prompt (200 tok) + tool schemas + task → response
Message 4: system prompt (200 tok) + tool schemas + task → response

Total system prompt tokens: 800+ (repeated 4 times)
Context from previous messages: 0 (each starts fresh)

WITH SESSIONS:
Message 1: system prompt (200 tok) + tool schemas + task → response
Message 2: task only → response (has full prior context)
Message 3: task only → response (has full prior context)
Message 4: task only → response (has full prior context)

Total system prompt tokens: 200 (loaded once)
Context from previous messages: everything
The model remembers files it read, changes it made, and errors it encountered without re-sending any of it. For a sequence of related operations (diagnose → fix → verify → report), sessions eliminate ~600 tokens of redundant context per follow-up message.
Over 30,000 monthly executions with an average session length of 3 messages, that's roughly 12 million tokens saved tokens that never enter the context window, never count against your rate limit, and never cost you a cent.
The Blocklist: What Your MCP Server Should Never Allow
If you're building MCP tools that execute code or commands, here's the blocklist I arrived at after running in production:
BLOCKED_SUBSTRINGS = [
"rm -rf /", "rm -rf ~", # filesystem destruction
"format", "del /s /q", # Windows destruction
"rmdir /s /q", # Windows recursive delete
"shutdown", "reboot", # system control
"halt", "poweroff", # system control
":(){:|:&};:", # fork bomb
"DROP TABLE", # database destruction
"chmod 777", # permission escalation
"chown -R", # ownership takeover
]

BLOCKED_PATTERNS = [
r"curl.|\s(bash|sh|python|node)", # remote code exec
r"wget.|\s(bash|sh)", # remote code exec
r"(bash|sh)\s+<(", # process substitution
r"eval\s+\$(", # eval injection
r"../../../..", # path traversal
]
These are not prompt instructions. They are server-side enforcement that the model cannot circumvent regardless of prompt injection, jailbreaking, or hallucination. The run_command tool checks every command against this list before execution and returns a hard error if any pattern matches.
Could a determined attacker find ways around these? Maybe. But the point is that the defense doesn't depend on the model behaving correctly. It's code, not a suggestion.
Key Takeaways

Every MCP tool is a native prompt. Tool schemas carry documentation that the model reads automatically. Move instructions from your system prompt into tool definitions they're cheaper, more precise, and structurally enforced.
Tool constraints beat prompt constraints. "Never edit ambiguously" as a prompt instruction is a suggestion. edit_file rejecting non-unique matches is a guarantee. Put your guardrails in server code, not in prose.
MCP tools compress tokens 3x. Structured tool calls replace multi-turn bash generation, raw output parsing, and conversational overhead. The savings compound at scale.
Dynamic MCP config saves context budget. Load only the servers relevant to the current task. 24 tools in context instead of 144 is an 80% reduction in schema tokens.
Sessions are the multiplier. Token compression per-execution (MCP tools) × token elimination across-executions (sessions) = dramatic reduction in total consumption. This is the compounding effect that makes the flat subscription model viable at high volume.
One server, N projects. Parameterize your MCP server by project root and process name. Adding a new project should be a config change, not a code change.
The flat subscription changes everything. At 30,000 executions/month, a $100 flat plan is 4-9x cheaper than any per-token API. MCP tools amplify this advantage by fitting more operations into the same rate-limited window. Build your tools once. Reuse them everywhere. Let the protocol do the integration work. The Stack MCP Server: Python + MCP SDK (24 tools, single file, parameterized per project) Agent runtime: claude -p (Claude Code CLI, Max plan, Sonnet model) Protocol: MCP over stdio (JSON-RPC 2.0) Sessions: --session-id / --resume (1-hour context retention) Config: Dynamic per-execution mini-config (only target project's server)

I'm Gumaro González. I run a restaurant in Culiacán, México and I build the software behind it from the WhatsApp order bot to the autonomous agent infrastructure. Everything built with Claude Code as my copilot.

GitHub: github.com/Gumagonza1

claude_runner — how I eliminated Claude API costs by using the subscription I was already paying for

Gumaro Gonzalez — Mon, 23 Mar 2026 09:16:34 +0000

For months I was paying for Claude twice. The monthly subscription and the API tokens every time an agent made a call.
Turns out I didn't have to.
The problem
When you import the Anthropic SDK directly, every token gets billed:

This charges per token consumed

from anthropic import Anthropic
client = Anthropic(api_key="sk-...")
response = client.messages.create(...)
1,000 fiscal document analyses per month with Sonnet: between $25 and $80 USD on top of what you already pay for the subscription. And that scales linearly with every new agent you add to the system.
The discovery
Claude Code CLI has an authentication hierarchy that almost nobody documents:

CLAUDE_CODE_USE_BEDROCK / USE_VERTEX (cloud providers)
ANTHROPIC_AUTH_TOKEN (proxies / gateways)
ANTHROPIC_API_KEY ← per-token billing starts here
apiKeyHelper script (rotating credentials)
~/.claude/.credentials.json ← your Max subscription lives here When you run claude login, the CLI stores an OAuth token at ~/.claude/.credentials.json. That token is exactly the same one your interactive terminal uses. If there is no ANTHROPIC_API_KEY defined in the environment, the CLI falls back to position 5 and uses your subscription session. claude -p spawned as a subprocess from your code does the same thing. No API key. No additional invoice. What claude_runner is It's a module that acts as a bridge between agents and Claude, using claude -p as a subprocess instead of the SDK. It exists in two versions: tacos-aragon-fiscal/src/claude_runner.py ← Python, fiscal document analysis pmo-agent/claude-runner.js ← JavaScript, production agent Both do the same thing: spawn the claude -p process, parse the output, and return the response to the calling agent. No secrets in the code. No environment variable that can leak into logs. Python implementation (79 lines) The Python version is minimal. No external dependencies beyond the standard library. """ claude_runner.py — No API key, no per-token costs. Replaces direct Anthropic SDK calls. """

import subprocess, sys, os, tempfile

CLAUDE_TIMEOUT = 300 # 5 minutes default

def run(system_prompt: str, user_message: str,
model: str = "sonnet",
max_budget: float = 2.0,
timeout: int = CLAUDE_TIMEOUT,
session_id: str | None = None) -> str:

full_prompt = f"=== INSTRUCTIONS ===\n{system_prompt}\n\n=== TASK ===\n{user_message}"

tmp = tempfile.NamedTemporaryFile(mode='w', suffix='.txt',
                                  delete=False, encoding='utf-8')
tmp.write(full_prompt)
tmp.close()

try:
    cmd = (
        f'type "{tmp.name}" | claude -p'
        f' --output-format text'
        f' --model {model}'
        f' --permission-mode bypassPermissions'
        f' --max-budget-usd {max_budget}'
    )
    if session_id:
        cmd += f' --session-id {session_id}'

    comspec = os.environ.get('COMSPEC', r'C:\Windows\system32\cmd.exe')
    result = subprocess.run(
        [comspec, '/c', cmd],
        capture_output=True, text=True,
        timeout=timeout, encoding='utf-8', errors='replace'
    )

    if result.returncode != 0:
        raise RuntimeError(f"Claude error: {result.stderr}")

    return result.stdout.strip()

finally:
    os.unlink(tmp.name)

Why a temp file instead of passing the prompt directly? Windows has a ~32,767 character limit on command-line arguments. Fiscal analysis prompts exceed that regularly. The temp file is the reliable solution.
JavaScript implementation (with stream-json)
const { spawn } = require('child_process');
const crypto = require('crypto');
const fs = require('fs');
const os = require('os');
const path = require('path');

let _running = false; // Anti-reentrance guard

async function runClaude({ promptFile, userPrompt, projectName }) {

if (_running) {
return { ok: false, error: 'Execution already in progress' };
}
_running = true;

const mcpConfig = getMcpConfigForProject(projectName);
const { sessionId, isNew } = getOrCreateSession(projectName);

const finalPrompt = isNew
? ${await fs.promises.readFile(promptFile, 'utf8')}\n\n${userPrompt}
: userPrompt;

const tmpId = crypto.randomBytes(4).toString('hex');
const tmpPrompt = path.join(os.tmpdir(), pmo-prompt-${tmpId}.txt);
const tmpBat = path.join(os.tmpdir(), pmo-run-${tmpId}.bat);

await fs.promises.writeFile(tmpPrompt, finalPrompt, 'utf8');

const batContent = [
'@echo off',
type "${tmpPrompt}" | claude -p ^,
--output-format stream-json ^,
--model sonnet ^,
--mcp-config "${mcpConfig}" ^,
--strict-mcp-config ^,
--permission-mode bypassPermissions ^,
--max-turns 20 ^,
--max-budget-usd 2.00 ^,
--session-id ${sessionId}
].join('\r\n');

await fs.promises.writeFile(tmpBat, batContent, 'utf8');

return new Promise((resolve) => {
let finalOutput = '';
let watchdog;

const resetWatchdog = () => {
  clearTimeout(watchdog);
  watchdog = setTimeout(() => {
    proc.kill();
    resolve({ ok: false, error: 'Inactivity timeout' });
  }, 5 * 60 * 1000);
};

const proc = spawn('cmd.exe', ['/c', tmpBat]);

proc.stdout.on('data', (chunk) => {
  resetWatchdog();
  for (const line of chunk.toString().split('\n')) {
    if (!line.trim()) continue;
    try {
      const event = JSON.parse(line);
      processStreamEvent(event, (output) => { finalOutput = output; });
    } catch { /* non-JSON line, ignore */ }
  }
});

proc.on('close', async (code) => {
  clearTimeout(watchdog);
  _running = false;
  await Promise.allSettled([
    fs.promises.unlink(tmpPrompt),
    fs.promises.unlink(tmpBat)
  ]);
  resolve({ ok: code === 0, output: finalOutput, exitCode: code, sessionId });
});

resetWatchdog();

});
}
The stream-json event parser
function processStreamEvent(event, onResult) {
switch (event.type) {

case 'system':
  console.log(`🔌 MCP: ${event.mcp_servers.map(s => s.name).join(', ')}`);
  break;

case 'assistant':
  for (const block of event.message.content) {
    if (block.type === 'thinking') console.log(`💭 ${block.thinking}`);
    if (block.type === 'tool_use') console.log(`🔧 ${block.name}`);
    if (block.type === 'text')     console.log(`💬 ${block.text}`);
  }
  break;

case 'result':
  onResult(event.result);
  // cost_usd is informational in Plan Max — not a real charge
  console.log(`💰 Equivalent cost: $${event.cost_usd.toFixed(4)}`);
  break;

}
}
Why stream-json instead of text? With text the process looks frozen until it finishes. With stream-json the inactivity watchdog can tell Claude is still working because each tool_use event resets the timer. Five minutes without any event means something went wrong.
The three decisions that make it work in production

Anti-reentrance guard Without _running, the same error can trigger the agent twice in a row. Two Claude instances operating on the same codebase simultaneously is a race condition that ends badly.
Dynamic MCP config per project Instead of loading the global config with all servers in the ecosystem, the runner generates a minimal JSON before each execution: { "mcpServers": { "project-tacos-bot": { "command": "python", "args": ["C:/servers/tacos-bot-mcp/index.py"] } } } If you load 6 MCP servers with 24 tools each when you only need 24 tools from one of them, you are injecting the schema of 144 tools into the context. More input tokens, slower execution, and Claude has to ignore tools it will never use.
Session management per project Each project gets a session UUID with a 1-hour TTL and an 8-message limit: const SESSION_TTL_MS = 60 * 60 * 1000; const SESSION_MAX_MESSAGES = 8;

function getOrCreateSession(projectName) {
const now = Date.now();
const existing = activeSessions.get(projectName);

if (existing &&
(now - existing.createdAt) < SESSION_TTL_MS &&
existing.messages < SESSION_MAX_MESSAGES) {
return { sessionId: existing.sessionId, isNew: false };
}

const sessionId = crypto.randomUUID();
activeSessions.set(projectName, { sessionId, createdAt: now, messages: 0 });
return { sessionId, isNew: true };
}
On an active session, the prompt skips the instructions. Claude remembers them from the first message of the session. On a new session, they go in full. The difference in input tokens is significant when the system prompt is long.
The trap to avoid
If at any point you define ANTHROPIC_API_KEY in the server environment, the CLI detects it at position 3 in the hierarchy and starts billing per token with no warning. The runner stops using the subscription without you noticing.

Check before going to production

echo $ANTHROPIC_API_KEY

If this returns anything, there is a problem

unset ANTHROPIC_API_KEY
That variable must not exist in the environment where the agent runs.
The cost_usd field is not a charge
The result event in the stream-json output includes a cost_usd field. That number shows what it would cost if you were in API mode. In Plan Max it is not deducted from any balance and generates no billing.
I log it as an efficiency reference to know exactly how much I am saving per execution and to catch if a call is consuming more context than expected.
Cost comparison
Setup
Per execution
500 analyses/month
1,000/month
Sonnet SDK direct
~$0.047
~$23
~$47
GPT-4o API direct
~$0.039
~$19
~$39
claude_runner Plan Max
$0.00
$0.00
$0.00
Break-even against Plan Max at $200/month: 71 executions per day. After that point, the API costs more than the full plan.
What runs in production
tacos-aragon-fiscal (Python): downloads CFDIs from Mexico's SAT tax authority, parses the fiscal XML, calculates taxes, and detects inconsistencies between declared income and actual sales.
pmo-agent (JavaScript): detects errors in production processes, proposes fixes ordered by impact, waits for Telegram approval, applies changes, commits, restarts PM2, and reports exactly what it did. If something ends up worse than before, it runs git checkout automatically.
aragon-git-guardian: intercepts every git push, scans the repo with grep across 10 security categories, and if it finds anything calls claude_runner with the specific evidence for contextual analysis. No AI when there are no findings, no cost when the repo is clean.
Monthly cost for all these agents combined: $0 additional on top of the subscription.
How to replicate it

1. Install and authenticate Claude Code

npm install -g @anthropic-ai/claude-code
claude login

2. Verify there is no API key in the environment

unset ANTHROPIC_API_KEY
echo $ANTHROPIC_API_KEY # should be empty

3. Test that the CLI uses the subscription

claude -p "respond with just: ok"

Should respond without asking for an API key

After that: spawn claude -p as a subprocess with spawn (Node.js) or subprocess (Python), parse the stream-json, and manage the process lifecycle.
The highest-impact decision is writing your own MCP server instead of using generic third-party MCPs. Your own context is cleaner, uses fewer tokens, and Claude enters the session already knowing how your system is built.

PMO Agent repo: github.com/Gumagonza1/pmo-agent

Claude_runner repo:https://github.com/Gumagonza1/claude-runner

Self-healing server article: dev.to/gumagonza1/i-built-a-self-healing-production-server-using-claude-code-no-api-key-no-extra-cost-1eoo

I Built a Self-Healing Production Server Using Claude Code — No API Key, No Extra Cost

Gumaro Gonzalez — Sun, 22 Mar 2026 08:11:17 +0000

How a restaurant operator in México built an autonomous AI agent that reads logs, fixes bugs, restarts services, and reports back — all from a Telegram message, using a $100/month plan.

The Problem

I run six production services on a Windows Server 2022 VM in GCP. A WhatsApp bot, a REST API, a CFO fiscal agent, a Telegram dispatcher, a portfolio site, and a monitor. When something breaks at 2 AM, I either wake up to fix it or it stays broken until morning.

I wanted autonomous self-correction. Every solution I found required either:

An expensive enterprise platform (Salesforce Agentforce, PagerDuty + AI add-ons)
A complex LangChain/CrewAI setup with its own API key billing
Or it was a demo that didn't survive contact with production

I already had Claude Code on the Max plan ($100/month). I was using it as my daily coding copilot. Then I realized: claude -p runs Claude non-interactively. It accepts a system prompt. It connects to MCP servers. And it uses my existing session — no API key, no extra cost.

That was the insight that made everything else possible.

The Architecture

The PMO Agent (Project Management Operations Agent) is the only component in my ecosystem capable of modifying code in production. It connects three systems:

ADMIN (Telegram)
    !pmo tacos-api: fix the null check in ventas.js
         ↓
telegram-dispatcher (PM2)
         ↓
mensajes.db (SQLite WAL — shared queue)
         ↓
PMO Agent — polls every 10 seconds
         ↓
claude -p (Plan Max, no API key)
         ↓
MCP Project Server (Python, 24 tools per project)
         ↓
Read logs → Edit files → Restart PM2 → Verify → Report
         ↓
Telegram ← "Fixed. Null check added at line 45. Service online, 0 errors in last 15s."

The key principle: claude -p invokes Claude Code CLI in non-interactive mode. It uses the authenticated Max subscription of the user — the same session that powers your interactive terminal. There is no second API call. There is no token billing. The same $100/month that covers your daily coding covers your autonomous production agent.

The MCP Server: 24 Tools in 6 Categories

Each project gets its own instance of a Python MCP server. Claude connects to exactly the right project's tools — no cross-contamination, no blast radius beyond the target service.

1,064 lines of Python. 38.5 KB. 24 tools.

Category	Count	Tools
Read	4	`read_file`, `list_files`, `search_code`, `get_project_structure`
Write	4	`write_file`, `edit_file`, `delete_file`, `create_directory`
Git	6	`git_status`, `git_diff`, `git_log`, `git_pull`, `git_commit`, `git_add`
PM2	5	`get_status`, `view_logs`, `restart_process`, `stop_process`, `start_process`
Testing	2	`run_tests`, `check_health`
Context	3	`read_claude_md`, `get_dependencies`, `run_command`

The edit_file tool is the most critical. It works as a strict search-and-replace: it finds old_text exactly in the file and replaces it with new_text. If old_text is not unique in the file, it fails and asks for more context. This prevents accidental edits. Claude cannot blindly overwrite files — it must identify the exact code it wants to change.

Each MCP server is invoked with --strict-mcp-config, meaning Claude only sees the tools for the target project. Nothing else.

Two Modes of Operation

Mode 1: Admin Instruction via Telegram

You send a message prefixed with !pmo:

!pmo tacos-api: add a GET /health endpoint that returns { status: "ok" }
!pmo bot: change the welcome message to "Hola, qué vas a ordenar?"
!pmo cfo-agent: fix the bug where it doesn't parse DD/MM/YYYY dates

Telegram shortcuts with autocomplete (15 commands) make this feel like a native interface:

/pmo_api   → targets tacos-api
/pmo_bot   → targets TacosAragon WhatsApp bot
/pmo_cfo   → targets cfo-agent
/pmo_telegram → targets telegram-dispatcher

Mode 2: Autonomous Autocorrection

When the monitor detects a repeated error, it enqueues an autocorrect message:

AUTOCORRECT|tacos-api|TypeError: Cannot read property "precio" of undefined at src/routes/ventas.js:45

The PMO Agent picks this up and executes a full repair cycle without any human input:

Diagnose — reads logs, reads the file with the error, searches the codebase for the pattern
Analyze — identifies the exact line, classifies severity (CRITICAL/HIGH/MEDIUM/LOW)
Fix — applies the minimum change using edit_file, never refactors, preserves style
Verify — restarts the process, waits 10 seconds, checks logs and HTTP health endpoint
Report — sends a structured Telegram message (max 4,000 chars)

Example autocorrect report:

AUTOCORRECT [tacos-api] — SUCCESS
Error: TypeError at src/routes/ventas.js:45
Cause: variable "producto" can be null when item is out of stock
Fix: added null check before accessing .precio
Verification: service online, 0 errors in last 15s

Session Context: The Feature Most Builders Miss

Each admin session shares context for 1 hour. Claude remembers everything it has read, every change it has made, every project it has touched — across multiple messages.

10:00  !pmo tacos-api: explain the architecture
       → NEW SESSION (expires 11:00). Claude reads files, responds.

10:05  !pmo tacos-api: add a /health endpoint
       → CONTINUES session (msg #2). Claude already knows the architecture.
       → Edits code, restarts, verifies.

10:12  !pmo cfo-agent: what endpoints does it have?
       → SAME session (msg #3). Claude remembers tacos-api AND reads cfo.

10:20  !pmo tacos-api: write the test for /health
       → SAME session (msg #4). Knows exactly what it built.

11:01  !pmo bot: add RFC validation
       → Session expired. NEW SESSION starts.

Implementation: first call uses --session-id UUID (creates a session on disk). Subsequent calls use --resume UUID (resumes with full context). After 1 hour, UUID expires and a new one is generated.

This is not available in any LangChain tutorial. It's a Claude Code CLI feature that most people using it interactively don't know exists.

The Security Model: 4 Concentric Layers

Autonomous code execution is dangerous. Every layer fails independently.

Layer 1: MCP Server (per project)

Path traversal blocked — .. cannot escape the project directory
Sensitive files blocked — .env, *.pem, *.key, credentials.json
Binaries excluded — images, executables, databases not readable or editable
Dangerous commands filtered — rm -rf /, format, shutdown, reboot
Size limits — 500KB per file, 500 lines per output

Layer 2: PMO Agent

1 concurrent execution maximum — no overlapping corrections
5-minute cooldown between corrections on the same service
10-minute timeout per Claude execution
Full audit trail in pmo_ejecuciones table

Layer 3: System Prompt (`autocorrect.md`)

NEVER modifies .env, credentials, or production configuration
NEVER installs unknown packages
If root cause not identified with certainty: report only, don't touch code
If fix fails: revert with git checkout, report FAILURE
Maximum 3 files modified per correction

Layer 4: Claude CLI

Budget cap: $2.00 per execution (failsafe against token loops)
Model: Sonnet (fast, economical for corrections)
--strict-mcp-config — only uses configured MCP servers, ignores others
1-hour sessions — shared context per conversation, auto-expires

Real Production Data

The system has been running since March 21, 2026. Here is the unfiltered data from pmo_ejecuciones:

Execution Summary

Metric	Value
Total executions	9
Completed (success)	7 (78%)
Infrastructure errors	2 (bugs in the PMO itself, now fixed)
Claude errors	0
Real success rate	100% (7/7 when Claude ran)

The 2 failures were bugs in my infrastructure code — the PMO dispatcher, not Claude. When Claude actually executed, it succeeded every single time.

Execution Timeline (March 21, 2026)

#	Project	Status	Duration	Time
1	tacos-api	completed	11s	9:46 PM
2	TacosAragon	error_infra	0s	9:59 PM
3	TacosAragon	completed	107s	10:06 PM
4	TacosAragon	completed	n/a	10:32 PM
5	TacosAragon	error_infra	180s	10:38 PM
6	TacosAragon	completed	408s	10:46 PM
7	TacosAragon	completed	600s	11:00 PM
8	TacosAragon	completed	123s	11:16 PM
9	TacosAragon	completed	600s	11:22 PM

Resolution Time

Metric	Value
Average	308s (~5 min)
Minimum	11s
Maximum	600s (~10 min)

Token Consumption (per execution)

Component	Characters	Approx. Tokens
System prompt	~1,800	~500
User prompt	~400	~110
MCP tool calls (read ~5 files)	~50,000	~13,000
MCP tool results (code read)	~80,000	~21,000
Total input		~34,600
Response (output)	~2,651	~700

Note: Token counts are approximate estimates based on character counts. Claude Code does not expose exact token counts for claude -p executions.

Database Footprint

Table	Rows
mensajes_queue	110
mensajes_responses	31
pmo_ejecuciones	9
mensajes.db total size	84 KB

At this rate: ~10,000 executions before reaching 1 MB. The entire ecosystem's operational data fits in a text file.

The Cost Comparison

Using real token data (14,830 input / 193 output per execution):

Platform	Cost/execution	Cost at 30 exec/day × 30 days	Annual
GPT-4o API ($2.50/M in, $10/M out)	$0.039	$35.85/month	$430/year
Claude Sonnet API ($3/M in, $15/M out)	$0.047	$42.50/month	$510/year
Plan Max	$0.000	$100/month	$1,200/year

Break-even point:

vs GPT-4o: Max becomes cheaper at 84+ executions/day
vs Sonnet API: Max becomes cheaper at 71+ executions/day

At 30 executions/day, the raw API cost is lower than Max. So why Max?

Because the PMO Agent is not the only thing running. The same $100/month also covers:

All interactive Claude Code sessions (my daily coding copilot)
The aragon-git-guardian security hook on every git push
All Skills, CLAUDE.md hierarchies, and custom slash commands
Any other claude -p automation I add

Break-even point: at ~71 Sonnet API executions/day, Max becomes cheaper than raw API billing. Everything below that is a bonus that comes included.

The real financial argument is not the PMO alone. It's that for a solo operator running 6 production services, the $100/month Max plan functions as an entire DevOps + QA + on-call engineering layer.

What This Is Not

This is not a prototype. It is not a tutorial with TODO: add real logic here. The system ran 9 times in one evening, resolved real tasks on real production code, and left an audit trail in a SQLite database.

It is also not a replacement for proper SRE practices. Circuit breakers, cooldowns, budget caps, and human-in-the-loop escalation exist precisely because autonomous agents fail in unexpected ways. The system is designed to operate safely within defined boundaries and escalate outside them.

What Surprised Me

After building this, I searched for prior art. I found:

Telegram + Claude Code bridges — several repos, all require a separate API key
Self-healing infrastructure — enterprise frameworks (VIGIL, AIOps) costing orders of magnitude more
PMO-style agents — LangChain tutorials, demo-quality, no production data

I did not find a single documented implementation of claude -p as a production autocorrection engine, with per-project MCP servers, session persistence, and a 4-layer security model — running on a Max subscription without a separate API key.

The capability was there. The documentation was not.

The full implementation is open source: github.com/Gumagonza1/pmo-agent

The Stack

pmo-agent/
├── index.js              # PM2 process: polls SQLite every 10s
├── claude-runner.js      # Wrapper for claude -p (spawn + timeout)
├── config.js             # Project map, paths, timings
├── mcp-projects.json     # MCP config for claude -p
├── prompts/
│   ├── autocorrect.md    # System prompt: autonomous correction
│   └── pmo-instruction.md # System prompt: admin instructions
└── state/               # Cooldown state per service

mcp-project-server/
└── server.py             # 1,064 lines, 24 tools, 38.5 KB

telegram-dispatcher/
└── index.js             # Recognizes !pmo prefix, writes to SQLite

mensajes.db              # SQLite WAL, shared queue, 84 KB total

Configuration (config.js):

Parameter	Value	Description
POLL_INTERVAL_MS	10,000	SQLite polling frequency
VERIFY_WAIT_MS	15,000	Wait after fix before verifying
CLAUDE_TIMEOUT_MS	600,000	10-minute max per Claude execution
MAX_CONCURRENT	1	No overlapping executions
COOLDOWN_MS	300,000	5-minute cooldown per service

Managed projects:

Project	PM2 Name	Port	Critical
TacosAragon	TacosAragon	3003	Yes
MonitorBot	MonitorBot	—	Yes
tacos-api	tacos-api	3001	Yes
telegram-dispatcher	telegram-dispatcher	—	No
cfo-agent	cfo-agent	3002	No
portfolio-aragon	portfolio-aragon	—	No

Adding a New Project (3 Steps)

// Step 1: config.js
'nuevo-proyecto': {
  mcp: 'project-nuevo',
  root: 'C:\\ruta\\al\\proyecto',
  pm2: 'nombre-en-pm2',
  puerto: 3005,
  critico: true,
}

// Step 2: mcp-projects.json
"project-nuevo": {
  "command": "python",
  "args": [
    "C:\\...\\mcp-project-server\\server.py",
    "--root", "C:\\ruta\\al\\proyecto",
    "--pm2", "nombre-en-pm2",
    "--name", "nuevo"
  ]
}

# Step 3
pm2 restart pmo-agent

A Real Fix: What Claude Actually Did

Theory is easy. Here is a specific production fix the PMO Agent diagnosed and applied on March 21, 2026.

The problem: TacosAragon (the WhatsApp ordering bot) was producing imprecise responses. The monitor flagged degraded quality in Gemini's outputs.

The PMO's diagnosis:

Causa principal: El menú CSV con UUIDs inyectaba ~25,000 chars de ruido al contexto de Gemini, degradando la precisión. Contexto total estimado bajó de ~76,500 a ~53,000 chars (-30%).

Translation: the menu being sent to Gemini included raw UUID identifiers from the Loyverse POS system — ~25,000 characters of noise the model didn't need. This was bloating the context by 30% and degrading response quality.

Three fixes applied autonomously to bot-tacos/index.js:

Fix 1 — menuParaIA() (line 211): Added UUID filtering before sending menu CSV to Gemini. Eliminated ~25,000 characters of irrelevant identifiers from the context.

Fix 2 — temperature reduction (lines 246, 262): Lowered from 0.5 to 0.3 to reduce hallucinations and improve ordering precision.

Fix 3 — MAX_HISTORIAL reduction (line 315): Reduced conversation history limit from 35,000 to 20,000 characters to prevent context overload in long sessions.

Result: Total context sent to Gemini dropped from ~76,500 to ~53,000 characters — a 30% reduction. Three targeted edits, no refactoring, code style preserved.

The Actual PMO Output

Here is the unedited message the PMO Agent sent to Telegram before applying any fix:

✅ PMO TacosAragon — Completed (123s)
🔗 Session: msg #1, 58min remaining

🔴 ROOT CAUSE: Menu CSV sent with UUIDs to Gemini

Each call includes full menuRaw (118 lines × 10 columns, 6 of them
36-char UUIDs):
agua-litro,10005,Agua cebada Litro,Bebidas,29,877e394e-...

Gemini receives ~25,000 chars of UUIDs it cannot use. This context
noise degrades instruction-following precision.

Fix: Filter menuRaw before injecting into the prompt.
function menuParaIA(csv) {
    return csv.split('\n').map((linea, i) => {
        if (i === 0) return 'Handle,Nombre,Categoria,Precio';
        const cols = linea.split(',');
        return [cols[0], cols[2], cols[3], cols[4]].join(',');
    }).join('\n');
}

🟡 History at 35,000 chars — reduce to 20,000
🟡 Model: Flash instead of Pro (line 243)
🟢 Temperature 0.5 — lower to 0.3

Context estimate:
  instrucciones.txt    ~12,000 chars
  menu.csv with UUIDs  ~28,000 chars
  History (max)        ~35,000 chars
  Profile + internal    ~1,500 chars
  TOTAL               ~76,500 chars
  With UUID fix       ~53,000 chars (-30%)

Shall I apply the fixes now?

Notice the last line: "Shall I apply the fixes now?"

The PMO Agent did not execute automatically. It read five files, identified four causes ordered by impact, calculated exact context sizes, wrote the implementation code, and then paused for confirmation before touching a single line of production code.

This is human-in-the-loop by design, not by accident. The system prompt instructs Claude to present the diagnosis and proposed changes before executing anything above a defined risk threshold. The agent has full capability to apply changes unilaterally — it has edit_file and restart_process tools available. The constraint is deliberate.

After receiving approval, it applied all three fixes, restarted the service, and the entire cycle completed in 123 seconds.

How the System Evolved: Before vs After

The initial version had significant issues. Here is the BEFORE/AFTER after one evening of debugging:

Aspect	Before	After
MCP servers per execution	6 (all loaded simultaneously)	1 (dynamic per project)
System prompt loading	Read from disk every time	Cached with mtime invalidation
Re-entrancy protection	None	Guard prevents duplicate execution
Orphan processes	Persisted after crashes	Auto-cleanup on exit
Execution timeout	3 minutes	20 minutes
Budget per execution	$0.50	$2.00
`procesado=1` timing	Set BEFORE execution	Set in `finally` (AFTER)
stderr handling	Ignored	Used as fallback if stdout empty

The most critical bug: procesado=1 was being set before Claude ran. If Claude failed or timed out, the message was marked as processed and never retried. Setting it in finally (always runs, regardless of success or failure) was a one-line fix that changed the entire reliability profile.

What I'm Building Next

aragon-ops-server — MCP tools for Loyverse (sales/inventory), Facturama (CFDI fiscal), and SQLite analytics. Claude will be able to query yesterday's sales or generate an invoice directly from a Telegram message.
Progressive cooldown backoff — 5min → 15min → 60min for repeated failures on the same service
Daily budget cap across all PMO executions
Daily ops report generated automatically every morning

Conclusion

The most valuable insight from this project is not about Claude. It is about the claude -p flag.

Most developers who use Claude Code use it interactively. They type, Claude responds, they review. But claude -p turns Claude Code into a callable function — a reasoning engine you can invoke programmatically, with MCP tool access, session persistence, and your existing subscription credentials.

No separate API key. No LangChain dependency. No new billing surface.

The PMO Agent is 9 executions old as of this writing. It has never made a code error. It fixed real bugs, added real features, and restarted real services — autonomously, from a Telegram message, on a phone, while I was doing something else.

If you are running production services on a Claude Code Max plan and you have not looked at claude -p, you are leaving a significant capability on the table.

Gumaro González is the owner and CTO of Tacos Aragón, a family restaurant in Culiacán, Sinaloa, México. He builds the Ecosistema Aragón — an AI-powered operations platform — as a solo developer since 2020.

GitHub: github.com/Gumagonza1
PMO Agent repo: github.com/Gumagonza1/pmo-agent
Live system: gumaro.dev.tacosaragon.com.mx