DEV Community: Alex LaGuardia

I broke my own governed MCP server by hand, then built the scanner that catches the class

Alex LaGuardia — Sat, 27 Jun 2026 23:18:44 +0000

A few weeks back I shipped Warden, a governance layer that sits in front of an MCP server and enforces who can read what. Role-based, field-level. The demo had a support role that could list customer accounts but never see their billing tier. The tier field is stripped from everything support gets back.

I was poking at it the way you poke at your own work when you don't quite trust it.. I tried this:

query_resource("accounts", {"tier": "Enterprise"})

Six rows came back. Acme Corp, Initech, Umbrella, Hooli, Stark, Wayne. The support role can't see the tier, but the query layer still accepted it as a filter. So you ask for every Enterprise account, and the ones that match tell you their tier by simply existing in the result. Redaction held on the output. It leaked through the input.

That's the bug. It's small and it's boring and it's exactly the kind of thing that ships.

Here's the part that bothered me more than the bug. I went and ran the MCP security scanners on it. The ones everyone uses now read the tool manifest: they look at the tool descriptions, grep for poisoned instructions, flag suspicious-looking metadata. Good tools. They all came back green. They have to. There is nothing wrong with the manifest. The query_resource tool description is honest. The bug only exists when the server runs and a real role makes a real call. A scanner that reads text can't reach it.

So I built the thing that can. It's called Siege.

Run the server, don't read it

Siege points at a live MCP server and behaves like an attacker against it, as real roles. No manifest grep. It connects as each identity you give it, and it diffs what comes back.

The wedge is runtime authorization. Static scanners own static tool-poisoning and they're fine at it; I'm not going to out-grep them. What nobody ships is a tool that exercises the running server as different users and tries to break access control. The RBAC vendors all say "you should red-team your authorization scope" as advice. Siege is that advice turned into a thing you run.

The hard rule I gave myself: no hardcoded field names, no hardcoded roles. If it only caught the Warden bug because I told it about tier, it would be a unit test, not a scanner. So the method is differential. Learn the schema and the real values from the most-permissive identity, the one that sees everything. Then for every restricted role, diff what it sees against that, and probe the gaps.

Four detectors came out of that, all role-relative:

Redacted-field filter leak. The Warden bug, generalized. For any field stripped from a role's output, try it as a filter. If filtering on it returns fewer rows than the baseline, the hidden value just leaked through the difference.
Row-scope escalation. A role whose normal view is scoped to a subset (region = West, say) tries an out-of-scope filter value. If region=East returns rows it shouldn't have, the filter ran against the full dataset instead of the scoped one.
ID enumeration. The list path is governed, the single-record lookup often isn't. So get_record on guessed ids walks straight past the scoping that query_resource enforces. Classic IDOR, MCP edition.
Forbidden-resource read. A role can't even list a resource, but get_record hands one over anyway. Access checked on list and query, forgotten on the by-id path.

The last three I never found by hand. they fell out of writing the first one generically.. build the engine for one bug and it pulls the next few with it.

The money shot

I keep two Warden builds: the vulnerable commit and the fixed one. Siege runs against both.

BEFORE — vulnerable Warden (4938bdf)
## 1. [HIGH] Redacted field 'tier' leaks through filter predicate on 'accounts'
   Found as role: support
   Reproduce: query_resource({"resource_type":"accounts","filters":{"tier":"Enterprise"}})
   baseline_count: 8   filtered_count: 6
   leaked_records: ['Acme Corp', 'Initech', 'Umbrella Co', 'Hooli', 'Stark Industries', 'Wayne Enterprises']

AFTER — fixed Warden (7188eed)
   No findings. The probed classes held.

VERDICT: PASS — Siege caught the bug and cleared the fix.

Every finding carries an exact, replayable repro: the tool, the arguments, the rows that came back. You can paste it into your own client and watch it leak. And to make sure the detectors aren't no-ops that pass everything, there's an intentionally-broken fixture server in the repo. Siege fires all four detectors on it, including the critical forbidden-resource read. it's in there if you want to watch it go.

The second class: did the agent actually get owned

Tool-poisoning is the attack everyone talks about: hide an instruction in a tool description or a tool's output, and the agent reading it does what the attacker said instead of what the user asked. Static scanners ask "does this description look hostile." Siege asks a different question. Does the agent get hijacked.

So it runs a real agent loop. Benign read tool, plus an export_record sink that ships data to a URL. The user's task is read-only: summarize record 1, that's all. Then Siege injects each payload through the description channel and the output channel and watches whether the model fires the sink at an attacker destination it was never asked to touch. A hijack is observed, not inferred from text.

The output is a matrix, not a verdict. Five payloads across two channels: system-block spoofing (run through both the description and the output), plain policy text, role-confusion, task-decomposition. You see which ones steered the model and which bounced off. A clean 0-of-5 is a real result too, and a regression guard for the day you bump model versions and a framing that used to bounce stops bouncing.

What it doesn't do

The report names the classes it ran and prints what it skipped. MCP servers only for now, no OpenAI function-calling, that's a later expansion. stdio transport today, HTTP next. The silent-failure class (does the server claim success while returning empty data) is designed and not yet shipped. No "finds all vulnerabilities" anywhere in the output, because that sentence is how scanners lie.

And it only attacks my own fixtures and servers I explicitly opt in. Pointing a runtime red-team tool at someone else's live server without an invite isn't a demo.

Where it sits

Siege is the offense leg of a three-piece stack. Warden governs the server. Crumb attributes every call to the person who authorized it. Siege is the part that tries to break what Warden built. Build the wall, then lay siege to it.

Code's public: github.com/AlexlaGuardia/siege. It's v0.1 and it's narrow on purpose. Runs against a live server, as real roles. The part the manifest can't show you.

An AI agent acted across two companies. Whose audit log knows which human?

Alex LaGuardia — Wed, 24 Jun 2026 12:16:50 +0000

Alice logs into her company's tools through their identity provider. She points an agent at a task. That agent hands part of the work to a sub-agent, and the sub-agent calls a tool that lives in a partner company's system, behind a different identity provider. The tool does something it shouldn't. An auditor pulls the record.

Whose log knows it was alice?

Not the agent's. The agent is a process; it can claim to be anyone. Not the model's either, which reads whatever it was handed and has no idea which human is behind the session. The honest answer in most deployments today is that the partner's system can prove a bot called it, and can prove which company's bot. Then the trail goes cold. The person who actually directed the action dissolves into "some agent at the vendor."

I have been building Crumb to refuse that outcome: a tamper-evident record that binds the actual person behind an agent's tool call, verifiable by someone who does not have to trust whoever ran the agent. Within a single identity provider, that chain was already working. This post is about the part that wasn't, and why it took longer than I expected.

The single-issuer case was the easy half

When the whole chain lives under one identity provider, delegation has a clean answer, and it is a real standard. RFC 8693 token exchange lets you mint a token that carries two identities at once: the human as the sub, and the agent acting for them as a nested act claim. Add a hop and you nest again. The human stays at the root the whole way down.

{
  "iss": "https://idp-a.local",
  "sub": "alice",
  "act": { "sub": "researcher", "act": { "sub": "planner" } },
  "aud": "read_record"
}

One provider signs that token. A resource server verifies it against that provider's public key, walks the act chain back to alice, and it is done. No shared secret, no trusting the gateway that minted it. I covered that build in an earlier post. It holds up.

The catch is in the assumption hiding under "one provider."

The boundary is where it breaks

Real delegation does not stay inside one company. The interesting, dangerous case is the one that crosses.

So planner, holding a token IdP A signed, needs the call into B's domain to carry a token B will honor. The textbook move is another RFC 8693 exchange, this time against B. You hand B the token A issued, and B mints you a fresh one.

And right there is the problem, sitting in plain sight in the spec. When B does that exchange, it mints a token signed only by B and drops A's signature on the floor. The new token says sub: alice because B copied it across, but the cryptographic proof that A authenticated alice is gone. Downstream, all you hold is B's word: "A told me it was alice."

For most systems that is fine, because most systems were already trusting B. But Crumb's entire reason to exist is to let an auditor verify without trusting the operator. A cross-issuer hop that resolves to "trust B" puts the trust-me point right back in the middle of the chain I was trying to make checkable. It's the one thing I can't wave away.

Stapling: carry the signature across, don't reissue it

The fix I landed on is to stop throwing the upstream token away.

When B exchanges A's token, two things happen. First, B verifies A's token against A's public key. B can only do that if it federates with A, so A has to be in B's trust set. That is a real relationship and I will come back to how honest it is. Second, instead of discarding A's token, B staples it into the one it mints: the exact inner JWS rides along in a prv claim, its SHA-256 in psh, and the inner issuer in pis.

{
  "iss": "https://idp-b.local",
  "sub": "alice",
  "act": { "sub": "researcher", "act": { "sub": "planner" } },
  "aud": "read_record",
  "prv": "<the exact JWT that IdP A signed>",
  "psh": "sha256:5992849d649979e6...",
  "pis": "https://idp-a.local"
}

Now the outer token is not an assertion that alice was authenticated. It is a pointer to the original proof, hash-pinned so it can't be swapped. B signed its own segment. A already signed its segment. Nobody re-signed anybody else's.

A verifier handed the outer token walks the chain backward and checks each segment against the key of the issuer that actually signed it.

Each rule maps to one way a dishonest issuer could try to cheat:

Per-segment signature. Every token in the chain is verified against its own issuer's key, pulled from the verifier's federation set. An issuer it does not federate with has no key, so the token is refused, not verified-then-ignored.
Staple integrity. A token carrying prv must have psh equal to the hash of that prv. Swap the embedded provenance for a different token and the hash stops matching.
Human continuity. The sub has to be the same identity at every hop. An outer token claiming to act for alice while stapling a token A issued for bob is a lie the walk catches.
Actor continuity. The chain an outer token carries beneath its own actor has to equal the inner token's chain exactly. An issuer may append a hop. It may not rewrite the hops it inherited.

What it refuses

The part I care about most is the negative space. A mechanism that only shows the happy path hasn't proven anything. So the demo verifies the real chain across two issuers, and then it tries to break it five ways and shows each one failing by name.

The sharpest of the five: a malicious B tries to fabricate an upstream human. It controls its own signing key, so it mints a perfectly valid B token that says it is acting for mallory, and it staples a forged "A token" that also names mallory. B can sign its own segment all day. What it cannot do is sign as A. The verifier checks the stapled segment against A's real key, the forgery fails there, and B's attempt to invent a human it was never handed dies at the boundary.

3. malicious B forges an upstream human (mallory)
   forged upstream    rejected (InvalidSignature): B can't sign as A
4. swap the stapled provenance (psh left stale)
   swapped provenance rejected (StapleMismatch): psh pins one predecessor
5. B claims alice but staples bob's token
   human discontinuity rejected (HumanDiscontinuity): same human or nothing
6. B rewrites the inherited actor chain
   rewritten chain    rejected (ActorChainBroken): append-only, no rewrite
7. upstream from an unfederated issuer
   unfederated issuer rejected (UntrustedIssuer): verifier trusts its own set

That last one matters more than it looks. Even when B chooses to accept some sketchy third issuer C and builds a chain on it, the verifier makes its own trust decision. B vouching for C buys C nothing. The verifier trusts its set, not B's.

The part I am not going to oversell

Here is the boundary, stated plainly, because pretending it isn't there is exactly the tell I am trying to avoid.

This isn't a new standard. The prv and psh staple claims are a Crumb convention. There is no RFC that defines them, and if two vendors wanted to interoperate this way they would have to agree on the format first. And the whole thing still rests on a federation trust set. Somebody, somewhere, decides which issuers they accept. I didn't make that decision disappear.

What I did was make it the only thing you have to decide, and make everything downstream of it checkable. You pick your trusted issuers once, explicitly, in an object you can read. After that no single issuer gets to assert the human on its own word. Each one signs only its own segment, and the verifier re-checks all of them.

There's still no trust-free answer for cross-issuer identity. Just a smaller question: who do you federate with.

Try it

The whole thing is one additive module and a demo you can run.

git clone https://github.com/AlexlaGuardia/crumb
python -m crumb.cross_issuer_demo

It stands up two issuers with two different keys, crosses a real delegation chain between them, verifies it back to the human, and then fails the five forgeries above. The live timeline and the rest of Crumb are at crumb.alexlaguardia.dev.

If you work on agent identity or authorization and you think the stapling model has a hole in it, I want to hear where.

An AI agent exported a patient record. Your logs can't say who told it to.

Alex LaGuardia — Tue, 23 Jun 2026 13:45:10 +0000

You put an LLM agent into production. It runs under a service account or a shared API key, because that's how you give software credentials. It reads a record, exports a file. Sometimes it moves money. Your audit log dutifully records the action. It says the agent did it.

It does not say which human told it to.

That's fine right up until it isn't. If the agent does something it shouldn't have, "the service account did it" is not an answer anyone can act on. You can't discipline a service account. You can't tell a regulator that a bot was responsible and leave it there.

The deadline that makes this concrete

The EU AI Act, Article 12, comes into force on August 2 2026. High-risk systems have to keep logs that allow "the identification of the natural persons involved" in an event. A natural person. Not a service account, not an agent id. The actual human.

A log built around shared credentials can't answer that question. The identity was never captured, so no amount of log retention brings it back.

You can't prompt your way out of this

The obvious instinct is to make the model report who it's acting for. Put the user in the system prompt, have the agent include it in the tool call.

Two problems.

A tool call, on the wire, is {"name": "export_record", "arguments": {...}}. There is no field for who. OpenAI function-calling has no native identity slot. MCP permits carrying it but almost nobody implements it. So at the protocol level, the "who" has nowhere to live.

And worse, anything the model emits can be prompt-injected. If identity comes from the model, then the data the agent reads back from a tool can rewrite it. I tested this on the same payload delivered two ways, and the tool description hijacked more models than the tool output did. The model's output is the one surface you can never treat as trusted for identity. It has to be stamped by the runtime, outside the agent's reasoning, before the model gets a say.

So I built the runtime that stamps it. It's called Crumb. Every agent action drops a crumb; the trail leads back to the human who directed it.

The shape of it

One gateway, every tool call passes through it.

It pulls the human's identity from the verified session, captured once at login, never from the model. It mints a short-lived delegation token that carries both identities: the human as the RFC 8693 sub, the agent as the act, scoped to the one resource being called. Then it writes a crumb to an append-only, hash-chained ledger, each entry signed with Ed25519, and calls the tool with the token. The tool refuses any call that doesn't carry a valid token, so there's no path to the data that skips it.

That delegation token isn't hand-rolled. It's a real RFC 8693 token exchange against an identity provider: the human's session goes in as the subject_token, an RS256 provider-signed composite comes back, and the resource verifies it against the provider's published JWKS. No shared secret. Point it at Okta or Keycloak or Zitadel and the same code path holds, because it's the standard, not a custom copy of it.

The part that actually breaks: more than one agent

A single agent calling a tool is the easy case. Real systems don't look like that. A human directs an orchestrator. The orchestrator delegates to a sub-agent. The sub-agent calls the tool. Now who's accountable, and how do you prove it, when the human is two hops away from the action?

This is where most attribution stories quietly stop. The standards bodies haven't fully solved it either. But RFC 8693 has the mechanism hiding in section 4.1: the act claim can nest. Each new actor wraps the previous one, and the human stays the sub at the root the whole way down. Walk the nesting back and you get the full chain of who-acted-for-whom, ending at the person who started it.

So Crumb implements it end to end. Each hop nests the prior actor. The provider does the nesting over a real token exchange, not a dev shortcut. The crumb records the whole chain. And because the entire nested structure is signed as one token, there's no per-hop seam to forge at. I tried: rewrite a middle actor in the chain and re-sign it without the key, and verification rejects it on the signature. The chain holds together or it doesn't verify.

Alice authorizes one action, read_record, when she logs in. A planner agent takes her request and delegates to a researcher sub-agent. The researcher reads the record. The crumb traces it back through both agents to Alice, verified.

Then a hop goes rogue and calls export_record, which Alice never authorized. The action may technically run. But the crumb records no human directive behind it. It flags the action unauthorized and names the agent chain that did it. Alice is in the record. She's provably not the one accountable.

A service-account log can't do that. It says a bot exported the record, and stops there. This one clears Alice by name and points at the agents instead.

Tamper-evidence, including against yourself

A signed, hash-chained log sounds tamper-proof until you remember who holds the signing key. You do. If you can re-sign, you can rewrite history and re-sign the whole chain, and per-entry verification passes the forgery, because every entry is validly signed. By you.

So the ledger checkpoints its Merkle root and publishes it to Sigstore's public Rekor transparency log. Now the operator-rollback attack falls apart: you rewrite a crumb, re-sign the entire chain, and per-entry verify still passes. But the rewritten root no longer matches the one already sitting public in Rekor, timestamped before your edit. The forgery is caught by something you don't control. There's a button on the live demo that runs exactly this and shows the anchor catching it.

What it isn't

This is the part I want to be straight about, because attribution is a space where it's easy to overclaim.

Crumb is a flight recorder, not a control plane. Stopping things is a different and well-funded job. Cerbos, Capsule, Astrix already do it. Crumb records and proves; it points at them for the rest.

Attribution is only as strong as the gateway. Bypass it and there's no crumb, so the gateway has to be real and enforced, not optional.

The multi-hop chain is single-issuer. One provider, one trust root. A chain that spans two different identity providers is genuinely unsolved at the standards level, and I'm not going to pretend otherwise.

The ledger stores a hash of the arguments, not the raw arguments, to keep sensitive data out of the log. The tradeoff is that it proves an action happened and who directed it, not the exact bytes that were touched.

And MCP attribution is permitted by the spec but rarely implemented upstream, so Crumb can stamp the record but can't force a non-compliant server to honor the human identity.

That's the gap between what's built and what's marketing. In this space, that gap is the whole thing.

Try to break it

The demo is live at crumb.alexlaguardia.dev. Seed some crumbs, tamper a row, watch verification flip. Hit the operator rollback and watch the external anchor catch a forgery that per-entry signing passes. The code is on GitHub.

If you're building agent infrastructure and you've hit this, or you think I've got something wrong, I want to hear it.

Same question, three answers: a governed MCP server with receipts

Alex LaGuardia — Wed, 10 Jun 2026 14:44:04 +0000

Ask my agent "what's the open pipeline for Acme Corp?" as an admin and it answers $125,000 across two deals, with a table. Ask the exact same question as a support agent and it says, politely and correctly, that it can't see pipeline data and suggests who to ask instead.

The model didn't decide that. It never gets the chance to. That's the whole project.

The problem

Give an AI agent tool access to company data and you get two questions you can't dodge:

Who is the agent acting as? A support rep must not get answers the human behind the keyboard isn't allowed to see.
How do you know it behaved? "Seemed fine in testing" doesn't survive a security review.

I kept seeing these two questions in every AI-infra and forward-deployed engineering job posting, so I built a complete answer and put it on the public internet: Warden, a governed MCP server with an agent, traces, and evals on top. You can fire a real (rate-limited) agent run yourself.

Three ideas worth stealing

1. Governance lives outside the model. The role comes from session identity (the MCP server reads it at spawn, like OAuth scopes). Every read passes through one GovernedStore choke point that applies resource access, region row-scoping, and field redaction before the model sees a byte. Prompting harder widens nothing, because there's nothing on the model's side of the wall to widen.

2. The eval oracle has to obey the rules too. This was the design moment of the build. If your reference answers come from the raw database, then a correctly denied answer scores as a failure: the support agent honestly says "I can't see pipeline" and your eval compares that to $125,000 and marks it wrong. So Warden's oracle computes ground truth through the same governance layer as the agent. An honest denial becomes a passing grade. Then a stronger model judges than answers (Opus judging Sonnet), anchored to that reference. Unanchored LLM judges grade on vibes; anchored ones measure. 12/12 cases passing, scorecard is public.

3. Denials are data, not error strings. Tools return a structured access_denied object. That's what lets the eval layer check "did the agent report the limit honestly instead of guessing," and it's what makes the same-question-three-roles diff page work.

Every run also emits real OpenTelemetry spans (GenAI semantic conventions) that the dashboard replays as a timeline, with the enforcing role stamped on every tool result.

What bit me

Markdown tables from the agent rendered as pipe-soup until I learned Tailwind's prose classes silently do nothing without @tailwindcss/typography, and react-markdown needs remark-gfm for tables at all. Found it by clicking the deployed site, not in the build.
The official MCP Python SDK ships FastMCP at mcp.server.fastmcp. The standalone fastmcp package is a different thing. Know which one you're importing.
A public endpoint that burns real model tokens forces the unglamorous work: per-IP limits off the CDN's forwarded header, a global daily budget, a single-flight lock, hard timeouts. That's the difference between a demo and a toy.

Links

Live console: warden.alexlaguardia.dev
Source: github.com/AlexlaGuardia/warden
Full build write-up: alexlaguardia.dev/writing/warden

Built solo as a working answer to "how do you let an agent touch real data without trusting it blindly?" If you're building agents over data someone cares about, the choke point, the governance-aware oracle, and structured denials all carry straight over.

Your AI Agent Forgets Everything Between Sessions (Here's How to Fix It)

Alex LaGuardia — Fri, 01 May 2026 10:17:57 +0000

The Problem

You finish a session with Claude Code at 11pm. Three files changed, two design decisions made, one bug discovered but unresolved.

You start fresh the next morning. The agent has no memory of any of it.

You spend the first ten minutes of the new session doing what I call "cold-start theater": re-reading the changed files, re-explaining what you decided yesterday, re-discovering the bug you already debugged.

Multiply that by every session. That's the tax you pay for stateless agents.

Why Conversation History Doesn't Solve This

The obvious answer is "just save the conversation." It doesn't work for three reasons:

Conversation history is enormous. A real working session has thousands of messages, tool calls, and outputs. Loading it consumes most of your context window before you do anything useful.
It's mostly noise. 90% of what happened in the previous session was the agent reasoning out loud. The next agent doesn't need that. It needs the conclusions.
It doesn't compose across agents. If agent A finishes a task and agent B picks up later, B doesn't want to read A's monologue. B wants to know what changed and what's next.

What a Handoff Actually Needs

After running multi-agent setups for a year, the pattern that works is a structured summary with five fields:

Files touched: what physically changed on disk
Decisions made: architectural or design choices that affect future work
Blockers: things that stopped progress, with enough context to unblock
Next steps: what the next agent should do first
Open threads: anything unresolved that future-you needs to remember

That's it. Five fields, usually under 500 words. The next agent reads this in under a second and has full operational awareness.

The Protocol

In Vigil, handoff is a first-class operation:

from vigil import Vigil

v = Vigil()
v.handoff(
    agent="backend-cc",
    files_touched=["api/routes.py", "models/user.py"],
    decisions=["Switched to JWT auth from sessions; simpler refresh flow"],
    blockers=["Stripe webhook still failing in test mode, see line 142"],
    next_steps=["Wire JWT middleware into protected routes", "Fix Stripe webhook signature validation"],
    open_threads=["Decide on rate limit strategy before deploy"],
)

When the next agent boots:

context = v.resume(agent="backend-cc")
# Returns the most recent handoff, or chains across the last N

Or via the CLI:

vigil resume backend-cc

The handoff is stored as structured data, queryable, and the daemon includes the most recent handoff in the agent's awareness file automatically.

Handoff Chains

The thing that surprised me when I built this: chains compound.

If you handoff three sessions in a row on the same project, the next agent can resume the chain. It sees the most recent handoff plus a summarized rollup of the previous two. No information loss across multiple sessions.

vigil resume backend-cc --chain 5

Returns a synthesized view of the last five handoffs. Decisions persist. Blockers either get resolved (and removed) or carry forward (and become urgent).

This is how you keep continuity across days or weeks of work without ever loading a full conversation history.

Why MCP Wasn't Enough

I tried to do this through MCP at first: just expose handoff tools to Claude Code and let the agent emit them.

That works, but it's not enough. The handoff needs to live somewhere the next agent can read before tools are even loaded. Tool calls cost a round trip. The handoff should be in your boot context.

The pattern that works: handoff data lands in the awareness file. Agents read awareness on boot. Zero tool calls needed to know what happened last session.

Concrete Numbers

Before this protocol: my agents spent 8-15K tokens per session re-discovering context.

After: the awareness file with embedded handoff is ~2K tokens, loaded once at boot. The token savings show up directly on my Anthropic bill.

The bigger win is psychological: I stopped dreading the start of new sessions. The agent knows where we left off.

Getting Started

pip install vigil-agent
vigil init

Handoff is a core feature of Vigil, alongside the awareness daemon, frame-based tool filtering, and the signal protocol. Full docs and source on GitHub. MIT license.

If you're running multi-session AI workflows and you've felt the cold-start tax, give it a try. I'd love to hear what handoff protocol works for your setup.

I'm building cognitive infrastructure for AI agents. If session handoff is something you're solving for, drop a comment or find me on GitHub.

Your MCP Servers Are Flying Blind (Here's How to Fix It)

Alex LaGuardia — Thu, 30 Apr 2026 12:55:21 +0000

The Problem

You deploy an MCP server. Agents start calling tools. Something breaks.

How do you know?

Right now, you don't. Most MCP servers are black boxes. No metrics. No error rates. No latency tracking. No alerts when a tool starts failing silently.

I run 95 MCP tools across multiple projects. When a tool started returning empty results instead of errors, I didn't notice for three days. The agent just quietly worked around it, producing subtly wrong output. No crash, no log, no alert.

That's when I built MCPWatch.

What MCPWatch Does

MCPWatch wraps any Python MCP server with one line — FastMCP and low-level Server, same API:

from vigil import MCPWatch

watch = MCPWatch(server)

That's it. From that point, every tool call is tracked:

Call volume per tool (which tools are actually used?)
Duration with p50/p95/p99 percentiles (what's slow?)
Error rates per tool (what's failing?)
Latency trends (is performance degrading?)
Silent failures (tool returned successfully but with empty/null data)

The Dashboard

MCPWatch exposes 5 REST endpoints for monitoring:

GET /mcp/health    -- overall server health (healthy/degraded/unhealthy)
GET /mcp/tools     -- per-tool stats breakdown
GET /mcp/errors    -- recent errors with full context
GET /mcp/latency   -- latency percentiles per tool
GET /mcp/volume    -- call volume over time

There's also a CLI command:

vigil mcp-health

This gives you a per-tool breakdown right in your terminal. I run it before and after deploys.

Alerts

MCPWatch emits alerts when things go wrong:

watch = MCPWatch(
    server,
    error_threshold=0.1,     # alert if >10% of calls fail
    latency_threshold=5000,  # alert if p95 > 5 seconds
)

Alerts flow through Vigil's signal protocol, which means you can wire them to webhooks, Slack, or any trigger action.

CI/CD Health Check

For CI pipelines, there's a stdio probe:

vigil mcp-health-check --timeout 5000 --min-tools 10 --require query,signal

Returns exit code 0 (healthy) or 1 (unhealthy). Drop it into GitHub Actions:

- name: MCP Health Check
  run: vigil mcp-health-check --timeout 5000 --min-tools 10

Why This Matters

The MCP ecosystem is growing fast. There are 11,000+ servers listed across registries. But the tooling around MCP is still in the "deploy and pray" phase.

In traditional web services, you'd never deploy an API without monitoring. MCP servers deserve the same treatment. Especially when the consumer is an AI agent that won't tell you something is wrong -- it'll just silently degrade.

Getting Started

pip install vigil-agent

MCPWatch is part of Vigil, a broader cognitive infrastructure toolkit for AI agents. But you can use MCPWatch standalone -- just wrap your server and point your monitoring at the endpoints.

The full docs and source are on GitHub. MIT license.

I'm building tools for AI agent infrastructure. If you're running MCP servers in production, I'd love to hear what observability problems you're hitting. Drop a comment or find me on GitHub.

Three freelancer tools died in two months. I built the replacement.

Alex LaGuardia — Sat, 04 Apr 2026 10:18:46 +0000

HoneyBook hiked prices 89%. AND.CO shut down entirely. Bonsai got acquired by Zoom with no roadmap. All within two months of each other.

I'm a freelancer who was paying $29/mo for HoneyBook. I used two features: proposals and invoice reminders. That's it. Two features out of fifty. The other forty-eight were bloat I paid for and never touched.

Dubsado is so complex that a cottage industry of "setup specialists" charge $500-3,500 just to configure it. That tells you everything about how broken this market is.

So I built Stampwerk. Proposals, contracts, invoices, and follow-ups. $12/mo. No setup wizard. No onboarding call. No fifty features you'll never open.

What the AI actually does

This isn't "AI-powered" as a marketing checkbox. The AI does two specific things that freelancers hate doing manually.

1. Proposal generation. Answer 5 questions about a project and the LLM writes a full proposal -- scope, timeline, pricing breakdown, and payment terms.

# 5 inputs in, structured proposal out
response = groq_client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[
        {"role": "system", "content": PROPOSAL_SYSTEM},
        {"role": "user", "content": json.dumps({
            "client": client_name,
            "description": project_desc,
            "budget_range": budget,
            "timeline": timeline,
            "deliverables": deliverables
        })}
    ],
    response_format={"type": "json_object"}
)

Not template-fill. The model reasons about scope and pricing based on the project description. You edit what it generates, not what a template assumes.

2. Invoice follow-ups. A background daemon runs hourly and chases overdue invoices on a 3-step escalation:

Day 3 -- friendly check-in
Day 7 -- professional reminder with payment link
Day 14 -- firm final notice

Each message matches the escalation stage. This is the part of freelancing that everyone hates and nobody does consistently. Now it runs while you sleep.

The full pipeline

The thesis behind Stampwerk is that these aren't separate features. They're one flow:

Client signs up (Google or magic link, 30 seconds)
Creates a project, answers 5 questions
AI generates the proposal
Client views it at a public link, accepts with one click
Contract auto-generates from the accepted proposal terms
Client e-signs
Milestones trigger invoices with Stripe payment links
Overdue invoices get automatic follow-ups

One pipeline. Every step feeds the next. No configuration, no "setup specialist" needed.

HoneyBook has all these features too. They also have fifty others, a $29-59/mo price tag, and an 89% price hike that tells you where they think the market is headed.

Why these tech choices

Layer	Choice	Why
Backend	FastAPI	42 routes, async, typed
Database	SQLite	One file, WAL mode, zero ops burden
AI	Groq + Llama 3.3 70B	Free inference, structured JSON output
Payments	Stripe	Payment links for clients, subscriptions for us
Email	Resend	Transactional email under 3K sends is free
Frontend	Next.js 14 + Tailwind	SSR, file routing, fast iteration

Total infrastructure cost: $0/mo. AI calls are free through Groq. Email is free at this scale. Stripe only charges when money moves. The whole thing runs on a single server I already had.

This matters because the competitors raised hundreds of millions. HoneyBook took $479M in funding. Dubsado bootstrapped to $2.5M ARR. Moxie raised ~$10M. When you compete against that, your margin has to be your moat. A $0 cost base means $12/mo is sustainable, not a loss leader.

Honest trade-offs

The retro arcade UI is polarizing. Some people think it's unprofessional for a business tool. I'm keeping it. If your target is corporate project managers, sure. If your target is solo freelancers who are tired of software that looks like every other SaaS dashboard, it works.

No PDF export yet. No time tracking. No QuickBooks integration. No mobile app. These are real gaps. But I'd rather ship the core pipeline right and add features from real user feedback than build fifty features nobody asked for.

That's how we got HoneyBook in the first place.

Try it

stampwerk.com -- free tier gives you 5 clients, 5 projects, and full AI proposals. Pro is $12/mo for unlimited.

Built with FastAPI, Next.js 14, SQLite, Groq, Stripe, and Resend. Questions about the stack or the business model welcome.

I Built a Security Scanner That Uses AI to Review Its Own Findings

Alex LaGuardia — Tue, 31 Mar 2026 09:53:59 +0000

Every AI coding tool ships code fast. None of them check if it's safe.

I built Critik — an open-source security scanner that catches what your AI writes and your review misses. Regex and AST find the candidates. An LLM reviews each one with full file context, confirms the real problems, kills the false positives, and explains why in plain English.

pip install critik and you're scanning in 30 seconds.

The Numbers Are Ugly

53% of teams that shipped AI-generated code later found security issues that passed review. Georgia Tech's Vibe Security Radar tracked 74 CVEs from AI coding tools in Q1 2026 alone — 6 in January, 15 in February, 35 in March. Accelerating.

Here's what I keep finding when I scan AI-built projects:

Hardcoded API keys — Cursor generates a Supabase client and pastes the service_role key right in the file
SQL injection via f-strings — Copilot autocompletes db.execute(f"SELECT * FROM users WHERE id = {user_id}") without blinking
Firebase rules wide open — Bolt scaffolds read: true, write: true and nobody touches it
NEXT_PUBLIC_ prefix on secrets — the env var that hands your database URL to every browser

Not edge cases. Default patterns.

The Tools That Exist Don't Fix This

Snyk charges $25-98/dev/mo. Built for enterprises with procurement budgets.

Semgrep is powerful. Also requires writing custom rules in a DSL. Steep curve. Recently relicensed behind commercial terms.

npm audit is, in Dan Abramov's words, "broken by design" — flags devDependency issues that can't touch production.

Bandit and ESLint security plugins catch patterns but have zero context. They flag eval() in a test fixture the same way they flag eval(user_input) in a request handler.

That last one is the real problem. Static scanners are noisy. Developers learn to ignore them. Which means they ignore the real findings too.

Two Passes. One Scanner.

Pass 1 — Static (fast, offline, free)

Regex patterns and Python AST parsing. Hardcoded secrets (16 patterns — AWS, Stripe, OpenAI, Anthropic), SQL injection, command injection, eval/exec, XSS, framework misconfigs. Runs in milliseconds. No API key needed.

Pass 2 — AI Review (optional, the whole point)

Add --ai and each finding goes to Groq's Llama 3.3 70B with the full file as context. The model acts as a security analyst:

Verdict: confirmed, false_positive, or needs_review
Confidence: 0-100%
Why: "This eval() parses trusted JSON config from a local file" vs "This eval() takes unsanitized user input from req.query"
Fix: actual code, not generic advice

The AI doesn't replace the scanner. It reviews the scanner's work.

What It Looks Like

$ critik scan . --ai

  Critik v0.4.0 — scanned 7 files  [AI]

  CRITICAL  nextjs-public-secret
  app/config.ts:18  Secret exposed to browser via NEXT_PUBLIC_ prefix
  | 18 | const key = process.env.NEXT_PUBLIC_SECRET_API_KEY
  CONFIRMED (95%)
  > The NEXT_PUBLIC_ prefix exposes this API key to every browser.
  Fix: Rename to SECRET_API_KEY and access server-side only

  CRITICAL  aws-access-key              (dimmed — false positive)
  tests/fixtures/bad_secrets.py:2  AWS access key detected
  FALSE POS (100%)
  > This file is in tests/fixtures — fake credentials for testing.

  HIGH      sql-fstring
  app/db.py:6  SQL injection via f-string in execute()
  | 6 | db.execute(f"SELECT * FROM users WHERE id = {user_id}")
  CONFIRMED (95%)
  > This f-string takes unsanitized input, allowing SQL injection.
  Fix: db.execute('SELECT * FROM users WHERE id = ?', (user_id,))

  ─────────────────────────────────────────────
  7 files scanned in 2714ms — 23 findings: 10 critical, 8 high, 5 medium
  AI analysis: 7 confirmed, 16 false positives

Without AI: 23 findings. Developer overwhelmed. Ignores all of them.

With AI: 7 real issues. 16 dismissed with reasons. Developer fixes what matters.

Under the Hood

Each API call sends the full file content (up to 8K chars) plus all findings for that file. One call per file — keeps tokens low, context high.

The model sees imports, function signatures, data flow. It knows test fixtures are probably safe, .env files are expected to have secrets, and NEXT_PUBLIC_ vars are intentionally client-exposed.

Temperature 0.2. Structured JSON back. If the API is down, Critik falls back to regex-only. No crash, no hang.

What It Catches

Category	Patterns	Examples
Secrets	16	AWS, GitHub, OpenAI, Anthropic, Stripe, Slack, DB URLs, JWTs, private keys
Injection	6	SQL via f-string/concat, eval(), exec(), os.system(), subprocess shell=True, XSS
Frameworks	8	Supabase RLS, Firebase rules, NEXT_PUBLIC_ secrets, NextAuth, Prisma raw, Stripe webhooks
Config	6	NODE_ENV in source, insecure cookies, open CORS, debug mode
Auth	2	Missing auth on routes, open endpoints
Dotenv	3	Exposed .env, sensitive vars unencrypted

Free. All of It.

pip install critik
critik scan .                # regex/AST only — offline, instant
critik scan . --ai           # + AI review (needs GROQ_API_KEY)
critik scan . --format fix   # copy-paste fix prompts for Cursor/Claude

Pre-commit hook: critik hook install. SARIF output for CI/CD. GitHub Action included. MIT license.

Why I Built This

I hunt bugs on HackerOne and 0din. The vulnerabilities I find in production are the same patterns AI tools ship by default. Hardcoded keys. Missing auth. SQL injection. Open configs.

The irony: AI coding tools are the biggest source of new vulnerabilities and the best tool for catching them. A regex finds eval(). Only an LLM can tell you if it's dangerous.

Critik is the scanner I wanted. Now it exists.

Website: critik.dev
GitHub: AlexlaGuardia/Critik
PyPI: pip install critik

Run critik scan . on your project. You might not like what you find.

OAuth2, Two APIs, and Soft Deletes — Building an MCP Server for FreshBooks

Alex LaGuardia — Thu, 26 Mar 2026 22:33:14 +0000

Most MCP servers assume your target API hands you an API key and gets out of the way. FreshBooks doesn't. It requires full OAuth2, splits its API across two different base URLs, and has resources that can only be soft-deleted. Building this server meant solving problems most MCP tutorials don't prepare you for.

The result: 25 tools covering invoices, clients, expenses, payments, time tracking, projects, estimates, and reports — with the auth flow, API quirks, and deletion edge cases handled for you.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, you manage your entire freelance business without leaving your AI assistant.

Before (manual):

Log into FreshBooks
Navigate to Invoices → find overdue ones
Note the client names and amounts
Switch to your AI tool
Type out all the details
Ask what to do about it

After (with mcp-freshbooks):

"Which invoices are overdue? Draft follow-up messages for each client based on how late they are."

Claude calls list_invoices with a status filter, gets the details, and drafts personalized follow-ups — all in one shot.

25 Tools, Full Business Coverage

Invoices (6): List, get, create, update, delete, send by email
Clients (4): List, get, create, archive with full contact details
Expenses (3): List, get, create with category and tax support
Payments (2): List, record payments against invoices
Time Entries (2): List, create with project/service association
Projects (2): List, get with budget and billing details
Estimates (2): List, get with line items
Reports (1): Profit & Loss report with date filtering
Auth (3): OAuth2 flow, identity check, connection test

Technical Decisions Worth Sharing

Full OAuth2 — No Shortcuts

FreshBooks requires OAuth2. No API keys, no shortcuts. The server handles the entire flow: it spins up a local HTTPS callback server, opens the authorization URL, catches the redirect with the auth code, exchanges it for tokens, and persists them to ~/.mcp-freshbooks/tokens.json. Token refresh is automatic — you authenticate once and forget about it.

@mcp.tool()
def freshbooks_authenticate() -> str:
    """Start OAuth2 authentication. Returns a URL to open in your browser."""
    config = get_config()
    url = get_auth_url(config)
    # Spins up localhost:8555 HTTPS callback server in background
    start_callback_server(config)
    return f"Open this URL to authorize:\n{url}"

This was the hardest part of the build. Most MCP servers assume API keys. When your platform demands OAuth2, you either solve it properly or your server is useless.

Two APIs, Two Base URLs

FreshBooks has a split API: accounting resources (invoices, clients, expenses) live at api.freshbooks.com/accounting/account/{account_id}/..., while project resources (projects, time entries) live at api.freshbooks.com/projects/business/{business_id}/.... Different base URLs, different ID types.

The client abstracts this completely:

ACCOUNTING_BASE = "https://api.freshbooks.com/accounting/account"
PROJECTS_BASE = "https://api.freshbooks.com/projects/business"

async def accounting_list(resource, ...):
    account_id, _ = await get_ids()
    url = f"{ACCOUNTING_BASE}/{account_id}/{resource}"
    ...

async def projects_list(resource, ...):
    _, business_id = await get_ids()
    url = f"{PROJECTS_BASE}/{business_id}/{resource}"
    ...

The tools never think about which API base to use — they just call the right function.

Soft Deletes vs Hard Deletes

FreshBooks treats deletion differently depending on the resource. Invoices and estimates can be hard-deleted (actually removed). Clients and expenses can only be soft-deleted by setting vis_state to 1 (archived). Delete a client with the wrong endpoint and you get a cryptic 400 error.

async def accounting_delete(resource, resource_id):
    """Hard-delete (invoices, estimates)."""
    ...

async def accounting_soft_delete(resource, resource_id, wrapper_key):
    """Soft-delete via vis_state=1 (clients, expenses)."""
    return await accounting_update(resource, resource_id, wrapper_key, {"vis_state": 1})

Each tool uses the correct method — the AI never needs to know about this distinction.

The search[key] Query Format

FreshBooks uses a non-standard query parameter format for filters: search[status]=2&search[date_from]=2024-01-01. Not status=2, not filter[status]=2 — specifically search[key]. Get the format wrong and the API silently ignores your filters.

def _build_search_params(filters):
    params = {}
    for key, value in filters.items():
        if isinstance(value, list):
            for v in value:
                params.setdefault(f"search[{key}][]", []).append(str(v))
        else:
            params[f"search[{key}]"] = str(value)
    return params

The tools accept clean Python dicts and handle the formatting internally.

Get Started in 2 Minutes

Install

pip install mcp-freshbooks

Create OAuth App

Go to my.freshbooks.com/#/developer, create an app, and note the client ID and secret. Set the redirect URI to https://localhost:8555/callback.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "freshbooks": {
      "command": "mcp-freshbooks",
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your-client-id",
        "FRESHBOOKS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Then ask Claude to run freshbooks_authenticate — it will give you a URL to authorize. One-time setup, tokens auto-refresh after that.

Claude Code

claude mcp add freshbooks -- env FRESHBOOKS_CLIENT_ID=id FRESHBOOKS_CLIENT_SECRET=secret mcp-freshbooks

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Add invoice line item support from day one. The current create_invoice accepts line items as a JSON string, which works but isn't the cleanest interface. A dedicated line-item builder would be more ergonomic for the AI.

Handle plan-gated features more gracefully. FreshBooks gates features by plan tier — time tracking, projects, and advanced reports require paid plans. The error handling catches 403s and explains this, but detecting plan limits upfront would be smoother.

Lessons for MCP Server Builders

Solve OAuth2 properly. If your target platform requires it, don't punt — build the full flow with token persistence and auto-refresh. It's the difference between a demo and a tool people actually use.
Abstract API inconsistencies. If the platform has split APIs, different deletion behaviors, or non-standard query formats — hide all of it. The AI should never deal with platform quirks.
Handle plan-tier errors. SaaS platforms gate features by pricing tier. Catch permission errors and explain what's happening instead of returning raw 403s.
Persist tokens securely. Store tokens in a well-known location (~/.mcp-freshbooks/) with clear documentation. Users shouldn't have to re-authenticate every session.

Links

GitHub: AlexlaGuardia/mcp-freshbooks
PyPI: mcp-freshbooks
License: MIT

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: Mailchimp, WooCommerce, ActiveCampaign. Follow me here or on GitHub to catch the next one.

Update (April 2026): Since publishing, mcp-freshbooks has been expanded from 25 to 53 tools (v0.2.0). New coverage includes recurring invoices, 5 typed reports (P&L, tax, accounts aging, revenue, expense), and workflow tools like invoice-from-time and estimate-to-invoice conversion. pip install mcp-freshbooks to get the latest.

Zero to 33 Tools: Building the First MCP Server for ActiveCampaign

Alex LaGuardia — Thu, 26 Mar 2026 22:32:11 +0000

I searched GitHub, npm, PyPI, and every MCP registry I could find for an ActiveCampaign MCP server. Zero results. Not a bad one, not an incomplete one — nothing. For a platform with 185,000 paying customers and a full-featured API, that gap felt worth filling.

So I built it from scratch: 33 tools covering contacts, deals, automations, tags, pipelines, campaigns, custom fields, and webhooks.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, you manage your CRM and marketing automation without leaving your AI assistant.

Before (manual):

Log into ActiveCampaign
Navigate to Contacts → search for a customer
Check their tags, deals, automation history
Switch to your AI tool
Describe what you found
Ask for analysis

After (with mcp-activecampaign):

"Find all contacts tagged 'enterprise-lead' and show me their deal pipeline status. Which ones haven't been contacted in 30 days?"

Claude calls list_contacts with a tag filter, then list_deals for each, and gives you an actionable priority list — all in one shot.

33 Tools, Full CRM Coverage

Contacts (7): List, get, create, update, delete, search, manage tags
Deals (5): List, get, create, update, delete with pipeline/stage support
Tags (4): List, create, add to contact, remove from contact
Lists (2): List all, get details with subscriber counts
Automations (3): List, get details, add contacts to automations
Pipelines (2): List pipelines, list stages within pipelines
Custom Fields (3): List fields, get values, set values per contact
Campaigns (2): List campaigns with stats, get full campaign details
Accounts (2): List and get company/organization records
Webhooks (3): List, create, delete for real-time event handling

Technical Decisions Worth Sharing

Client-Side Rate Limiting

ActiveCampaign enforces 5 requests per second per account. Hit the limit and you get 429s that can cascade. Instead of reacting to failures, the client prevents them:

MAX_RPS = 5
MIN_INTERVAL = 1.0 / MAX_RPS  # 0.2s between requests

async def _throttle(self) -> None:
    """Enforce 5 req/s rate limit."""
    async with self._lock:
        now = time.monotonic()
        elapsed = now - self._last_request
        if elapsed < self.MIN_INTERVAL:
            await asyncio.sleep(self.MIN_INTERVAL - elapsed)
        self._last_request = time.monotonic()

An asyncio lock ensures thread safety, and time.monotonic() avoids clock-drift edge cases. If a 429 still slips through (burst from another client), there's a fallback that respects the Retry-After header:

if resp.status_code == 429:
    retry_after = float(resp.headers.get("Retry-After", "1"))
    await asyncio.sleep(retry_after)
    return await self._request(method, path, **kwargs)

Belt and suspenders. The AI never sees rate limit errors.

The "Deal Groups" Translation

ActiveCampaign calls pipelines "deal groups" internally. The API endpoint is /dealGroups, stages are filtered by d_groupid, and creating a deal requires a group field — not pipeline. This naming inconsistency trips up every integration:

@mcp.tool()
async def list_pipelines(limit: int = 20, offset: int = 0) -> str:
    """List deal pipelines (called 'deal groups' in AC API)."""
    data = await ac.get("/dealGroups", ...)
    for p in data.get("dealGroups", []):
        pipelines.append({
            "id": p["id"],
            "title": p.get("title", ""),
            ...
        })

The tools use the word "pipeline" (what users expect) while the client sends "dealGroup" (what the API expects). The AI works with natural language; the translation happens silently.

URL Normalization with API Path

ActiveCampaign API URLs look like https://youraccountname.api-us1.com/api/3/contacts. Users might pass just the account URL, or include the /api/3 suffix. The client normalizes both:

base_url = base_url.rstrip("/")
if not base_url.endswith("/api/3"):
    base_url = f"{base_url}/api/3"

Small thing, but it eliminates a common setup failure.

Read-Only Automations (And Being Honest About It)

ActiveCampaign's API doesn't support creating automations programmatically — you can only list them, view details, and add contacts to existing ones. The tool docstrings say this explicitly:

@mcp.tool()
async def list_automations(...) -> str:
    """List automations (read-only — AC API doesn't support creating automations)."""

When the AI knows the boundary, it can suggest alternatives ("Create the automation in the AC dashboard, then I can add contacts to it") instead of failing mysteriously.

Get Started in 2 Minutes

Install

pip install mcp-activecampaign

Get Your API Credentials

ActiveCampaign → Settings → Developer. You need:

API URL: https://youraccountname.api-us1.com
API Key: The key shown on that page

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "activecampaign": {
      "command": "mcp-activecampaign",
      "env": {
        "ACTIVECAMPAIGN_URL": "https://youraccountname.api-us1.com",
        "ACTIVECAMPAIGN_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add activecampaign -- env ACTIVECAMPAIGN_URL=https://youraccountname.api-us1.com ACTIVECAMPAIGN_API_KEY=key mcp-activecampaign

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Add deal note support. ActiveCampaign deals have a notes system that's heavily used by sales teams. I covered the core CRUD but skipped notes — they're high-value for AI-assisted sales workflows.

Build contact-to-deal linking tools. The current create_deal accepts a contact_id, but there's no tool to view or manage the contact-deal association after creation. That relationship is central to how AC users think about their CRM.

Lessons for MCP Server Builders

Rate limit proactively, not reactively. Client-side throttling is always better than hitting limits and retrying. Use asyncio.Lock + time.monotonic() for a clean implementation.
Translate internal naming to user naming. If the API calls something "dealGroups" but users call it "pipelines," use the user's word in your tools. The translation is invisible and the ergonomics improve dramatically.
Document API limitations in docstrings. If the platform doesn't support creating a resource via API, say so in the tool description. The AI uses docstrings to decide what to suggest.
Be the first mover. When you search for "[Platform] MCP server" and find zero results, that's a signal. 185K customers and nobody built this? Ship it.

Links

GitHub: AlexlaGuardia/mcp-activecampaign
PyPI: mcp-activecampaign
License: MIT

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: Mailchimp, WooCommerce, FreshBooks. Follow me here or on GitHub to catch the next one.

Update (April 2026): Since publishing, mcp-activecampaign has been expanded from 33 to 65 tools (v0.2.0). New coverage includes lead scoring, saved segments, campaign create/send, forms, goals, deal custom fields, CRM notes and tasks, event tracking, ecommerce, and bulk import. pip install mcp-activecampaign to get the latest.

How I Built a Full Product in One Night with 3 Parallel AI Agents

Alex LaGuardia — Wed, 25 Mar 2026 22:12:15 +0000

Last Thursday night I sat down to add session handoff to my Python library. I stood up 8 hours later with a complete product: MCP server, REST API, embedded dashboard, event triggers, signal compaction. From 1,200 lines to 5,900. From a CLI tool to something with a web UI.

Here's how, and why the technique matters more than the project.

The Setup

I'd built Vigil — an awareness daemon for AI agents. It worked great as a CLI tool: emit signals, compile state, boot agents with context. But it was missing the features that make it a real product: session handoff, an MCP server for Claude/Cursor integration, a REST API, and a dashboard.

Each of these features lives in its own module. They share the database layer but have no code dependencies on each other. That's the key insight.

The Technique: Parallel AI Windows

I opened three Claude Code terminal windows, each working on a separate file:

Window 1: Session handoff protocol (handoff.py)
Window 2: Signal compaction engine (compaction.py)
Window 3: MCP server mode (mcp_server.py)

Each window had the same context: the existing codebase, the database schema, the module interfaces. But they worked independently, writing to separate files. No merge conflicts.

While those three were building, I reviewed their output periodically and planned the next batch. When all three finished, I opened a single integration window that wired everything together: imports, CLI commands, shared database migrations.

Then I repeated the pattern:

Window 1: REST API (api.py)
Window 2: Dashboard templates (5 HTML pages)
Window 3: Event triggers (triggers.py)

Same idea. Independent files, parallel execution, single integration pass.

What Made It Work

1. Clean module boundaries. Every feature was a new file that imported from existing modules (db.py, signals.py, awareness.py). No feature needed to modify another feature's code. This isn't accidental — I designed the architecture knowing I'd build this way.

2. Stable interfaces. The database schema and the VigilDB API were stable. All three windows could from vigil.db import VigilDB and trust that the interface wouldn't change under them.

3. Integration is the bottleneck, not implementation. Each module took 30-60 minutes to build. Integration — wiring CLI commands, updating __init__.py, running the test suite — took 20 minutes per batch. The integration step is where I caught type mismatches, missing imports, and interface disagreements.

4. Mid-session code audit. After the first batch (handoff + compaction + MCP), I ran a full code audit before starting batch two. Found 3 critical issues and 6 important ones. Fixing them before building the REST API prevented those bugs from propagating.

The Numbers

Metric	Before (v0.1)	After (v1.0)	Delta
Lines of code	1,278	5,922	+4,644
Modules	7	13	+6
Tests	48	196	+148
CLI commands	7	14	+7

14 commits over 8 hours. Zero merge conflicts.

What I'd Do Differently

Start with the integration test, not the unit tests. Each window wrote unit tests for its module. But the integration tests — "emit a signal, compile awareness, check the dashboard shows it" — came last. If I'd written those first, I'd have caught interface mismatches earlier.

Define the REST API schema before building the dashboard. Window 2 (dashboard) had to guess what the API response shapes would be, because Window 1 (API) was still being built. A shared types file or API schema would have eliminated that friction.

Why This Matters Beyond My Project

The parallel AI window technique works for any codebase with clean module boundaries:

Microservices: Each window builds a different service
Frontend components: Each window builds a different page/component
Data pipelines: Each window builds a different stage

The constraint is the same: modules must be independently buildable with stable interfaces between them. If feature B needs to call feature A's code and that code doesn't exist yet, you can't parallelize them.

This is also a strong argument for writing clean interfaces first. The 30 minutes I spent designing VigilDB's API saved hours of integration pain later.

The Product

Vigil v1.5.0 is on PyPI. It gives AI agents persistent awareness across sessions:

Awareness daemon compiles system state every 90 seconds
Frame-based tool filtering reduces context by 75-85%
Signal protocol lets agents coordinate without direct communication
Session handoff with structured summaries and resume
MCP server with 12 tools (Claude Code, Cursor, Claude Desktop)
REST API with 20 endpoints and SSE event stream
Dashboard with live updates

pip install vigil-agent
vigil init
vigil daemon start

GitHub: github.com/AlexlaGuardia/Vigil

If you're building with AI coding assistants and want to move faster, try the parallel window technique on your next feature batch. The key is architecture that supports it — clean boundaries, stable interfaces, independent files.

I Built a Nervous System for AI Agents (Not Another Memory Store)

Alex LaGuardia — Wed, 25 Mar 2026 22:09:18 +0000

The Problem Nobody Talks About

Everyone's building AI agents. Nobody's building the infrastructure to keep them aware.

I've been running ~95 MCP tools across multiple AI agents for the past year — a coding assistant, a trading system, a creative writing setup. Three problems kept hitting me:

1. Cold starts. Every new session starts from zero. The agent has no idea what happened 5 minutes ago in a different session.

2. Token bloat. Loading 95 tool definitions into context burns ~50,000 tokens before the agent does a single useful thing. That's real money and real context window wasted on tools the agent won't use.

3. No coordination. Multiple agents working on the same system can't hand off work or share awareness without me copy-pasting context between them.

The existing tools (Mem0, Letta, LangGraph) solve pieces of this. Mem0 does memory retrieval. Letta does stateful agents. LangGraph does workflow state. But none of them give agents awareness — a continuously-compiled understanding of what's happening right now.

What If Agents Had a Nervous System?

Memory stores are filing cabinets. You put stuff in, you pull stuff out. That's useful, but it's not how awareness works.

Your nervous system doesn't wait for you to query it. It continuously processes signals from your environment and compiles them into a state that's instantly available. You don't boot up every morning and run SELECT * FROM memories WHERE relevant = true. You just... know what's going on.

That's what I built.

Vigil: The Six Ideas

1. The Awareness Daemon

A background process runs every 90 seconds, reading signals from agents and compiling them into "hot context" — a structured snapshot any agent can boot from instantly.

from vigil import VigilDaemon

daemon = VigilDaemon(
    db_path="vigil.db",
    compile_interval=90,
    awareness_file="AWARENESS.md",
)
daemon.start()

When an agent starts a session, it calls compiler.boot() and gets full context in under a second: active frame, current work, recent signals, priority queue. No startup latency.

The daemon also writes an AWARENESS.md file — human-readable, version-controllable. My agents and I read the same file.

2. Frame-Based Tool Filtering

This was the biggest win. Instead of loading all tools into every context, you tag tools with "frames" — named context modes.

from vigil.registry import tool, tool_count

@tool(name="deploy", description="Deploy to production",
      frames=["backend", "devops"])
async def deploy(args):
    ...

@tool(name="write_chapter", description="Write a story chapter",
      frames=["creative"])
async def write_chapter(args):
    ...

@tool(name="health", description="Health check",
      frames=["core"])  # Always visible
async def health(args):
    ...

tool_count()              # 3 (all tools)
tool_count("backend")     # 2 (deploy + health)
tool_count("creative")    # 2 (write_chapter + health)

An agent in "backend" mode never sees creative writing tools. In my setup, this took tool definitions from 95 down to 14-25 per session — a 75-85% reduction in tool-definition tokens. The LLM also makes better tool choices with fewer irrelevant options.

3. Signal Protocol

Agents communicate through signals — short, categorized messages with content budgets:

Type	Budget	Purpose
observation	400 chars	Regular activity updates
handoff	600 chars	Session conclusions
summary	800 chars	Comprehensive summaries
alert	300 chars	Urgent notifications

from vigil import SignalBus, VigilDB

db = VigilDB("vigil.db")
bus = SignalBus(db)

bus.emit("backend-agent", "Deployed auth service v2. Tests passing.")
bus.emit("frontend-agent", "Dashboard layout refactored for mobile.")

Content budgets prevent runaway data. The daemon reads these signals, synthesizes them into the awareness summary, and moves on. Agents don't talk to each other — they emit into the bus and the daemon handles the rest.

4. Session Handoff

This is what makes multi-session work actually work. Agents end sessions with structured summaries:

from vigil import HandoffProtocol

proto = HandoffProtocol(db)

proto.end_session(
    agent_id="backend-agent",
    summary="Shipped auth v2 with JWT tokens",
    files_touched=["auth.py", "middleware.py"],
    decisions=["Switched from session cookies to JWT"],
    next_steps=["Add rate limiting", "Write integration tests"],
)

# Next morning, different agent resumes
context = proto.resume("morning-agent")
# Includes: last handoff, signals since, pending next steps

Handoff chains track continuity across sessions. The resume context tells the next agent exactly what happened, what decisions were made, and what to do next. No more "remind me what we were working on."

5. Signal Compaction

Signals accumulate. Without compaction, your awareness context grows forever. Vigil uses tiered retention:

Raw signals — kept for 7 days
Daily summaries — synthesized from raw, kept for 30 days
Weekly digests — synthesized from daily, kept for 90 days
Monthly snapshots — permanent archive

vigil compact --dry-run  # Preview what would be compacted
vigil compact            # Run it

History stays manageable without losing important context.

6. Event Triggers

Pattern-match on signals and fire actions automatically:

from vigil import TriggerManager

triggers = TriggerManager(db)

triggers.create(
    name="alert-to-slack",
    signal_type="alert",
    agent_pattern="*",
    action_type="webhook",
    action_config={"url": "https://hooks.slack.com/..."},
)

"If any agent emits an alert, post to Slack." "If the backend agent goes silent for 2 hours, create a focus item." Triggers turn Vigil from a passive awareness layer into an active coordination system.

MCP Server: The Distribution Play

Everything above is available as an MCP server:

vigil serve                          # stdio (Claude Code, Claude Desktop)
vigil serve --transport sse          # SSE (remote clients)
vigil serve --transport http         # REST API + dashboard

12 MCP tools: boot, compile, signal, status, signals, handoff, resume, chain, stale, focus, frames, agents.

Any MCP-compatible client (Claude Code, Cursor, Windsurf, Claude Desktop) connects and gets persistent awareness. The agent boots with context, emits signals during work, and hands off when done. Next session picks up where it left off.

The Numbers

Metric	Value
Modules	14
Lines of code	7,100+
Tests	252
MCP tools	12
REST endpoints	20
Dashboard pages	5
Dependencies	0 (stdlib only, MCP is optional)
Infrastructure	SQLite (zero setup)

Why Not [Existing Tool]?

	Vigil	Mem0	Letta	LangGraph
Approach	Awareness daemon	Memory retrieval	Stateful runtime	State machine
Context	Pre-compiled, instant	Query on demand	LLM-managed	Checkpoint-based
Tool filtering	Frame-based (75-85% savings)	None	None	None
Multi-agent	Signal protocol + handoff	Shared memory	Single agent	Graph edges
Compaction	Tiered retention	None	LLM-managed	None
MCP native	Built-in server	No	No	No
Infrastructure	SQLite	API + LLM costs	Full runtime	LangChain ecosystem

These aren't competitors — they're complementary. Vigil handles awareness and coordination. Mem0 handles deep memory. Use both.

Get Started

pip install vigil-agent

vigil init
vigil signal my-agent "Starting work on the auth system"
vigil daemon start
vigil status

Or as an MCP server:

pip install "vigil-agent[mcp]"
vigil serve

252 tests. MIT license. Zero external dependencies.

GitHub: github.com/AlexlaGuardia/Vigil
PyPI: pypi.org/project/vigil-agent

This is v1.5.0. The roadmap includes a hosted multi-tenant platform, federation protocol for cross-org agent coordination, and eventually a hardware device (Pi-based always-on awareness hub). If you're building multi-agent systems and fighting the same problems, I'd love to hear how you're solving them.