Authors: Trevor Stuart

For the past year, I’ve been hearing a version of the same thing from engineering leaders: AI tools are working, productivity is up, the business case is there. And yet, something about the picture still feels incomplete. So we decided to go find out how widespread that feeling actually is. We surveyed 700 engineers and managers across five countries, and published the results in the State of Engineering Excellence 2026.

89% of engineering leaders say developer productivity has improved since deploying AI. It’s a clean story. AI is working. Engineering teams are moving faster.

But, we also found that 81% of those same leaders say code review time has gone up since deploying AI. Significantly up, in a lot of cases. And, developers estimate that roughly a third of their day is now consumed by AI-related work that remains largely invisible to traditional productivity metrics.

So which is it? Is AI making engineering teams more productive, or simply shifting effort into places they don’t yet measure? After sitting with this data for a few weeks, the answer is both. That’s the more honest read, even if it’s less satisfying.

The gap between generating code and shipping value

AI has been very good at increasing output. Simultaneously, it has not automatically delivered more shipped value.

I talked to a customer recently, a large enterprise engineering org, and they were genuinely proud of how much their output metrics had improved. Lines of code written, PR velocity per developer, tickets closed, features delivered. All of it up. Then we dug into what was actually making it to production, and the numbers looked much less clean. A meaningful share of AI-generated code was not getting to production.

Most organizations can tell you how much AI code was accepted. Very few can tell you how much of it actually landed in production, and that’s the number that matters. Hard dollars spent on agent compute that never shipped anything isn’t a productivity story. That’s a visibility gap, and it’s one most organizations aren’t measuring today.

What “invisible work” actually looks like

The 31% figure, the estimated share of developer time now consumed by AI-related work that appears in no metric, probably sounds abstract until you break down what it actually is.

It’s a developer sitting with a pull request for 45 minutes because the AI-generated code is technically correct but written in a style nobody on the team recognizes, and they need to fully understand it before they can approve it. It’s debugging a subtle edge case that the AI missed, which takes longer to track down than writing the function would have. It’s working with 10 agents in parallel on 10 different tasks. None of this makes it into velocity or cycle time, and even code review metrics only catch a fraction of it.

What this data shows is that organizations are running a business where the costs are partially off the books. You can show your CFO a 20% productivity improvement and that’s true. You just can’t show them what it cost to get there.

High confidence in a broken system is its own problem

The finding that surprised me most: 89% of engineering leaders say their current metrics accurately reflect AI’s impact. And 94% say key factors like tech debt, validation time, and developer burnout are missing from those same metrics.

When there’s no established standard for measuring something, people default to trusting the frameworks they already know. Not because they’ve validated them for the new environment, but because they’re familiar. High confidence in an incomplete system is a coping mechanism, not an accuracy signal.

The lesson: confidence in your measurement system should go up as you add instrumentation, not stay high when important dimensions of the work are still invisible. When 94% of leaders acknowledge gaps and only 6% think they’re equipped to close them, that’s not a minor calibration issue. That’s a signal worth taking seriously.

The trust problem is structural, not individual

54% of practitioners fear individual performance evaluations based on AI productivity data. Managers, by contrast, show far greater comfort with these systems: they are nearly four times more likely than developers to report having no concerns at all.

Measurement systems almost always get built top-down, by the people who won’t be measured by them. The practitioners who experience the day-to-day pressures of AI adoption, and who understand where invisible overhead actually lives, are rarely involved in defining the frameworks used to measure it. The result is a system that captures what leadership can see and misses what developers actually experience.

What developers said they need is straightforward: keep improvement data separate from performance evaluation, be transparent about what’s being measured, and involve them in defining the metrics. None of that is technically hard. It requires organizational commitment. When measurement feels like surveillance, you don’t get accurate data. You get people performing for the system instead of working in it.

What we’re doing about it at Harness

The productivity gains from AI are real. The problem is that organizations are making multi-year investment decisions with dashboards built for a different era, and the gap between what those dashboards show and what’s actually happening widens as AI adoption scales.

This is a problem we’ve been thinking deeply about at Harness. We’re working on new capabilities in Software Engineering Insights ( SEI) that are designed to give engineering leaders visibility into the full picture: not just how much code is being generated, but how much of it is shipping, what the review and validation overhead actually looks like, and where AI spend is producing returns versus producing churn.

We believe the next generation of engineering measurement needs to be built for AI-native workflows, and we’ll be sharing more about that direction in the coming weeks.

Getting the measurement right isn’t a reporting exercise. It’s what makes the productivity gains from AI sustainable.

Download the full State of Engineering Excellence 2026 report [here].

Originally published at https://www.harness.io on May 13, 2026.

AI Productivity Is Up. Are Your Metrics Keeping Up? was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Authors: Sunil Gattupalle, Dewan Ahmed

Engineers have been shipping pieces of “the graph” for years. Service maps. Dependency graphs. Knowledge graphs. RDF triples. The newest entrant is the context graph, and the reason it shows up now is specific: software is increasingly executed by agents, and agents need a model of how work actually happens, not just an index of what exists.

This post is a practical, vendor-neutral walkthrough of context graphs: what they are, what separates them from a knowledge graph, the components you’ll end up building, and the pitfalls that bite teams who try to ship one. I’ll be drawing on engineering writing from Glean and Harness where they’ve published useful frames, but the design decisions apply regardless of stack.

The shift from “what” to “how”

A knowledge graph answers questions about state. What services exist. Which team owns which repo. Which ticket is linked to which incident. The graph is a snapshot of relationships at a point in time.

A context graph answers a different question. How does work flow through this organization? When a P1 fires, what sequence of actions usually resolves it? When a deal moves from “pilot created” to “closed-won,” what steps are between those states, who runs them, and how long do they take? When a service hits an error rate threshold, what’s the typical path from alert to mitigation?

The Glean engineering team puts it concisely: “what” exists vs. “how” change happens. Their model treats actions as first-class nodes in the graph, with edges encoding causality and correlation. Other formulations exist, but the central idea is consistent across them.

Three layers that usually compose a context graph

Most production designs end up with a layered architecture, even if teams don’t always name the layers the same way:

Layer 1: knowledge graph. Entities and the static relationships between them. Service A depends on service B. User U owns repo R. Ticket T is linked to incident I. This is the substrate. Without it, you don’t know that “ACME Inc” in your CRM and “Acme” in support is the same customer, and any aggregate analysis turns to mush.

Layer 2: personal graph (or activity stream). A per-user temporal sequence of actions: viewed doc, edited file, commented on PR, joined channel, deployed service. The signals are noisy on their own. Real work is messy. People context-switch constantly, reuse the same document across efforts, and abandon threads only to pick them back up days later. The job at this layer is to stitch raw events into coherent units of work.

Layer 3: context graph. Aggregate, anonymized patterns derived from many personal graphs. This is where you get statements like “P1 incidents in this product area resolve in 30 minutes 80% of the time and almost always pass through these four steps.” It is a probabilistic model of organizational process, not a static workflow definition.

Another way to look at the same architecture: a context graph is two intertwined graphs operating over the same entities. One is structural — nodes and edges representing the static relationships in your organization. The other is executional — transitions and actions that move those entities through their lifecycle over time. The context graph emerges from their combination. Neither graph alone is sufficient: the structural one tells you what could be touched in a given situation, the executional one tells you what actually gets touched, and only the intersection produces a model that’s useful to an agent. The three layers above are one way to slice this; the structural/executional split is another, and they map onto each other cleanly. Layer 1 is mostly structural, Layer 2 is mostly executional, and Layer 3 is where the two are joined under a shared semantic frame.

Sitting under all three is a semantic layer that defines what each thing actually means: an “incident” in the graph maps to a specific schema, with specific attributes and lifecycle states, regardless of which tool emitted the event. Without this, you’re shoveling JSON between systems and hoping the LLM figures it out.

Why this is not the same as a knowledge graph

This question comes up constantly, so it’s worth being precise. A knowledge graph is structural. It models entities and explicit relationships. A context graph adds time and behavior. It models the temporal sequences of actions that move entities through their lifecycle.

You can build a useful knowledge graph without any context graph. People have been doing it for decades with RDF, property graphs, ontologies, and graph databases. What you can’t build without a context graph is a model of how work actually happens in your organization.

Concretely, a knowledge graph might tell you:

• service payments-api depends on auth-service
• auth-service is owned by team iam
• the on-call for iam this week is Priya

A context graph layered on top adds:

• 65% of payments-api outages last quarter were caused by config changes in auth-service
• the typical mitigation involves rolling back the change, paging the iam on-call, then reviewing the deploy in postmortem
• time from alert to mitigation is bimodal: under 15 minutes when the alert correlates with a recent auth-service deploy, 45+ minutes otherwise

Each of those statements requires walking entity relationships and looking at temporal action sequences. Neither layer is sufficient on its own.

Why this is not process mining either

There’s a related comparison worth making, because process mining shows up often in conversations about this and the differences are easy to miss. Traditional process mining assumes relatively structured enterprise workflows running through bounded event systems — ERP, CRM, BPM platforms with consistent event logs and a finite set of process types. The job is to reconstruct an actual process from those logs and then report or optimize against a predefined target. The environment is controlled. The schemas are known. The processes have names.

Context graphs operate in a different environment. The work being modeled is fragmented across chat, docs, tickets, source control, observability tools, calendars, and increasingly agent actions themselves. There is no single event log, no shared schema across tools, and no predefined target workflow to compare against. The underlying systems weren’t designed to emit process traces; the traces have to be inferred from messy signals across tools that don’t know about each other and weren’t built to be joined.

The objective also differs. Process mining tends toward reporting and optimization of workflows you already know exist. A context graph is trying to build an adaptive, agent-consumable model of how work actually happens across structured and unstructured systems — including the parts that no one has ever formally defined as a process. The output isn’t a dashboard for a process owner; it’s a substrate for agent reasoning that updates as the organization changes.

Put another way: process mining is an analytics problem in a controlled environment. Context graphs are a behavioral modeling problem in an uncontrolled one. The system isn’t mining workflows. It’s learning organizational behavior, and most of that behavior was never written down.

Why agents need this

LLMs can already call tools. The harder problem is that they don’t know which tools to call, in what order, on which entities, to accomplish a real task in your environment. They have no model of your organization’s process.

Documentation describes intent. Systems of record capture state. Neither captures the actual flow of work. When you ask an agent to “investigate this alert,” “draft this proposal,” or “onboard this customer,” it has to assemble the workflow itself, usually with limited success.

A context graph fills the gap. It gives an agent a learned model of “what tends to happen and in what order” for the situations the agent encounters. Instead of hard-coding workflows in playbooks, the system surfaces the most probable path for the current scenario, and the agent can deviate when the situation warrants.

There’s a related constraint that the Harness engineering team frames well: the context window is RAM, and RAM is finite. Every token spent on infrastructure noise is a token that can’t be spent on reasoning. A context graph is only useful if the agent can pull just the relevant slice of it into context at the moment it’s needed. Loading the whole graph blows the budget.

What an event in the graph actually looks like

There’s no standard schema yet, but the shape that recurs across implementations is roughly this. An abstracted trace step (the kind that gets aggregated into the context graph) might look like:

{

  "trace_id": "trace_8f2a...",

  "step_index": 3,

  "timestamp_relative_ms": 142000,

  "action_type": "comment",

  "tool_family": "ticketing",

  "entities": {

    "incident_id": "INC-2391",

    "service_id": "payments-api",

    "team_id": "iam"

  },

  "process_tags": ["investigate_alert", "p1_response"],

  "outcome": null,

  "duration_ms": 86000

}

Two things to notice. First, no raw text. No message bodies, no doc contents, no user identifiers. The aggregation is over abstracted steps, not raw activity. Second, knowledge graph entity IDs are first-class on every step. That’s how the context graph stays tied to the substrate. Without those IDs, the patterns you mine are interesting but not actionable.

Building one: components that matter

There’s no canonical architecture for context graphs yet. The components that recur across teams shipping one are roughly these.

1. Deep connectors and event capture

You can’t model what you can’t observe. The first investment is connector coverage broad enough to capture change events across the tools where work actually happens: source control, CI/CD, ticketing, chat, docs, calendars, observability, identity. Snapshot data is necessary but not sufficient. You need the event stream of changes over time.

This is harder than it sounds. Each tool has its own API, rate limits, and idea of what “changed” means. Identity reconciliation alone is its own minor industry. The same human is priya@example.com in Slack, priya.k@example.com in GitHub, and Priya Kumar (Engineering) in your HRIS. Until you can prove those are the same person, your aggregates lie to you.

2. The semantic layer

Before you put events in a graph, you need agreement on what entities mean. A deployment event from your CD tool, a release from your CI tool, and a change in your ITSM system might describe the same physical action, or three different ones. Without a canonical model, downstream queries are unreliable.

Harness’s framing is useful here: the semantic layer is the source of truth for the structure and meaning of the data, and it enforces consistent definitions across tools. This is not supporting infrastructure. It is the substrate the rest of the system depends on. Every aggregation, every query, and every agent decision downstream inherits its meaning from this layer. Get it wrong and the layers above don’t fail loudly; they produce confidently wrong output. You can implement it with formal ontologies, JSON Schema, protobuf, or a registry of resource types. The implementation choice is less consequential than the discipline of treating the canonical model as load-bearing and making every connector conform to it.

3. Trace stitching and task segmentation

Raw event streams are not directly useful. A given person edits a doc, switches to Slack, opens a PR, runs a build, comes back to the doc. Are those one task or three? The graph needs to carve continuous activity into bounded units of work.

The approaches that work in practice combine cheap signals (shared titles, links between artifacts, time windows, channel names) with an LLM step that looks at sequences of events and infers semantic boundaries: “this cluster looks like investigating an alert,” “these actions look like drafting a spec.” The output is a labeled task with a coarse type, a duration, and a set of entities touched.

The cheap signals do most of the work. The LLM step is for cases where the cheap signals disagree or run out. Reverse the order and you’ll burn a lot of tokens for marginal gains.

4. Aggregation and pattern mining

Once you have many personal task traces, you aggregate. Normalize each trace into a sequence of anonymized steps: action type, tool family, knowledge graph entities involved, derived process tags, lightweight timing. Compute similarity between traces. Group similar traces. Mine the most common paths.

The output is a probabilistic model: for situations of type X, the typical sequence is A, B, C with probabilities p1, p2, p3, and timing distributions T1, T2, T3.

The word “probabilistic” is doing real work in that sentence, and it’s worth pausing on. The graph is not canonical truth and shouldn’t be presented to downstream consumers as one. Real organizational processes are noisy, overlapping, partially observable, and constantly evolving. The same situation can resolve through three different paths depending on who’s on call, what week of the quarter it is, and which subsystem happened to fail first. A model that collapses that reality into a single deterministic process will quietly mislead the agents that consume it, and the failure mode is the worst kind: confident, plausible, wrong.

Good implementations carry the uncertainty forward rather than papering over it. Each inferred path gets a confidence score that reflects how well the underlying traces actually support it. Temporal weighting decays older traces so the model tracks recent reality instead of the org chart from six quarters ago. Competing paths for the same situation are kept as parallel hypotheses with their own probabilities, not collapsed into the highest-frequency one. Sparse situations are flagged as low-confidence rather than presented with false precision.

The agent consuming the graph then has to reason under that uncertainty: pick the most probable path when confidence is high, surface alternatives when it isn’t, and fall back to first-principles reasoning when the situation is novel enough that the graph has no strong signal. The graph’s job is to make the uncertainty legible to the agent above it, not to hide it behind a single most-likely answer.

The Glean blog calls out a useful constraint here: only treat a pattern as viable if it appears across at least k distinct users and n independent traces. Below that threshold, you’re modeling individuals, not processes, and you’re at real risk of leaking PII through deanonymization. Pick your k and n before you ship, not after.

5. Storage that supports both structured and semantic access

Pure graph stores are great for traversal but rigid for free-form text. Pure vector stores are great for semantic similarity but blind to structure. A hybrid approach is what most teams converge on: graph entities and edges for relationships, with text chunks tagged by entity IDs that get embedded for semantic search.

This is the same pattern that underpins KG + RAG systems more generally. The graph provides depth (relationships, lineage, ownership). The vector index provides breadth (matching free-form queries to relevant content). The semantic layer ties them together so that “the auth incident from yesterday” resolves to a specific node, not a set of approximately-relevant text fragments.

PLACEHOLDER: hybrid storage diagram. Show two parallel stores at the bottom (a graph database with nodes/edges, and a vector index with embeddings). Above them, a query layer that takes a natural-language question, decomposes it, hits both stores, and returns a unified result. Show entity IDs as the join key between the two stores. Optional: a third lane showing “process traces” stored as ordered sequences referencing the same entity IDs.

6. The feedback loop

A context graph that stops learning is a static playbook with extra plumbing. The architecture only pays off if agent and human actions feed back in as new traces. When an agent runs a workflow, the outputs (which tools it called, in what order, with what result, whether the user accepted the output) become training signal. Successful runs reinforce the patterns. Failed runs flag anti-patterns where the model’s predicted path didn’t match reality.

This is where the system starts to get interesting from a reinforcement-learning angle. The graph functions as a policy the agent samples actions from, and that policy updates as the agent acts. The Glean piece makes a good operational point on this: if your agents run outside the system that owns the graph, the graph evolves one way and agent behavior evolves another. You end up with two divergent versions of reality. The graph and the orchestration layer have to share a feedback path.

The OS analogy is more useful than it looks

Sunil Gattupalle at Harness frames the agent loop as an operating system. The mapping is more than rhetorical, and it does real design work for context graphs too:

• The context window is RAM. Finite. Everything the agent can see right now lives here.
• Tool calls are syscalls. Structured I/O between the agent and the rest of the world.
• The agent harness (MCP server, framework, custom orchestrator) is the kernel. It mediates access to underlying systems and enforces policy.
• The knowledge and context graphs are the filesystem. Persistent structured storage the agent can query.
• Schema discovery is virtual memory. The agent doesn’t load every type definition upfront. It pages in metadata when it needs it.

If you take that mapping seriously, the design constraints fall out cleanly. You don’t dump the whole context graph into the agent’s context window any more than you would cat the entire filesystem into RAM. You build query primitives that let the agent pull the slice it needs.

The Harness MCP redesign is a useful concrete example. The team went from 130+ endpoint-shaped tools to 11 generic verbs (list, get, create, update, execute, describe, diagnose, and a handful of others) backed by a registry that dispatches to the right resource type. The tool count stays constant; capability grows in the registry. Whatever your stack, the underlying lesson holds: keep the agent’s “menu” small, push capability into queryable backends, and let the agent reason about what to fetch rather than parse a giant tool catalog.

The same lesson applies to context graphs. You don’t expose 50 tools that each query one slice of the graph. You expose a small set of generic query verbs (describe_process, find_similar_traces, get_typical_path) and let the graph itself hold the variety.

PLACEHOLDER: agent loop / OS mapping diagram. Two columns side by side. Left column: classic OS stack (process → syscalls → kernel → drivers → hardware). Right column: agent stack (LLM reasoning → tool calls → harness/kernel → resource registry → backend systems and graphs). Horizontal arrows showing the analogous components.

Pitfalls worth watching

Patterns that go wrong in real implementations:

Storing events without entity resolution. If you can’t reliably say two different event streams are about the same logical entity, your aggregation is meaningless. Identity reconciliation is unglamorous and load-bearing.

Treating the context graph as static. Process changes constantly. Tools come and go. Teams reorg. If your graph stops ingesting and re-aggregating, it ages out fast. Anything older than a quarter is suspect for active processes.

Underinvesting in the semantic layer. Without a canonical model of what entities and actions mean, graph rot accelerates. New tools get integrated with ad-hoc mappings. Queries return inconsistent results. Engineers stop trusting it.

Hard-coding workflows on top of the graph. The whole point is that the system learns process. If you turn around and embed a fixed playbook on every common path, you’ve built a regular workflow engine with extra plumbing.

Ignoring k-anonymity in aggregation. Aggregate process insights derived from a small number of users are deanonymized personal graphs in disguise. Pick a threshold and enforce it before you ship.

Letting context drift from execution. This is the divergence problem above. The graph that informs the agent and the system the agent acts in have to share a feedback path, or they will desynchronize within weeks.

Loading the wrong thing into context. A 50KB process description in the agent’s working memory is 50KB you don’t have for reasoning. Design the graph’s query API to return small, focused slices. If the only way to use the graph is to dump it, the agent will degrade.

How to evaluate one

A common question once you have a context graph is whether it’s actually useful. Some signals worth tracking:

Coverage. What fraction of meaningful work in your org is represented in the graph? If your most expensive processes aren’t in it, the graph isn’t helping where it matters.

Path agreement. When an expert is asked to describe how X usually happens, does their description match the graph’s most probable path for X? This is a sanity check for trace stitching and aggregation. Disagreement is informative either way: either the graph is wrong, or the expert is describing the ideal rather than what really happens.

Agent task completion. Agents grounded in the graph should complete relevant tasks at higher success rates than agents using only documentation or only tool descriptions. If they don’t, the graph is too noisy or too sparse, and you have a calibration problem upstream.

Time-to-fresh. How long after a real-world process changes does the graph reflect it? If it takes weeks, you have built a museum, not a model.

Context cost. What’s the average number of tokens an agent spends pulling relevant context from the graph for a given task? Track this over time. If it’s growing, your query API is leaking abstraction.

A question I haven’t seen good answers to yet

There isn’t a standard schema for context graphs the way there is for distributed traces (OpenTelemetry) or feature stores. Every team rolls their own. That’s fine for now because the design space is still being explored, but it makes federation across organizations and tools harder than it needs to be. The closest adjacent standard is OCSF for security events, which has the right shape but the wrong domain.

If you’re building a context graph today, document your schema with the same rigor you’d apply to a public API. Future-you, and any other team that integrates with your graph, will appreciate it.

Closing

Context graphs sit at the intersection of three things engineers have been shipping pieces of for years: knowledge graphs, activity streams, and agentic systems. The new and useful synthesis is the combination. A context graph captures how work actually happens, not just what exists, and it gives agents a structured, queryable model of process to ground their reasoning in.

Whether you call it a context graph, a process graph, a behavioral graph, or just an aggregate activity model, the design constraints are the same. Capture events at depth. Resolve entities to canonical forms. Stitch traces into tasks. Aggregate patterns under privacy thresholds. Store hybrid (graph plus vector). Treat agent execution as both consumer and producer of the graph. Keep the agent’s working memory clean.

The teams building this well aren’t reinventing graph databases. They’re applying old systems-engineering principles (small stable interfaces, demand paging, content-addressable storage, feedback loops) to a problem that’s only become tractable in the last couple of years.

References

• David Huynh and Pradeep Vaghela, “How do you build a context graph?”, Glean Engineering blog
• Sunil Gattupalle, Rohan Gupta, and Shubham Jindal, “Architecting MCP for AI Agents: Lessons from Our Redesign”, Harness Engineering blog
• Sunil Gattupalle, “The Agent Loop Is the New OS: Design Philosophy of the Harness MCP Server”, Harness Engineering blog
• Sunil Gattupalle, “Knowledge Graph + RAG: A Unified Approach to DevOps Intelligence”, Harness Engineering blog

Originally published at https://www.harness.io on May 18, 2026.

What a Context Graph Actually Is, and How to Build One was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Author: Sunil Gattupalle

The design of the Harness MCP (Model Context Protocol) server is driven by a pattern that keeps reappearing across systems that scale well: small, stable interfaces with most of the complexity pushed behind a dispatch layer. The central idea is this: the agent loop behaves like an operating system boundary. The LLM is the reasoning engine, the context window is working memory, tool calls act like syscalls, and the MCP server serves as a kernel that mediates access to underlying systems. This isn’t a literal equivalence, but it’s a useful design lens. It forces you to think in terms of memory pressure, interface stability, and clean I/O contracts.

We built the Harness MCP server to make Harness agent-native. In practice, that means exposing the platform through a runtime-discoverable, schema-driven interface that agents can inspect, select from, and compose without hardcoded knowledge of the domain. Today, that interface consists of 10 generic tools that dispatch to 30 toolsets covering 140+ resource types across the platform, along with 57 Knowledge Graph views for cross-module analytics.

Those numbers matter less than the constraint behind them: tool count stays constant while capability scales through data and dispatch. The goal is to keep the agent’s context focused on reasoning, not on parsing a large menu of endpoints.

Before getting into the architecture, though, it’s worth asking a simpler question: why does Claude feel so capable when you give it nothing more than a bash shell?

Why Claude Feels Powerful with Just Bash

The Contrast

Give Claude access to a terminal. Just bash. No APIs, no SDKs, no custom tools. It can navigate an unfamiliar codebase, find a bug across 50 files, refactor code, run tests, and commit end-to-end.

Now give an LLM access to a hundred perfectly-documented REST endpoints. It gets confused by the tool count, picks the wrong endpoint, and loses track of multi-step operations.

The difference isn’t the tools themselves. It’s the shape of the interface. The point isn’t that shell text streams are superior to structured APIs, but that agents perform better with interfaces that have a small, consistent grammar and are easy to compose.

What Makes Bash Work

Bash provides three properties that matter enormously for agent reasoning:

Composability. Every Unix tool does one thing and communicates through a uniform interface: text streams. grep | sort | uniq -c | head is four tools composed into an analytical pipeline. The agent doesn’t need to know about a special “count-unique-matches” API. It composes primitives.

Uniform interface. Every tool takes text in and produces text out. There’s no per-tool protocol, no per-tool authentication, no per-tool response schema. The contract is always the same: stdin, stdout, and exit code.

Introspection. ls, find, file, cat, head — the agent can discover what exists at runtime. It doesn’t need to memorize the file system layout. It explores, then acts.

These three properties mean the agent doesn’t need to hold 200 tool schemas in its context window. It learns a small set of verbs and composes them. The intelligence isn’t in any single tool. It’s in the loop that decides what to call next.

The Deeper Insight

Watch what actually happens when Claude debugs with bash:

1. Observe:     ls src/                    → see the project structure
2. Hypothesize: "error likely in auth module"
3. Act:         grep -r "token" src/auth/
4. Observe:     see the grep output
5. Refine:      "ah, token expiry not handled"
6. Act:         cat src/auth/session.ts
7. Observe:     read the file
8. Fix:         edit the file
9. Verify:      npm test

This is not “call the right API.” This is a reasoning loop — observe, hypothesize, act, verify. The bash commands are just I/O. The reasoning happens between them.

This loop is the program. The tools are the I/O. And the design of the tools determines how efficiently the loop can run.

The Agent Loop — What’s Actually Happening

The Event Loop

Every agent, whether it’s Claude in a terminal, Cursor with MCP tools, or a custom orchestrator, runs some version of this loop:

while (!task_done) {    
context   = observe(environment)       // tool outputs, previous results    
plan      = reason(context, goal)      // LLM inference    
action    = select_tool(plan)          // tool selection    
result    = execute(action)            // tool call    
environment.update(result)             // state change
}

This is an event loop. The LLM is the scheduler (the scheduling behavior is an emergent property of the loop, not an intrinsic property of the LLM). The tools are I/O operations. The context window is working memory. Each iteration, the agent observes the current state, reasons about what to do next, selects a tool, executes it, and incorporates the result into its context.

Where the Intelligence Lives

The critical insight: the intelligence is in the loop, not in the tools. The tools just move information in and out. The loop is what plans, backtracks, retries, composes, and converges.

This means the quality of the agent’s output depends on two things:

1. The loop’s ability to reason, which is a function of the LLM’s capability and the available context
2. The quality of I/O, which is a function of tool design (clear, structured, context-efficient)

If the tools are well-designed (few, composable, self-describing, context-efficient), the loop can reason clearly. If the tools are poorly designed (many, verbose, opaque), the loop spends its context budget parsing menus and payloads instead of thinking.

The MCP Server’s Role

Our MCP server does not implement the agent loop. The loop lives in the MCP host: Cursor, Claude Desktop, or whatever IDE/agent framework the user is running. Our server is stateless at the request level: each tool call arrives as a JSON-RPC message, runs an async handler, and returns a structured response. Task-level state lives in the MCP host and in the underlying Harness systems.

We implement the kernel that the loop dispatches into. Our job is to make each dispatch fast, clean, and context-efficient.

Systems That Just Click: We’ve Seen This Pattern Before

Before drawing the OS analogy, it’s worth stepping back. The properties that make bash work for agents, composability, uniform interface, and runtime discovery, aren’t unique to Unix. They show up in every long-lived system that engineers describe as “just working.”

Linux: The syscall ABI has been stable for decades. The VFS (Virtual File System) is a dispatch table: open(), read(), write(), close() work against ext4, NFS, procfs, sysfs, and any backend. New filesystem? Write a driver, load it at runtime. The interface never changes. /proc and /sys let the kernel describe itself through runtime introspection.

Git: Content-addressable blobs plus a handful of verbs. Branches are just pointers. The plumbing/porcelain split gives you a tiny, stable core with everything else built through composition. The transport protocol is uniform: push/fetch work the same over HTTP, SSH, or a local filesystem.

Kubernetes: Declare desired state. Controllers reconcile. kubectl get, apply, describe work on any resource kind: Pods, Services, your custom CRDs. New capability = new CRD, not a new CLI.

SQL: Small grammar: SELECT, JOIN, WHERE, GROUP BY. Works against any schema. The engine optimizes. You declare intent. The grammar has been stable for 40 years.

The Shared DNA

These systems share five properties:

1. Small, stable interface: few verbs, many nouns
2. Uniform contract: same interaction pattern regardless of backend
3. Runtime discovery: the system describes itself
4. Dispatch layer: a central mechanism that routes requests to domain-specific handlers
5. Extend without changing the core interaction model: new capabilities don’t require changing the existing interface.

This is the design target for agent infrastructure.

The Gap in REST: What MCP Had to Fill

REST APIs answered two questions well:

• WHAT: what resources exist (/pipelines, /services, /executions)
• HOW: how to operate on them (GET, POST, PUT, DELETE)

For programs, code written by humans who already understood the domain, this was enough.

The developer read the docs, wrote the integration, and deployed it. The logic was pre-written.

An agent encounters your API at runtime, with no prior knowledge. It needs a third answer:

WHY:

• Why would I use this tool?
• What does it return?
• When should I prefer it over another tool?
• What are the side effects?

This “why” lived in documentation, READMEs, and developers’ heads. It was never machine-readable. MCP fills this gap by making tools carry their own intent — descriptions, hints (readOnlyHint, destructiveHint), schemas, and metadata that the agent reads at runtime to decide what to call.

The difference between REST and MCP isn’t the transport. It’s the audience. REST APIs are typically optimized for pre-written integrations. MCP tool surfaces are optimized for runtime selection and composition by an agent.

The OS Analogy: A Systems Engineer’s Guide to Agent Platforms

The mapping between operating systems and agent platforms is more than metaphorical — parts of it are structural, and the rest provide a useful design vocabulary. The same engineering constraints apply, and the same design principles solve them.

The Full Mapping

Context Is RAM

This is the most important mapping, and it has direct engineering consequences.

The context window is finite. Every token you put in is a token that can’t be used for something else. Verbose API responses, unnecessary fields, large tool schemas: these are all memory allocations. If you fill the context with data, the agent can’t reason.

The OS parallels are precise:

The #1 job of an agent platform is to keep the context window clean for reasoning. Every architectural decision should be evaluated through this lens: does this consume more or less of the context budget?

Syscalls, Not Raw I/O

Programs don’t write directly to disk. They call write(), and the kernel handles buffering, permissions, journaling, and device-specific quirks. This abstraction is what makes programs portable and reliable.

The same applies to agents. An agent shouldn’t construct HTTP requests with auth headers, manage pagination cursors, handle retry backoff, or parse nested response wrappers. It should call a tool — a syscall — and the MCP server (the kernel) handles all of that.

The tool is the syscall. The MCP server is the kernel. Same contract every time. The agent never has to think about x-api-key headers, accountIdentifier query parameters, or exponential backoff on HTTP 429.

Virtual Memory = Schema Discovery

An OS doesn’t load every file into RAM upfront. It uses virtual memory — a large address space backed by on-demand paging. Hot pages stay in RAM; cold pages live on disk until needed.

Our MCP server applies the same pattern to domain knowledge. The agent’s “address space” covers 140+ resource types. But at any given moment, only the relevant metadata occupies context:

• Need pipeline fields? → harness_describe(resource_type=’pipeline’) loads ~500 tokens
• Need execution details? → harness_describe(resource_type=’pipeline_execution’) loads ~3K tokens of type catalog
• Need pipeline schema? → harness_schema(resource_type=’pipeline’), loaded only when constructing pipeline, and enables progressive discovery

This is demand paging for domain knowledge. The agent discovers what it needs, when it needs it, and the rest stays “on disk” (available but not occupying context).

Our Architecture Through This Lens

The Three-Layer Stack

The MCP server has three layers, each corresponding to a layer in the OS model:

Harness MCP Server Architecture

Layer 1 — MCP Tool Surface (syscall table). Ten generic tools that accept a resource_type parameter and dispatch through the registry. These are registered with the MCP SDK using Zod schemas for input validation. Each tool handler is a thin wrapper: normalize inputs → call registry → format response.

Layer 2 — Registry (kernel). The Registry class in src/registry/index.ts is the core dispatch engine. It holds a Map<string, ResourceDefinition> populated from 30 toolset files. When a tool handler calls registry.dispatch(client, resourceType, operation, input), the registry resolves the ResourceDefinition, looks up the EndpointSpec, and calls executeSpec() — the single execution pipeline that handles path templating, scope injection, query parameter building, body construction, auth header interpolation, HTTP dispatch, response extraction, and deep link generation.

Layer 3 — HarnessClient (block device driver). The raw HTTP client in src/client/harness-client.ts. Handles fetch() with the x-api-key auth header, accountIdentifier injection, retry with exponential backoff on 429/5xx, client-side rate limiting, timeouts, and response parsing.

The Syscall Table

The agent learns 10 verbs. They work against every domain in Harness.

Why Tool Count Matters

Every tool the agent “sees” costs tokens:

Our approach keeps this at ~1.2%. Tool count stays O(1). Capabilities grow O(n). This is the core design invariant.

The Dispatch Table (vtable)

The registry is a vtable — a dispatch table that maps (resource_type, operation) to an EndpointSpec and executes it through a unified pipeline. One execution path. Every resource type. Every operation.

Design Patterns

Pattern 1: Generic Verbs + Type Dispatch

Principle: Don’t create a tool per API endpoint. Create generic verbs that dispatch by resource type through a registry.

This is the same insight behind REST (uniform interface + varying resources) and Unix (uniform file interface + varying devices). The agent learns the grammar once — list, get, create, execute. New nouns (resource types) are just data in the registry.

Pattern 2: Declarative Over Imperative

Principle: Resource definitions are data structures, not handler functions.

Each API mapping is expressed as an EndpointSpec — a declarative object that describes the HTTP method, path, path parameters, query parameter mappings, body builder, response extractor, and metadata. The registry’s executeSpec() reads this spec and handles execution.

• Auth, retry, pagination, rate limiting, deep links — all handled once in the registry
• New resource types get these behaviors automatically
• Changes to the execution pipeline propagate to every resource type

This means:

Pattern 3: Fix Once in the Kernel, Every Driver Benefits

Principle: Centralized dispatch creates compounding returns on infrastructure investment.

Features that propagate everywhere through the registry:

Pattern 4: Validate Before Execute

Move error detection left. Validate agent-generated inputs before spending API budget on execution.

When an agent tries to create or execute something, validate the inputs before committing. If the agent provides a malformed pipeline YAML or references a nonexistent service, catch it at the schema level — before the API call burns tokens on a 400 error and the agent has to parse the response to figure out what went wrong.

harness_execute(
resource_type='pipeline', action='run', 
inputs={branch: 'main', service: 'payment-svc'}
) 
← Error: input 'service' is not a valid runtime input for this pipeline.    
Valid inputs: branch, environment, tag. Did you mean 'environment'?
// Agent retries with corrected inputs. Typically converges in one retry.

Validation is cheap — milliseconds. Wrong answers are expensive — broken trust, bad decisions. This is compile-time checking for agent-generated operations.

Pattern 5: Runtime Reflection Over Static Documentation

Principle: Let agents discover your domain model at runtime. Self-describing systems don’t need documentation updates.

Add a new toolset → the agent discovers it immediately. Add a new resource type → the agent can query it immediately. This is introspection — ls for your platform. The same thing that makes bash work for agents.

Anti-Patterns

Anti-Pattern 1: One Tool Per Endpoint

Problem: Creating list_pipelines, get_pipeline, list_services, etc. Each tool costs ~150 tokens. At 50 tools, that’s 7,500 tokens of menu.

Fix: Generic verbs with type dispatch.

Anti-Pattern 2: Raw API Passthrough

Problem: Returning the full Harness API response — 50+ fields, nested wrappers.

Fix: Use responseExtractor to return clean, relevant fields. Treat context tokens like memory allocations.

Anti-Pattern 3: Hardcoded Domain Knowledge

Problem: Embedding field lists or API shapes in tool descriptions. They go stale immediately.

Fix: Keep tool descriptions generic. Point to harness_describe() for runtime discovery.

Anti-Pattern 4: Context-Window Aggregation

Problem: Agents often fetch large datasets and aggregate in context, leading to extremely high token usage and degraded accuracy.

Fix: Routing aggregation to the Knowledge Graph dramatically reduces token usage and improves answer reliability.

Anti-Pattern 5: Bloating Server Instructions

Problem: Adding per-resource docs to instructions in src/index.ts.

Fix: Keep instructions under ~20 lines. Put resource-specific guidance in description, diagnosticHint, executeHint, and bodySchema.description on the EndpointSpec.

Conclusion

The agent loop is the new operating system. That’s not a rhetorical flourish. It’s a constraint with real engineering consequences.

Every design decision in the Harness MCP server follows from a single principle: the context window is RAM, and RAM is finite. Verbose responses trash it. Oversized tool menus fragment it. Redundant schemas waste it. The agent’s ability to reason, to observe, hypothesize, act, and verify, degrades in direct proportion to how much of that budget gets consumed by infrastructure noise instead of domain signal.

The patterns described here, generic verbs with type dispatch, declarative resource definitions, demand-paged schema discovery, and centralized kernel dispatch, aren’t novel. They’re the same patterns that made Unix, Git, Kubernetes, and SQL endure for decades: small, stable interfaces, uniform contracts, runtime introspection, and the ability to extend without changing the core interaction model.

What’s different is the audience. Those systems were designed for programs. This one is designed for reasoning systems operating at runtime.

If you’re building agent infrastructure, the questions to ask are the same ones OS designers asked in the 1970s: Does this abstraction compose? Does it describe itself? Does it keep the critical resource, then RAM, now context, available for the work that actually matters?

A useful test for any tool, schema, or abstraction is simple: does it reduce the amount of information the agent has to hold in working memory, or increase it? If it increases it, it’s probably making the system worse.

-

If you found this useful, follow and subscribe to the Harness Engineering blog for more deep dives on building agent-native systems and modern developer infrastructure.

‍

Originally published at https://www.harness.io on April 23, 2026.

The Agent Loop Is the New OS: Design Philosophy of the Harness MCP Server was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

As an enterprise chaos engineering platform vendor, validating chaos faults is not optional — it’s foundational. Every fault we ship must behave predictably, fail safely, and produce measurable impact across real-world environments.

When we began building our end-to-end (E2E) testing framework, we quickly ran into a familiar problem: the barrier to entry was painfully high.

Running even a single test required a long and fragile setup process:

• Installing multiple dependencies by hand
• Configuring a maze of environment variables
• Writing YAML-based chaos experiments manually
• Debugging cryptic validation failures
• Only then… executing the first test

This approach slowed feedback loops, discouraged adoption, and made iterative testing expensive — exactly the opposite of what chaos engineering should enable.

The Solution: A Simplified Chaos Fault Validation Framework

To solve this, we built a comprehensive yet developer-friendly E2E testing framework for chaos fault validation. The goal was simple: reduce setup friction without sacrificing control or correctness.

The result is a framework that offers:

• An API-driven execution model instead of manual YAML wiring
• Real-time log streaming for faster debugging and observability
• Intelligent target discovery to eliminate repetitive configuration
• Dual-phase validation to verify both fault injection and system impact

What previously took 30 minutes (or more) to set up and run can now be executed in under 5 minutes — consistently and at scale.

A real execution run — proving that chaos validation doesn’t have to be chaotic — From theory to turbulence

System Architecture

High-Level Architecture

High-level architecture

Layer Responsibilities

Core Components

1. Experiment Runner

Purpose: Orchestrates the complete chaos experiment lifecycle from creation to validation.

Key Responsibilities:

• Experiment creation with variable substitution
• Log streaming and target discovery
• Concurrent validation management
• Status monitoring and completion detection
• Error handling and retry logic

Architecture Pattern: Template Method + Observer

type ExperimentRunner struct {
    identifiers utils.Identifiers
    config      ExperimentConfig
}
type ExperimentConfig struct {
    Name                  string
    FaultName             string
    ExperimentYAML        string
    InfraID               string
    InfraType             string
    TargetNamespace       string
    TargetLabel           string
    TargetKind            string
    FaultEnv              map[string]string
    Timeout               time.Duration
    SkipTargetDiscovery   bool
    ValidationDuringChaos ValidationFunc
    ValidationAfterChaos  ValidationFunc
    SamplingInterval      time.Duration
    }

Execution Flow:

Run() → 
  1. getLogToken()
  2. triggerExperimentWithRetry()
  3. Start experimentMonitor
  4. extractStreamID()
  5. getTargetsFromLogs()
  6. runValidationDuringChaos() [parallel]
  7. waitForCompletion()
  8. Validate ValidationAfterChaos

2. Experiment Monitor

Purpose: Centralized experiment status tracking with publish-subscribe pattern.

Architecture Pattern: Observer Pattern

type experimentMonitor struct {
    experimentID string
    runResp      *experiments.ExperimentRunResponse
    identifiers  utils.Identifiers
    stopChan     chan bool
    statusChan   chan string
    subscribers  []chan string
}

Key Methods:

• start(): Begin monitoring (go-routine)
• subscribe(): Create subscriber channel
• broadcast(status): Notify all subscribers
• stop(): Signal monitoring to stop

Benefits:

• 80% reduction in API calls
• 92% faster failure detection
• Single source of truth
• Easy to add new consumers

3. Validation Framework

Purpose: Dual-phase validation system for concrete chaos impact verification.

ValidationDuringChaos

• Runs in parallel during experiment
• Continuous sampling at configurable intervals
• Stops when validation passes
• Use case: Verify active fault impact

ValidationAfterChaos

• Runs once after experiment completes
• Single execution for final state
• Use case: Verify recovery and cleanup

Function Signature:

type ValidationFunc func(targets []string, namespace string) (bool, error)
// Returns: (passed bool, error)

Sample Validation Categories:

Experiment Execution Engine

Execution Phases

Phase 1: Setup
├─ Load configuration
├─ Authenticate with API
└─ Validate environment

Phase 2: Preparation
├─ Get log stream token
├─ Resolve experiment YAML path
├─ Substitute template variables
└─ Create experiment via API

Phase 3: Execution
├─ Trigger experiment run
├─ Start status monitor
├─ Extract stream ID
└─ Discover targets from logs

Phase 4: Validation (Concurrent)
├─ Validation During Chaos (parallel)
│  ├─ Sample at intervals
│  ├─ Check fault impact
│  └─ Stop when passed/completed
└─ Wait for completion

Phase 5: Post-Validation
├─ Validation After Chaos
├─ Check recovery
└─ Final assertions

Phase 6: Cleanup
├─ Stop monitor
├─ Close channels
└─ Log results

State Machine

Concurrency Model

Main Thread:
├─ Create experiment
├─ Start monitor goroutine
├─ Start target discovery goroutine
├─ Start validation goroutine [if provided]
└─ Wait for completion
Monitor Goroutine:
├─ Poll status every 5s
├─ Broadcast to subscribers
└─ Stop on terminal status
Target Discovery Goroutine:
├─ Subscribe to monitor
├─ Poll for targets every 5s
├─ Listen for failures
└─ Return when found or failed
Validation Goroutine:
├─ Subscribe to monitor
├─ Run validation at intervals
├─ Listen for completion
└─ Stop when passed or completed

API Integration Layer

API Client Architecture

Variable Substitution System

Template Format: {{ VARIABLE_NAME }}

Built-in Variables:

INFRA_NAMESPACE          // Infrastructure namespace
FAULT_INFRA_ID          // Infrastructure ID (without env prefix)
EXPERIMENT_INFRA_ID     // Full infrastructure ID (env/infra)
TARGET_WORKLOAD_KIND    // deployment, statefulset, daemonset
TARGET_WORKLOAD_NAMESPACE // Target namespace
TARGET_WORKLOAD_NAMES   // Specific workload names (or empty)
TARGET_WORKLOAD_LABELS  // Label selector
EXPERIMENT_NAME         // Experiment name
FAULT_NAME              // Fault type
TOTAL_CHAOS_DURATION    // Duration in seconds
CHAOS_INTERVAL          // Interval between chaos actions
ADDITIONAL_ENV_VARS     // Fault-specific environment variables

Custom Variables: Passed via FaultEnv map in ExperimentConfig.

Validation Framework

Architecture

Validation Categories

1. Resource Validators

ValidatePodCPUStress(targets, namespace) (bool, error)
ValidatePodMemoryStress(targets, namespace) (bool, error)
ValidateDiskFill(targets, namespace) (bool, error)
ValidateIOStress(targets, namespace) (bool, error)

Detection Logic:

• CPU: Usage > baseline + 30%
• Memory: Usage > baseline + 20%
• Disk: Usage > 80%
• I/O: Read/write operations elevated

2. Network Validators

ValidateNetworkLatency(targets, namespace) (bool, error)
ValidateNetworkLoss(targets, namespace) (bool, error)
ValidateNetworkCorruption(targets, namespace) (bool, error)

Detection Methods:

• Ping latency measurements
• Packet loss percentage
• Checksum errors

3. Pod Lifecycle Validators

ValidatePodDelete(targets, namespace) (bool, error)
ValidatePodRestarted(targets, namespace) (bool, error)
ValidatePodsRunning(targets, namespace) (bool, error)

Verification:

• Pod age comparison
• Restart count increase
• Ready status check

4. Application Validators

ValidateAPIBlock(targets, namespace) (bool, error)
ValidateAPILatency(targets, namespace) (bool, error)
ValidateAPIStatusCode(targets, namespace) (bool, error)
ValidateFunctionError(targets, namespace) (bool, error)

5. Redis Validators

ValidateRedisCacheLimit(targets, namespace) (bool, error)
ValidateRedisCachePenetration(targets, namespace) (bool, error)
ValidateRedisCacheExpire(targets, namespace) (bool, error)

Direct Validation: Executes redis-cli INFO in pod, parses metrics

Validation Best Practices

Data Flow & Lifecycle

Complete Experiment Lifecycle

Data Structures Flow

// Input
ExperimentConfig
    ↓
// API Creation
ExperimentPayload (JSON)
    ↓
// API Response
ExperimentResponse {ExperimentID, Name}
    ↓
// Run Request
ExperimentRunRequest {NotifyID}
    ↓
// Run Response
ExperimentRunResponse {ExperimentRunID, Status, Nodes}
    ↓
// Log Streaming
StreamToken + StreamID
    ↓
// Target Discovery
[]string (target pod names)
    ↓
// Validation
ValidationFunc(targets, namespace) → (bool, error)
    ↓
// Final Result
Test Pass/Fail with error details

Performance & Scalability

Performance Metrics

Concurrent Test Execution

• Each test gets isolated namespace
• Separate experiment instances
• No shared state between tests
• Parallel execution supported

Example Usage of Framework

RunExperiment(ExperimentConfig{
    Name: "CPU Stress Test",
    FaultName: "pod-cpu-hog",
    InfraID:         infraID,
    ProjectID:       projectId,
    TargetNamespace: targetNamespace,
    TargetLabel:     "app=nginx", // Customize based on your test app
    TargetKind:      "deployment",
    FaultEnv: map[string]string{
     "CPU_CORES":            "1",
     "TOTAL_CHAOS_DURATION": "60",
     "PODS_AFFECTED_PERC":   "100",
     "RAMP_TIME":            "0",
    },
    Timeout:          timeout,
    SamplingInterval: 5 * time.Second, // Check every 5 seconds during chaos
    
    // Verify CPU is stressed during chaos
    ValidationDuringChaos: func(targets []string, namespace string) (bool, error) {
         clientset, err := faultcommon.GetKubeClient()
         if err != nil {
          return false, err
         }
         return validations.ValidatePodCPUStress(clientset, targets, namespace)
    },
    
    // Verify pods recovered after chaos
    ValidationAfterChaos: func(targets []string, namespace string) (bool,error) {
        clientset, err := faultcommon.GetKubeClient()
        if err != nil {
         return false, err
        }
        return validations.ValidateTargetAppsHealthy(clientset, targets, namespace)
    },
})

Knowledge Sharing and Learning

While this framework is proprietary and used internally, we believe in sharing knowledge and best practices. The patterns and approaches we’ve developed can help other teams building similar testing infrastructure:

Key Takeaways for Your Team

Whether you’re building a chaos engineering platform, testing distributed systems, or creating any complex testing infrastructure, these principles apply:

1. Measure your baseline — Know how long things take today
2. Set ambitious goals — 10x improvements are possible
3. Prioritize DX — Developer experience drives adoption
4. Automate ruthlessly — Eliminate manual steps
5. Share your learnings — Help others avoid the same pitfalls
6. Collect user feedback
7. Celebrate improvements!

We hope these insights help you build better testing infrastructure for your team!

Questions? Feedback? Ideas? Join Harness community. We’d love to hear about your testing challenges and how you’re solving them!

Theory to Turbulence: Building a Developer-Friendly E2E Testing Framework for Chaos Platform was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Author: Richard Black

Picture this. What should have been a routine Infrastructure as Code upgrade suddenly triggers a legal review, a compliance escalation, and an awkward platform meeting nobody planned for. Just the kind of chain reaction the Terraform license change set off for many teams, often long after the technical work was already done.

When HashiCorp announced its move from the Mozilla Public License v2.0 (MPL 2.0) to the Business Source License (BSL) in August 2023, the reaction extended beyond ‘just noise’ pretty quickly. It exposed how deeply Terraform had been assumed to be “safe, open, and predictable” infrastructure glue. Overnight, teams who thought they were managing purely technical risk found themselves pulled into licensing discussions they were never set up to handle.

The question quickly shifted from what changed to what does this mean for how we run infrastructure going forward?

Understanding the Terraform BSL License and What Changed

Before August 2023, Terraform’s open source MPL 2.0 license allowed broad reuse, modification, and redistribution, including for commercial services. This model made Terraform an easy default for internal platforms, consultancies, and SaaS providers building IaC-powered offerings. It removed friction, and over time, that frictionless adoption became an assumption.

The Business Source License changes that calculus. Under the Terraform BSL license, use is still permitted for many internal scenarios, but explicitly restricted when Terraform is used to build competing commercial services. That distinction matters more than it first appears.

If you are:

• Operating an internal platform team offering IaC as a shared service.
• Running managed infrastructure for customers.
• Embedding Terraform into a commercial product.

You are no longer operating in a clearly open space.

The HashiCorp license change paired legal challenges with uncertainty. Legal and compliance teams dislike ambiguity, and infrastructure teams rarely want to be the ones explaining why a core automation tool might fall into a gray area six months from now.

This is the context in which the BSL vs open source discussion actually matters: not ideology, but operational predictability.

OpenTofu vs Terraform: Why an Open Baseline Matters

In response to the license change, the community did what it has done many times before: it forked. OpenTofu emerged as a continuation of the last MPL-licensed Terraform release, governed under the Linux Foundation with an explicit commitment to open, community-driven development.

From a practical perspective, OpenTofu started life as a drop-in replacement. Existing configurations, state files, providers, and modules continued to work. That was intentional.

The goal was continuity without legal ambiguity.

Now, you and your team might ask, what makes OpenTofu compelling aside from feature novelty? And the biggest factor is governance clarity. OpenTofu provides an open source IaC tool whose roadmap, licensing, and contribution model are not tied to a single vendor’s commercial strategy. For organizations designing or evolving IaC platforms today, that matters…a lot.

Terraform, meanwhile, remains a powerful and widely adopted tool, particularly for teams already invested in Terraform Cloud or enterprise workflows. But its direction is now explicitly commercial-first. That does not make it wrong, but it does mean it is no longer the neutral baseline it once was.

This distinction is subtle but important. OpenTofu increasingly represents the default open path, while Terraform becomes a contextual choice driven by existing investment rather than long-term openness.

Common Pitfalls When Evaluating Terraform Alternatives

One of the biggest mistakes teams make after the Terraform license change is treating the decision as a simple binary swap. Replace the binary, update a few pipelines, move on. That approach works briefly, and then fails in production.

Migrating from Terraform requires more than CLI compatibility:

• Provider versions need validation.
• Module registries need auditing.
• State backends and locking mechanisms must be reviewed.
• CI/CD pipelines often hardcode assumptions that surface only under load.

Another common misstep is assuming ecosystem maturity is static. Terraform benefits from years of accumulated modules and institutional knowledge. OpenTofu is closing that gap quickly, but teams still need to inventory dependencies rather than assume universal parity.

Finally, many organizations ignore hybrid reality. Running OpenTofu for new workloads while maintaining Terraform for legacy environments is often the most pragmatic approach. The risk comes not from using both tools, but from managing them inconsistently.

Infrastructure as Code Licensing Is Now a Platform Concern

The Terraform license change highlighted a broader shift: infrastructure as code licensing is no longer a background concern. It is part of your platform architecture.

Infrastructure teams now have to think about:

• How licensing choices affect downstream products and services.
• Whether tooling decisions introduce future renegotiation risk.
• How easily execution engines can be swapped if assumptions change again?

This is where open source IaC tools regain their appeal. Not because they are “better,” but because they reduce surprise.

How Harness IaCM Supports OpenTofu and Terraform Without Lock-In

Regardless of where you land in the OpenTofu vs Terraform discussion, the operational challenge remains the same: running infrastructure changes safely, consistently, and with governance across teams.

Harness Infrastructure as Code Management (IaCM) is designed to absorb this kind of tooling evolution. It supports both OpenTofu and Terraform while treating the execution engine as an implementation detail rather than a strategic constraint.

With Harness IaCM:

This approach allows teams to adopt OpenTofu where openness and governance matter most, while continuing to support Terraform where existing investment justifies it. Drift detection and policy enforcement apply uniformly, regardless of which tool is executing the plan.

Rather than forcing an immediate migration, Harness IaCM enables controlled evaluation and gradual transition, reducing the risk that licensing decisions fragment your platform.

Summary: Make Licensing a Design Decision, Not a Surprise

The Terraform license change was a reminder that infrastructure tooling choices have consequences beyond syntax and state files. The BSL vs open source distinction affects governance, risk tolerance, and long-term platform flexibility.

OpenTofu provides a clear open baseline for teams who want to avoid licensing ambiguity going forward. Terraform remains relevant, especially where commercial tooling is already embedded. The key is designing your platform so that this choice does not become a single point of failure.

Harness Infrastructure as Code Management helps teams do exactly that. By supporting both OpenTofu and Terraform with consistent workflows and guardrails, it allows organizations to adapt without disruption.

The question is no longer which tool you prefer. It is whether your infrastructure platform can handle change when the rules shift again.

Explore Harness IaCM and design your IaC workflows for flexibility, not assumptions.

Check out the Terraform to OpenTofu migration to bring this flexibility into play and take back control of your infrastructure.

Originally published at https://www.harness.io on March 31, 2026.

Terraform License Change: BSL vs Open Source Guide was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Author: Pritesh Kiri

In today’s always-on digital economy, a single slow page or unexpected crash during peak traffic can cost businesses thousands or even millions of dollars in lost revenue, damaged reputation, and frustrated customers. Imagine Black Friday shoppers abandoning carts because your e-commerce site buckles under load, or a SaaS platform going down during a major product launch. This is where load testing becomes non-negotiable.

Load testing simulates real-world user traffic to ensure your applications, websites, and APIs stay fast, stable, and scalable. It’s a cornerstone of performance testing that helps teams catch bottlenecks early, validate SLAs, and build resilient systems.

If you’re searching for a complete load testing guide, what is load testing, or how to perform load testing, you’re in the right place. This beginner-friendly introduction covers everything from the basics to best practices, with practical steps anyone can follow.

What Is Load Testing?

Load testing is a type of performance testing that evaluates how your system behaves under expected (and sometimes peak) user loads. It simulates concurrent users, requests, or transactions to measure key metrics such as Response times (average, p95, p99), Throughput (requests per second), Error rates, Resource utilization (CPU, memory, database connections), Latency and scalability.

Unlike unit or functional tests that check “does it work?”, load testing answers: “How does it perform when 1,000 (or 100,000) people use it at once?”

Done early and often, load testing reduces risk across the lifecycle. It confirms capacity assumptions, reveals infrastructure limits, and proves that recent changes haven’t slowed critical paths. The result is fewer production incidents and fewer late-night fire drills.

Key terminology to anchor your approach:

• Response time: End-to-end time to complete a request.
• Latency: The network delay portion of response time.
• Throughput: Requests or transactions per second.
• Concurrency: The number of simultaneous users or sessions.
• Virtual users: Emulated users that generate traffic.
• Think time: Pauses between actions to mimic real behavior.
• Error rate: Percentage of requests that fail.
• Saturation point: Load level where performance drops sharply.
• Service-level objective (SLO): A target like p95 response time under 500 ms.

Why Load Testing Matters?

Effective load testing quantifies capacity, validates autoscaling, and uncovers issues like thread pool starvation, database contention, cache thrash, and third-party limits. With data in hand, you can tune connection pools, garbage collection, caching tiers, and CDN strategies so the app stays fast when it counts.

Skipping load testing is like launching a rocket without wind-tunnel tests, risky and expensive. Here’s why it’s essential:

• Prevents costly downtime: Unplanned outages average $5,600-$14,000+ per minute for enterprises, with some large companies facing $1M+ per hour.
• Improves user experience and conversions: Even 100ms of added latency can reduce sales by 1% and one-second delays can drop conversions by 7% for businesses.
• Validates scalability and auto-scaling: Especially critical for cloud-native apps on Kubernetes or AWS.
• Saves money long-term: Catch issues in staging instead of production; reduce infrastructure over-provisioning.
• Boosts confidence for high-traffic events: Product launches, sales, seasonal peaks.

Investing in load testing upfront keeps teams focused on building, not firefighting. Many major outages (think major retailers or banking apps) trace back to untested load scenarios. Load testing helps you ship with confidence.

Types of Load Testing

Not all traffic patterns are the same, and your system shouldn’t be tested with a one-size-fits-all approach. Different load testing scenarios help you understand how your application behaves under various real-world conditions, from everyday usage to extreme, unpredictable events.

• Baseline testing — This scenario tests your system under normal, expected load conditions. It helps establish a performance benchmark so you can compare how the system behaves under higher stress levels later.
• Ramp-up / Steady-state testing — In this approach, the load is gradually increased until it reaches a peak and is then maintained for a period of time. This helps you observe how your system handles growth in traffic and whether it can sustain peak load consistently.
• Stress testing — In this type of testing you push a system beyond its limits to see what happens when it starts to fail. In simple words, you keep increasing users or traffic until the system can’t handle it anymore.
• Spike testing — Spike testing simulates sudden and extreme increases in traffic over a short period. It is useful for understanding how your system reacts to unexpected surges, such as flash sales or viral events.
• Soak / Endurance testing — This type of testing runs the system under a steady load for an extended duration. It helps uncover issues like memory leaks, resource exhaustion, or performance degradation over time.

How to Perform Load Testing?

1. Define objectives and scope — Start by clearly defining what success looks like for your system. Identify your SLAs, expected concurrent users, peak traffic events, and the most critical user journeys like login, checkout, or key API calls.
2. Identify test scenarios -Use real production data such as analytics and logs to design realistic test scenarios. Make sure to include both common user flows (happy paths) and edge cases that could potentially break the system.
3. Set up test environment- Create a test environment that closely mirrors production in terms of infrastructure, data volume, and network conditions.
4. Create scripts — Develop scripts that simulate real user behavior using load testing tools. Incorporate think times, random delays, and varied actions to mimic how actual users interact with your system.
5. Configure load profile — Define how the load will be applied, gradually ramp up users, maintain a steady load, and then ramp down. This helps you observe how the system behaves under increasing and sustained pressure.
6. Execute the test — Run your tests in a controlled, non-production environment first to avoid impacting real users. Monitor system performance in real-time to catch any immediate issues.
7. Analyze results — Dive into the results using logs, dashboards, and APM tools to identify performance bottlenecks. Focus on metrics like response time, error rates, and system throughput.
8. Iterate and report — Fix the issues identified during testing and re-run tests to validate improvements. Document your findings and share insights with stakeholders for better decision-making.
9. Integrate into CI/CD pipelines — Automate load testing by integrating it into your CI/CD pipelines. This ensures performance is continuously validated with every build or deployment.

Load testing isn’t just about throwing traffic at your system, it’s about understanding how your application behaves under real-world conditions and uncovering hidden bottlenecks before your users do.

Here’s a step-by-step guide to do load testing:

Load testing is an iterative process, not a one-time activity. The more consistently you test and refine, the more resilient and reliable your system becomes over time.

Role of AI in load testing

Moving into 2026 and beyond, AI is shifting load testing from a manual, scheduled chore into an intelligent, autonomous process. Instead of relying on static scripts, AI agents now ingest vast streams of real-world data including recent incident reports, deployment logs, and even design changes documented in wikis to generate context-sensitive testing scenarios. This ensures that performance suites are no longer generic; they are hyper-targeted to the specific risks introduced by the latest code commits or environmental shifts, allowing teams to catch bottlenecks before they ever reach production.

The relationship between testing and infrastructure has also become a two-way street. Beyond just identifying breaking points, AI-driven analysis of load test results now provides proactive recommendations for deployment configurations. By correlating performance metrics with resource allocation, these systems can suggest the “golden path” for auto-scaling thresholds, memory limits, and container orchestration. This creates a continuous feedback loop where the load test doesn’t just pass or fail it actively optimizes the production environment for peak efficiency.

Load testing for AI Agents

In the new landscape of AI agents proliferation, load testing is no longer just about hitting a server with traffic it’s about managing the explosion of agentic orchestration. With organizations deploying hundreds of specialized AI agents, a single user request can trigger a “storm” of inter-agent communication, where one agent’s output becomes another’s prompt. Traditional load tests fail here because they can’t predict these emergent behaviors or the cascading latency that occurs when multiple agents reason, call external APIs, and update shared memory simultaneously. Testing must now account for “prompt bloat” and context contamination, where excessive or conflicting data fed into these agent chains causes performance to degrade or costs to spike unexpectedly.

To survive this complexity, performance engineering in 2026 has shifted toward dynamic environment testing and automated “prompt volume” estimation. Load testers are now using tools like AI Gateways to monitor and rate-limit the massive volume of prompts moving between agents, ensuring that “reasoning loops” don’t turn into infinite, resource-draining cycles. By simulating thousands of parallel agent trajectories in virtual sandboxes, teams can identify the specific point where a flurry of prompts causes an LLM’s context window to “clash,” leading to the 30–40% drops in accuracy often seen under heavy organizational load.

Popular Load Testing Tools

• Open-source/free: Apache JMeter, k6 (Grafana), Gatling, Locust (Python-based).
• Enterprise: Harness, LoadRunner, NeoLoad, BlazeMeter, LoadNinja.

When selecting a load testing tool, teams often start with open-source options for flexibility and cost, then move to enterprise or cloud-managed solutions for scale, collaboration, and integrations.

Here are some of the most popular and widely used load testing tools in 2026:

Choose based on scripting language, scale needs, and integration. For teams already invested in Locust or seeking to combine load testing with chaos engineering in CI/CD pipelines, platforms like Harness Resilience Testing provide seamless native support to elevate your testing strategy.

Load Testing Best Practices in 2026

As systems grow more distributed and user expectations continue to rise, load testing in 2026 is no longer optional, it’s a continuous discipline. Following the right best practices ensures that your application is not just fast, but also resilient and reliable under real-world conditions.

Adopting these best practices helps you move beyond basic performance testing toward building truly resilient systems. In 2026, it’s not just about handling traffic, it’s about thriving under pressure.

Conclusion

Load testing turns unknowns into knowns and panic into process. It isn’t a “nice-to-have”, it’s essential for delivering fast, reliable digital experiences that customers (and your bottom line) demand.

By following this guide, you’ll identify issues early, optimize performance, and build systems that scale confidently.

Ship faster, break less, and stay resilient.

Originally published at https://www.harness.io on March 31, 2026.

Load Testing: An Essential Guide for 2026 was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Authors: Abhay Ganvir

You’re tagging Docker images with build numbers.

-Build #47 is your latest production release on main. A developer pushes a hotfix to release-v2.1, that run becomes build #48.

-Another merges to develop, build #49. A week later someone asks: “What build number are we on for production?” You check the registry.

-You see #47, #52, #58, #61 on main. The numbers in between? Scattered across feature branches that may never ship. Your build numbers have stopped telling a useful story.

That’s the reality when your CI platform uses a single global counter. Every run, on every branch, increments the same number. For teams using GitFlow, trunk-based development, or any branching strategy, that means gaps, confusion, and versioning that doesn’t match how you actually ship.

TL;DR: Harness CI now supports branch-scoped build sequence IDs via <+pipeline.branchSeqId>.

Each branch gets its own counter. No gaps. No confusion.

Why Global Build Counters Break Down

Most CI platforms give you one incrementing counter per pipeline. Push to main, push to develop, push to a feature branch, same counter. So you get:

• Gaps in the sequence for any given branch (e.g. main might have #1, #4, #7).
• No clear answer to “what’s the latest build on main?”
• Semantic versioning and artifact naming that don’t line up with branch reality.
• Registries and artifact stores full of numbers that don’t map to how you release.

This is now built directly into Harness CI as a first-class capability.

What It Feels Like in Practice

Add <+pipeline.branchSeqId> where you need the number-for example, in a Docker build-and-push step:

Trigger runs on main, then on develop, then on a feature branch. Each branch gets its own sequence: main might be 1, 2, 3… develop 1, 2, 3… feature/x 1, 2. Your tags become meaningful: main-42, develop-15, feature-auth-3. No more guessing which number belongs to which branch.

• Per-branch counters — One sequence per pipeline + repo + branch, stored and incremented atomically.
• Pipeline expression — <+pipeline.branchSeqId>. Check out Harness variables documentation.
• REST API — List sequences for a pipeline, get the current value for a branch/repo, reset a branch counter, or set it to a specific value (for example, after a major release or when migrating from another CI).
• Consistent identification — Repo URLs and branch names are normalized (for example, refs/heads/main → main, different URL forms to one canonical host/owner/repo). Same logical branch and repo always share the same counter.
• Cleanup — When a pipeline is deleted, its branch-sequence data is removed so you don’t leave orphaned counters.

What You Get

Webhook triggers (push, PR, branch, release) and manual runs (with branch from codebase config) are supported. For tag-only or other runs without branch context, the expression returns null so you can handle that in your pipeline if needed.

How It Works Under the Hood

Branch and repo are taken from the trigger payload when possible (webhooks) or from the pipeline’s codebase configuration (for example, manual runs). We normalize them so that the same repo and branch always map to the same logical key: branch names get refs/heads/ (or similar) stripped, and repo URLs are reduced to a canonical form (for example, github.com/org/repo). That way, whether you use https://..., git@…, or different casing, you get one counter per branch.

The counter is stored and updated with an atomic increment. Parallel runs on the same branch still get distinct, sequential numbers. The value is attached to the run’s metadata and exposed through the pipeline execution context so <+pipeline.branchSeqId> resolves correctly at runtime.

• Docker image tagging: use <+pipeline.branchSeqId> and optionally <+codebase.branch>-<+pipeline.branchSeqId> for clear, branch-specific tags.
• Helm chart versioning: e.g. — version 1.0.<+pipeline.branchSeqId> --app-version <+codebase.commitSha> so the chart version tracks the build number and the app version tracks the commit.
• Release notes or deployment labels: for example, “Release Build #<+pipeline.branchSeqId>" so production and staging each have a clear, branch-local build number.

Putting It to Work

For teams that need control or migration support, branch sequences are also manageable via API:

# List all branch sequences for a pipelineGET /pipelines/{pipelineIdentifier}/branch-sequences # Reset counter for a specific branchDELETE /pipelines/{pipelineIdentifier}/branch-sequences/branch?branch=main&repoUrl=github.com/org/repo # Set counter to a specific value (e.g., after major release)PUT /pipelines/{pipelineIdentifier}/branch-sequences/set?branch=main&repoUrl=github.com/org/repo&sequenceId=100

All of this is gated by the same feature flag so only accounts that have adopted the feature use the APIs.

1. Enable the feature — Turn on CI_ENABLE_BRANCH_SEQUENCE_ID (Account Settings → Feature Flags, or Reach out to the Harness team).
2. Use the expression — Add <+pipeline.branchSeqId> in steps, tags, or env vars.
3. Verify — Run the pipeline on two or three branches and confirm each branch has its own 1, 2, 3…

Try It (With Smart Guardrails)

If branch context isn’t available, the expression returns null. Design your pipeline to handle that (for example, skip tagging or use a fallback) for tag builds or edge cases.

Feature availability may vary by plan. Check with your Harness account or Harness Developer Hub for your setup.

How Other CI Platforms Handle This (Spoiler: Most Don’t)

This isn’t just a Harness problem we solved-it’s an industry gap. Here’s how major CI platforms compare:

Most platforms treat build numbers as an afterthought. Harness CI treats them as a first-class versioning primitive. For teams migrating from Jenkins or Azure DevOps, the model will feel familiar. For teams on GitHub Actions, GitLab, or CircleCI, this fills a gap that previously required external services or custom scripts

What’s Coming

This is the first release of branch-scoped sequence IDs. The foundations are in place: per-branch counters, expression support, and APIs. We’re not done.

We’re listening. If you use this feature and hit rough edges-or have ideas for tag-scoped sequences, dashboard visibility, or trigger conditions-we want to hear about it. Share feedback .

Originally published at https://www.harness.io on March 31, 2026.

Branch-Scoped Sequence IDs in Harness CI was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Author: Dewan Ahmed, Shreyas Nagaraj

This is part 1 of a five-part series on building production-grade AI engineering systems.

Across this series, we will cover:

1. How to make your repository agent-native
2. How to prevent context decay in long AI sessions
3. How to orchestrate tools, subagents, and external systems
4. How to survive the multi-model reality with gateway layers
5. How to measure and enforce quality with AI evals

Most teams experimenting with AI coding agents focus on prompts.

That is the wrong starting point.

Before you optimize how an agent thinks, you must standardize what it sees.

AI agents do not primarily fail because of reasoning limits. They fail because of environmental ambiguity. They are dropped into repositories designed exclusively for humans and expected to infer structure, conventions, workflows, and constraints from scattered documentation.

If AI agents are contributors, then the repository itself must become agent-native.

The foundational step is introducing a standardized instruction layer that every agent can read.

That layer is AGENTS.md.

The Real Problem: Context Silos

Every coding agent needs instructions. Where those instructions live depends on the tool.

One IDE reads from a hidden rules directory.
Another expects a specific markdown file.
Another uses proprietary configuration.

This fragmentation creates three systemic problems.

1. Tool-dependent prompt locations

Instructions are locked into IDE-specific paths. Change tools and you lose institutional knowledge.

2. Tribal knowledge never gets committed

When a developer discovers the right way to guide an agent through a complex module, that guidance often lives in chat history. It never reaches version control. It never becomes part of the repository’s operational contract.

3. Inconsistent agent behavior

Two engineers working on the same codebase but using different agents receive different outputs because the instruction surfaces are different.

The repository stops being the single source of truth.

For human collaboration, we solved this decades ago with READMEs, contribution guides, and ownership files. For AI collaboration, we are only beginning to standardize.

What AGENTS.md Is

AGENTS.md is a simple, open, tool-agnostic format for providing coding agents with project-specific instructions. It is now part of the broader open agentic ecosystem under the Agentic AI Foundation, with broad industry adoption.

It is not a replacement for README.md. It is a complement.

Design principle:

• README.md is for humans.
• AGENTS.md is for agents.

Humans need quick starts, architecture summaries, and contribution policies.

Agents need deterministic build commands, exact test execution steps, linter requirements, directory boundaries, prohibited patterns, and explicit assumptions.

Separating these concerns provides:

Several major open source repositories have already adopted AGENTS.md. The pattern is spreading because it addresses a real structural gap.

Recent evaluations have also shown that explicit repository-level agent instructions outperform loosely defined “skills” systems in practical coding scenarios. The implication is clear. Context must be explicit, not implied.

A Real Example: OpenAI’s Agents SDK

A practical example of this pattern can be seen in the OpenAI Agents Python SDK repository.

The project contains a root-level AGENTS.md file that defines operational instructions for contributors and AI agents working on the codebase. You can view the full file here: Github.

Instead of leaving workflows implicit, the repository encodes them directly into agent-readable instructions. For example, the file requires contributors to run verification checks before completing changes:

Run `$code-change-verification` before marking work complete.

It also explicitly scopes where those rules apply, such as changes to core source code, tests, examples, or documentation within the repository.

Rather than expecting an agent to infer these processes from scattered documentation, the project defines them as explicit instructions inside the repository itself.

This is the core idea behind AGENTS.md.

Operational guidance that would normally live in prompts, chat history, or internal knowledge becomes version-controlled infrastructure.

Designing an Effective Root AGENTS.md

A root AGENTS.md should be concise. Under 300 lines is a good constraint. It should be structured, imperative, and operational.

A practical structure includes four required sections.

1. Project Overview

This section establishes the mental model.

Include:

• Project purpose and high-level architecture
• Directory structure and key components
• Technology stack and critical dependencies

Agents are pattern matchers. The clearer the structural map, the fewer incorrect assumptions they make.

2. Build, Test, and Push Instructions

This section must be precise.

Include:

Avoid vague language. Replace “run tests” with explicit commands.

Agents execute what they are told. Precision reduces drift.

3. Development Workflow

This section defines conventions.

Rather than bloating AGENTS.md, reference a separate coding standards document for:

The root file should stay focused while linking to deeper guidance.

4. Common Pitfalls and Prohibited Patterns

This is where most teams underinvest.

Document:

Agents tend to repeat statistically common patterns. Your codebase may intentionally diverge from those patterns. This section is where you enforce that divergence.

Think of this as defensive programming for AI collaboration.

Hierarchical AGENTS.md: Scaling Context Correctly

Large repositories require scoped context.

A single root file cannot encode all module-specific constraints without becoming noisy. The solution is hierarchical AGENTS.md files.

Structure example:

root/ AGENTS.md module-a/ AGENTS.md module-b/ AGENTS.md sub-feature/ AGENTS.md

Agents automatically read nested AGENTS.md files when operating inside those directories. Context scales from general to specific.

Root defines global conventions.
Module-level files define local invariants.
Feature-level files encode edge-case constraints.

This reduces irrelevant context and increases precision.

It also mirrors how humans reason about codebases.

Compatibility Across Tools

A standard file location matters.

Some agents natively read AGENTS.md. Others require simple compatibility mechanisms such as symlinks that mirror AGENTS.md into tool-specific filenames.

The key idea is a single source of truth.

Do not maintain multiple divergent instruction files. Normalize on AGENTS.md and bridge outward if needed.

The goal is repository-level portability. Change tools without losing institutional knowledge.

Best Practices for Agent Instructions

To make AGENTS.md effective, follow these constraints.

Write imperatively.
Use direct commands. Avoid narrative descriptions.

Avoid redundancy.
Do not duplicate README content. Reference it.

Keep it operational.
Focus on what the agent must do, not why the project exists.

Update it as the code evolves.
If the build process changes, AGENTS.md must change.

Treat violations as signal.
If agents consistently ignore documented rules, either the instruction is unclear or the file is too long and context is being truncated. Reset sessions and re-anchor.

AGENTS.md is not static documentation. It is part of the execution surface.

Ownership and Governance

If agents are contributors, then their instruction layer requires ownership.

Each module-level AGENTS.md should be maintained by the same engineers responsible for that module. Changes to these files should follow the same review rigor as code changes.

Instruction drift is as dangerous as code drift.

Version-controlled agent guidance becomes part of your engineering contract.

Why Teams Are Adopting AGENTS.md

Repositories across the industry have begun implementing AGENTS.md as a first-class artifact. Large infrastructure projects, developer tools, SDKs, and platform teams are standardizing on this pattern.

The motivation is consistent:

AGENTS.md transforms prompt engineering from a personal habit into a shared, reviewable, versioned discipline.

Vercel published evaluation results showing that repository-level AGENTS.md context outperformed tool-specific skills in agent benchmarks.

Why This Matters Now

AI agents are rapidly becoming embedded in daily development workflows.

Without a standardized instruction layer:

The repository must become the stable contract between humans and machines.

AGENTS.md is the first structural step toward that contract.

It shifts agent collaboration from ad hoc prompting to engineered context.

Foundation Before Optimization

In the next post, we will examine a different failure mode.

Even with a perfectly structured AGENTS.md, long AI sessions degrade. Context accumulates. Signal dilutes. Hallucinations increase. Performance drops as token counts rise.

This phenomenon is often invisible until it causes subtle architectural damage.

Part 2 will focus on defeating context rot and enforcing session discipline using structured planning, checkpoints, and meta-prompting.

Before you scale orchestration.
Before you add subagents.
Before you optimize cost across multiple model providers.

You must first stabilize the environment.

An agent-native repository is the foundation.

Everything else builds on top of it.

Originally published at https://www.harness.io on March 19, 2026.

The Agent-Native Repo: Why AGENTS.MD is the New Standard was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Author: Sunil Gattupalle, Rohan Gupta, Shubham Jindal

—

Key Takeaways:

The Harness MCP server is an MCP-compatible interface that lets AI agents discover, query, and act on Harness resources across CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Resilience Testing, Internal Developer Portal, and more.

• The Harness MCP server v2 reduces tools from 130+ to 11.
• The redesign cuts estimated tool-definition context cost from about 26% to 1.6% of a 200K-token window.
• A registry-based dispatch model supports 125+ resource types without expanding the tool vocabulary.
• The architecture is designed for Cursor, Claude Code, and other MCP-compatible clients.
• Built-in safety controls include confirmation for writes, fail-closed deletes, and read-only mode.

—

The first wave of MCP servers followed a natural pattern: take every API endpoint, wrap it in a tool definition, and expose it to the LLM. It was fast to build, easy to reason about, and it was exactly how we built the first Harness MCP server. That server taught us a lot: solid Go codebase, well-crafted tools, broad platform coverage across 30 toolsets. It also taught us where the one-tool-per-endpoint model hits a wall.

For platforms the size of Harness, spanning the entire SDLC, the pattern doesn’t scale. When you expose one tool per API endpoint, you’re asking the LLM to be a routing layer, forcing it to do something a switch statement does better. Every tool definition consumes context that could be spent on reasoning. At ~175 tools, that’s ~26% of the LLM’s context window before the developer even types a prompt.

So we iterated. The Harness MCP v2 redesign does the same work with 11 tools at ~1.6% context consumption. The answer isn’t fewer features, it’s a different architecture: a registry-based dispatch model where the LLM reasons about what to do, and the server handles how to do it.

What We Learned: Tool Sprawl and Agent Performance

When an MCP client connects to a server, it loads every tool definition into the LLM’s context window. Every name, description, parameter schema, and annotation. For the first Harness server at ~130+ active tools, here’s what that costs:

v1 vs v2 comparison

That’s the core insight: the first server uses ~26% of context on tool definitions before any work begins. The v2 uses ~1.6%.

This isn’t a theoretical concern. Research on LLM behavior in large context windows, including Liu et al.’s “Lost in the Middle” findings, shows that models struggle to use information placed deep within long contexts. As Ryan Spletzer recently wrote, dead context doesn’t sit inertly: “It dilutes the signal. The model’s attention is spread across everything in the window, so the more irrelevant context you pack in, the less weight the relevant context carries.”

Anthropic’s own engineering team has documented this trade-off: direct tool calls consume context for each definition and result, and agents scale better when the tool surface area is deliberately constrained.

The problem compounds in real-world developer environments. If you’re running Cursor or Claude Code with a Playwright MCP, a GitHub MCP, and the Harness MCP, those tool definitions stack. EclipseSource’s analysis shows that a standard set of MCP servers can eat 20% of the context window before you even type a prompt. The recommendation: stay below 40% total context utilization. Any MCP server with 100+ tools, ours included, would consume more than half that budget on its own.

How We Stack Up: Context Efficiency Across the MCP Ecosystem

The context window tax isn’t unique to Harness: it’s an industry-wide problem. Here’s how the v2 server compares to popular MCP servers in the wild:

Comparison of popular MCP servers

‍Lunar.dev research: “5 MCP servers, 30 tools each → 150 total tools injected. Average tool description: 200–500 tokens. Total overhead: 30,000–60,000 tokens. Just in tool metadata.” MCP server v2 at ~3,150 tokens would represent just 5–10% of a typical multi-server setup’s overhead.

Real-world Claude Code user: A developer on Reddit r/ClaudeCode with Playwright, Context7, Azure, Postgres, Zen, and Firecrawl MCPs reported 83.3K tokens (41.6% of 200K) consumed by MCP tools immediately after /clear. That’s before a single prompt.

Anthropic’s code execution findings: Anthropic’s engineering team reported that a workflow consuming 150,000 tokens was reduced to ~2,000 tokens (a 98.7% reduction) by switching from direct tool calls to code-based tool invocation. The principle is clear: fewer, smarter tools beat more, narrower ones.

MCPAgentBench: An academic benchmark found that “nearly all evaluated models exhibit a decline of over 10 points in task efficiency when tool selection complexity increases.” Models overwhelmed with tools prioritize task resolution over execution efficiency. They get the job done, but waste tokens doing it.

IDE Tool Limits and Practical Headroom

Cursor enforces an 80-tool cap, OpenAI limits to 128 tools, and Claude supports up to ~120. The v2 server’s 11 tools leave massive headroom to run Harness alongside other MCP servers without hitting these limits.

Consider a concrete example: a developer running Cursor with Playwright (21 tools), GitHub MCP (~40 tools), and the old Harness MCP (~175 tools) would hit ~236 tools, well past Cursor’s 80-tool cap. With v2 Harness (11 tools), the same stack is 72 tools, comfortably under the limit.

With Claude Code, the same old stack would burn ~76,400 tokens (~38%) on tool definitions alone. With v2, it drops to ~27,550 tokens (~14%), freeing ~48,850 tokens for actual reasoning and conversation.

The CLI vs MCP Debate and Why It’s the Wrong Question

The MCP ecosystem is in the middle of a reckoning. Scalekit ran 75 benchmark runs comparing CLI and MCP for identical GitHub tasks on Claude Sonnet 4, and CLI won on every efficiency metric: 10–32x cheaper, 100% reliable vs MCP’s 72%. For a simple “what language is this repo?” query, CLI used 1,365 tokens. MCP used 44,026 — almost entirely from schema injection of 43 tool definitions the agent never touched.

The Playwright team shipped the same verdict in hardware. Their new CLI tool saves browser state to disk instead of flooding context. In BetterStack’s benchmarks, CLI used ~150 tokens per interaction vs MCP’s ~7,400+ of accumulated page state. CircleCI found CLI completed browser tasks with 33% better token efficiency and a 77 vs 60 task completion score.

The CLI camp’s argument is real: schema bloat kills performance. But their diagnosis points at the wrong layer. The problem isn’t MCP. It’s naive MCP server design.

What CLI Gets Right

CLI wins when the agent already knows the tool. gh, kubectl, terraform: these have extensive training data. The agent composes commands from memory, pays zero schema overhead, and gets terse, predictable output. Scalekit found that adding an 800-token “skills document” to CLI reduced tool calls and latency by a third.

CLI also wins on composition. Piping grep into jq into xargs chains operations in a single tool call. An MCP agent doing the same work makes N round-trips through the LLM, each one burning context.

What CLI Can’t Do

But CLI’s advantages dissolve the moment you cross three boundaries:

Discovery

CLI works when the agent knows the command. For a platform like Harness, with 122+ resource types across CI/CD, GitOps, FinOps, security, chaos, and IDP, the agent can’t know the API surface from training data alone. MCP’s harness_describe tool lets the agent discover capabilities at runtime. CLI would require the agent to guess curl commands against undocumented APIs.

Authorization

As Scalekit themselves concluded: “The question isn’t CLI or MCP. It’s who is your agent acting for?” CLI auth gives the agent ambient credentials: your token. For multi-tenant, multi-user environments (which is where Harness operates), MCP provides per-user OAuth, explicit tool boundaries, and structured audit trails.

Safety

CLI agents can run arbitrary shell commands. An MCP server constrains the agent to declared tools with typed inputs. The v2 server’s elicitation-based confirmation flows, fail-closed deletes, and read-only mode are protocol-level safety guarantees that CLI can’t replicate.

The v2 Server Is Our Answer to This Debate

The CLI vs MCP debate is really about schema bloat and naive tool design. The v2 Harness MCP server eliminates the arguments against MCP without losing the arguments for it:

Schema bloat? 11 tools at ~3,150 tokens. That’s less than a single CLI help output for a complex tool. Cursor’s 80-tool cap? We use 11. The 44,026-token GitHub MCP problem? We’re 14x leaner.

Round-trip overhead? The registry-based dispatch means the agent makes one tool call to harness_diagnose and gets back a complete execution analysis — pipeline structure, stage/step breakdown, timing, logs, and root cause. A CLI agent would need to chain 4–5 API calls to assemble the same picture.

Discovery? harness_describe is a zero-API-call local schema lookup. The agent discovers 125+ resource types without a single network request. CLI would require a man page the agent has never seen.

Composition? Skills + prompt templates encode multi-step workflows (build-deploy-app, debug-pipeline-failure) as server-side orchestration. The agent reasons about what to do; the server handles how to chain it. Same efficiency as a CLI pipe, with protocol-level safety.

The real lesson from the benchmarks: MCP servers with 43+ tools and no architecture for context efficiency will lose to CLI on cost metrics. But a well-designed MCP server with 11 tools, a registry, and a skills layer outperforms both naive MCP and naive CLI — and provides authorization, safety, and discoverability that CLI architecturally cannot.

The Redesign: 11 Tools, 125+ Resource Types, 1 Registry

We stopped designing for API parity and started designing for agent usability.

The v2 server is built around a registry-based dispatch model. Instead of one tool per endpoint, we expose 11 intentionally generic verbs. The intelligence lives in the registry: a declarative data structure that maps resource types to API operations.

The 11 Tools

11 tools in the MCP v2 server

When an agent calls harness_list(resource_type="pipeline"), the server looks up pipeline in the registry, resolves the API path, injects scope parameters (account, org, project), makes the HTTP call, extracts the relevant response data, and appends a deep link to the Harness UI. The agent never needs to know the underlying API structure.

How the Registry Works

Each registry entry is a declarative ResourceDefinition:

{

resourceType: "pipeline",

displayName: "Pipeline",

toolset: "pipelines",

scope: "project",

identifierFields: ["pipeline_id"],

operations: {

list: {

method: "GET",

path: "/pipeline/api/pipelines/list",

queryParams: { search_term, page, size },

responseExtractor: (raw) => raw.content

},

get: {

method: "GET",

path: "/pipeline/api/pipelines/{pipeline_id}",

responseExtractor: (raw) => raw.data

}

}

}

‍

Adding support for a new Harness module requires adding one declarative object to the registry. No new tool definitions. No changes to MCP tool schemas. The LLM’s tool vocabulary stays constant as the platform grows.

Today, the registry covers 125+ resource types across 30 toolsets, spanning the full Harness platform:

• DevOps: Pipelines, Executions, Services, Environments, Infrastructure, Templates, Connectors, Secrets, Delegates
• Code: Repositories, Branches, Commits, Pull Requests, Code Reviews
• GitOps: Agents, Applications, Clusters, ApplicationSets, Repositories
• Security: Security Issues, Exemptions, SBOMs, Compliance, Supply Chain, OPA Policies
• Cloud Cost: Perspectives, Budgets, Recommendations, Anomalies, Commitments
• Chaos: Experiments, Probes, Templates, Infrastructure, Load Tests
• Feature Flags: Workspaces, Environments, Flags
• IDP: Entities, Scorecards, Workflows, Tech Docs
• SEI: DORA Metrics, Team Analytics, AI Usage, Business Alignment
• Platform: Organizations, Projects, Users, Roles, Permissions, Settings, Audit Trail

Optimized for Cursor, Claude Code, and Real Developer Workflows

The architecture wasn’t designed in a vacuum. We built it specifically for the environments developers actually use.

Cursor and Windsurf: Stdio-First, Toolset Filtering

Cursor and Windsurf connect via stdio transport — the server runs as a local process alongside the IDE. With 11 tools instead of 130+, the Cursor agent has a minimal, clear menu. It doesn’t waste reasoning cycles on tool selection or get confused by 40 CCM-specific tools when the developer is debugging a pipeline failure.

For teams that only use specific Harness modules, HARNESS_TOOLSETS lets you filter at startup:

{

"mcpServers": {

"harness": {

"command": "npx",

"args": ["-y", "harness-mcp-v2@latest"],

"env": {

"HARNESS_API_KEY": "pat.xxx.yyy.zzz",

"HARNESS_TOOLSETS": "pipelines,services,connectors"

}

}

}

}

‍

The agent only sees resource types from the enabled toolsets. The rest don’t exist as far as the LLM is concerned.

Claude Code: Prompt Templates and Multi-Project Discovery

Claude Code excels at multi-step workflows. We leaned into that with 26 prompt templates across four categories:

• DevOps (12): build-deploy-app, debug-pipeline-failure, create-pipeline, onboard-service, dora-metrics-review, and more
• FinOps (5): optimize-costs, cloud-cost-breakdown, commitment-utilization-review, cost-anomaly-investigation, rightsizing-recommendations
• DevSecOps (6): security-review, vulnerability-triage, sbom-compliance-check, supply-chain-audit, security-exemption-review, access-control-audit
• Harness Code (3): code-review, pr-summary, branch-cleanup

Each prompt template encodes a multi-step workflow the agent can execute. debug-pipeline-failure doesn’t just fetch an execution — it calls harness_diagnose, follows chained failures, and produces a root cause analysis with actionable fixes.

The v2 server also supports multi-project workflows without hardcoded environment variables. An agent can dynamically discover the account structure, then scope subsequent calls with org_id and project_id parameters. No configuration changes needed.

URL Context Awareness

Every tool accepts an optional url parameter. Paste a Harness UI URL, a pipeline page, an execution log, a dashboard, and the server automatically extracts the account, org, project, and resource identifiers. The agent gets context without the developer having to specify it manually.

Harness Skills: From MCP Tools to Guided Workflows

Reducing tool count solves the context efficiency problem. But developers don’t just need fewer tools — they need tools that know how to chain together into real workflows. That’s where Harness Skills come in.

The v2 server ships with a companion skills layer (github.com/thisrohangupta/harness-skills) that turns raw MCP tool access into guided, multi-step workflows. Skills are IDE-native agent instructions that teach the AI how to use the MCP server effectively — without the developer having to explain Harness concepts or orchestration patterns.

How Skills Work

Skills operate at three levels:

Level 1: Shared Agent Instructions

Every IDE gets a base instruction file, loaded automatically when the agent starts:

• CLAUDE.md for Claude Code (auto-loaded)
• AGENTS.md for OpenAI Codex / generic agents
• .cursor/rules/harness.mdc for Cursor (auto-loaded as project rule)
• .github/copilot-instructions.md for VS Code GitHub Copilot

These files teach the agent: what the 11 tools do, how Harness scoping works (account → org → project), dependency ordering (always verify referenced resources exist before creating dependents), and how to extract context from Harness UI URLs.

Level 2: Prompt Templates (Server-Side)

The 26 MCP prompt templates registered directly in the server. Any MCP client can invoke them. They encode multi-step workflows with phase gates, e.g., build-deploy-app structures a 4-phase workflow (clone → scan → CI pipeline → deploy) with explicit “do not proceed until this step is done” checkpoints.

Level 3: Individual Skills (Slash Commands)

Specialized SKILL.md files that function as slash commands in the IDE. Each skill includes YAML frontmatter (trigger phrases, metadata), phased instructions, worked examples, performance notes, and troubleshooting steps.

• Pipeline & Execution: /create-pipeline, /run-pipeline, /debug-pipeline, /create-trigger, /create-template, /migrate-pipeline
• Infrastructure: /create-service, /create-environment, /create-infrastructure, /create-connector, /create-secret
• Access Control: /manage-users, /manage-roles
• Specialized: /analyze-costs, /audit-report, /chaos-experiment, /create-policy

The Interaction Pattern

Without skills, a developer says “deploy my Node.js app” and the agent has to figure out the right Harness concepts, the correct ordering, and the proper API calls from scratch. With skills, the flow is:

• IDE auto-loads shared instructions (tool reference, scoping rules, dependency ordering)
• Agent matches intent to a skill via trigger phrases in skill descriptions
• Skill provides ordered, phase-gated execution steps (what to check, what to ask, what to generate)
• MCP server executes the actual harness_list / harness_create / harness_execute calls

Performance Benefits

The skills layer delivers three measurable improvements:

Fewer Round-Trips

Without skills, the agent typically needs 3–5 exploratory tool calls to understand Harness’s resource model before starting real work. Skills encode this knowledge upfront — the agent knows to check for existing connectors before creating a pipeline, to verify environments exist before deploying, and to use harness_describe for schema discovery instead of trial-and-error.

Correct Ordering on First Attempt

Harness resources have strict dependency chains (connector → secret → service → environment → infrastructure → pipeline → trigger). Skills encode the 7-step “Deploy New Service” and 8-step “New Project Onboarding” workflows as ordered sequences. The agent doesn’t discover dependencies through failures, it follows the prescribed order.

Reduced Token Waste

Each failed API call and retry burns tokens. Skills eliminate the most common failure modes (wrong scope, missing dependencies, incorrect parameter formats) by teaching the agent the patterns before execution. The combination of 11 tools (minimal context overhead) plus skills (minimal wasted calls) means more of the context window is available for the developer’s actual task.

IDE-Specific Integration

The first Harness MCP server (harness/mcp-server) pioneered the IDE-native pattern with a review-mcp-tool command that works across Cursor, Claude Code, and Windsurf via symlinked definitions:

• .claude/commands/ → Claude Code slash commands
• .cursor/commands/ → Cursor Agent commands
• .windsurf/workflows/ → Windsurf workflows

One canonical definition in .harness/commands/, symlinked to all three. Update once, propagate everywhere.

The v2 skills layer extends this pattern from developer-tool commands to full DevOps workflows, the same “define once, deploy to every IDE” architecture, applied to pipeline creation, deployment debugging, cost analysis, and security review.

Operational Safety: Designed for Production

MCP servers that can create, update, and delete resources need safety guardrails. We built them in from the start.

Human-in-the-loop confirmation: All write operations use MCP elicitation to request explicit user confirmation before executing. The agent presents what it intends to do; the developer approves or rejects.

Fail-closed destructive operations: harness_delete is blocked entirely if the MCP client doesn’t support elicitation. No silent deletions.

Read-only mode: Set HARNESS_READ_ONLY=true for shared environments, demos, or when you want agents to observe but not act.

Secrets safety: The secret resource type exposes metadata (name, type, org, project) but never the secret value itself.

Rate limiting and retries: Configurable rate limits (default: 10 req/s), automatic retries with backoff for transient failures, and bounded pagination to prevent runaway list operations.

Deployment: Local to Team-Scale

The v2 server supports two transports:

• Stdio (default): Direct integration with Claude Desktop, Cursor, Windsurf, Gemini CLI. Zero network configuration.
• Streamable HTTP: Session-based remote deployment. Kubernetes manifests included. Sessions reaped after 30 minutes. CORS restricted. Rate limited to 60 req/min per IP.

For team deployments, the HTTP transport is compatible with MCP gateways like Portkey, LiteLLM, and Envoy-based proxies, enabling shared control planes with centralized auth, observability, and policy enforcement.

# Local (Cursor, Claude Code)

npx harness-mcp-v2@latest

# Remote (team deployment)

npx harness-mcp-v2@latest http --port 3000

# Docker

docker run -e HARNESS_API_KEY=pat.xxx.yyy.zzz harness-mcp-v2

Why This Architecture Matters

The shift from 130+ tools to 11 isn’t about simplification for its own sake. It’s about recognizing that the best MCP servers are capability-oriented agent interfaces, not API mirrors.

Building the first Harness MCP server taught us the same lesson the broader ecosystem is learning: when you expose one tool per API endpoint, you’re asking the LLM to be a routing layer. You’re consuming context on definitions that could be used for reasoning. And you’re fighting against the LLM’s actual strengths, reasoning, planning, and multi-step problem solving, by forcing it to do something a switch statement does better. That first server made the cost concrete. The v2 is our answer.

The registry pattern inverts this. The tool vocabulary is stable: 11 verbs today, 11 verbs when Harness ships 50 more resource types. The registry is extensible. The skills layer is composable. The LLM reasons about what to do, and the server handles how to do it. That’s not just an efficiency win — it’s the correct division of labor between an LLM and a server.

This is the pattern we think more MCP servers should adopt, especially platforms with broad API surfaces. The MCP specification itself is built on the idea that servers expose capabilities, not endpoints. We took that literally.

Real Life Use Cases

The efficiency gains from the v2 architecture translate directly into concrete, time-saving use cases for developers operating within their IDEs. The combination of a minimal tool surface (11 tools), deep resource knowledge (125+ resource types), and pre-encoded workflows (Harness Skills) allows the agent to handle complex DevOps tasks with minimal guidance.

See it in action:

Some other use cases:

Debug a Failed CI Pipeline: Get root cause and logs for a pipeline run.

Onboard New Service: Create a Service, Environment, Infrastructure, and initial Connector.

Review Cloud Cost Anomaly: Investigate a sudden spike in cloud spend.

Check Compliance Status: Verify a service’s SBOM compliance against OPA policies.

Deploy App to Prod: Execute a canary deployment pipeline.

Get Started

npx harness-mcp-v2@latest

Configure with your Harness PAT (account ID is auto-extracted):

HARNESS_API_KEY=pat.<accountId>.<tokenId>.<secret>

Full source: github.com/thisrohangupta/harness-mcp-v2

Official Harness MCP Server: github.com/harness/mcp-server

— -

FAQs

What is the Harness MCP server?

The Harness MCP server is an MCP-compatible server that lets AI agents interact with Harness resources using a small set of generic tools.

Why does MCP tool count matter?

Each exposed tool adds metadata to the model context. A smaller tool surface leaves more room for reasoning and task execution.

How is the Harness MCP server different from a traditional MCP server?

Instead of exposing one tool per API endpoint, it uses 11 generic tools plus a registry that maps resource types to the correct API operations.

Which AI clients work with the Harness MCP server?

The post mentions Cursor, Claude Code, Claude Desktop, Windsurf, Gemini CLI, and other MCP-compatible clients.

Is the Harness MCP server safe for production use?

The design includes write confirmations, fail-closed delete behavior, read-only mode, and controls for retries, rate limiting, and deployment transport.

‍

Architecting MCP for AI Agents: Lessons from Our Redesign was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Author: Sayantan Mondal
Filtering data is at the heart of developer productivity. Whether you’re looking for failed builds, debugging a service or analysing deployment patterns, the ability to quickly slice and dice execution data is critical.

At Harness, users across CI, CD and other modules rely on filtering to navigate complex execution data by status, time range, triggers, services and much more. While our legacy filtering worked, it had major pain points — hidden drawers, inconsistent behaviour and lost state on refresh — that slowed both developers and users.

This blog dives into how we built a new Filters component system in React: a reusable, type-safe and feature-rich framework that powers the filtering experience on the Execution Listing page (and beyond).

Prefer Watching? Here’s the Talk

The Starting Point: Challenges with Our Legacy Filters

Our old implementation revealed several weaknesses as Harness scaled:

• Poor Discoverability and UX: Filters were hidden in a side panel, disrupting workflow and making applied filters non-glanceable. Users didn’t get feedback until the filter was applied/saved.
• Inconsistency Across Modules: Custom logic in modules like CI and CD led to confusing behavioural differences.
• High Developer Overhead: Adding new filters was cumbersome, requiring edits to multiple files with brittle boilerplate.

These problems shaped our success criteria: discoverability, smooth UX, consistent behaviour, reusable design and decoupled components.

Legacy Filters UI

The Evolution of Filters: A Design Journey

Building a truly reusable and powerful filtering system required exploration and iteration. Our journey involved several key stages and learning from the pitfalls of each:

Iteration 1: React Components (Conditional Rendering)

Shifted to React functional components but kept logic centralised in the FilterFramework. Each filter was conditionally rendered based on visibleFilters array. Framework fetched filter options and passed them down as props.

COMPONENT FilterFramework:
    STATE activeFilters = {}
    STATE visibleFilters = []
    STATE filterOptions = {}
    
    ON visibleFilters CHANGE:
        FOR EACH filter IN visibleFilters:
            IF filterOptions[filter] NOT EXISTS:
                options = FETCH filterData(filter)
                filterOptions[filter] = options
    
    ON activeFilters CHANGE:
        makeAPICall(activeFilters)
    
    RENDER:
        <AllFilters setVisibleFilters={setVisibleFilters} />
        
        IF 'services' IN visibleFilters:
            <DropdownFilter 
                name="Services"
                options={filterOptions.services}
                onAdd={updateActiveFilters}
                onRemove={removeFromVisible}
            />
        
        IF 'environments' IN visibleFilters:
            <DropdownFilter ... />

Pitfalls: Adding new filters required changes in multiple places, creating a maintenance nightmare and poor developer experience. The framework had minimal control over filter implementation, lacked proper abstraction and scattered filter logic across the codebase, making it neither “stupid-proof” nor scalable.

Iteration 2: React.cloneElement Pattern

Improved the previous approach by accepting filters as children and using React.cloneElement to inject callbacks (onAdd, onRemove) from the parent framework. This gave developers a cleaner API to add filters.

children.forEach(child => {
  if (visibleFilters.includes(child.props.filterKey)) {
    return React.cloneElement(child, {
      onAdd: (label, value) => {
        activeFilters[child.props.filterKey].push({ label, value });
      },
      onRemove: () => {
        delete activeFilters[child.props.filterKey];
      }
    });
  }
});

Pitfalls: React.cloneElement is an expensive operation that causes performance issues with frequent re-renders and it’s considered an anti-pattern by the React team. The approach tightly coupled filters to the framework’s callback signature, made prop flow implicit and difficult to debug and created type safety issues since TypeScript struggles with dynamically injected props.

Final Solution: Context API

The winning design uses React Context API to provide filter state and actions to child components. Individual filters access setValue and removeFilter via useFiltersContext() hook. This decouples filters from the framework while maintaining control.

COMPONENT Filters({ children, onChange }):
    STATE filtersMap = {}           // { search: { value, query, state } }
    STATE filtersOrder = []         // ['search', 'status']

    FUNCTION updateFilter(key, newValue):
        serialized = parser.serialize(newValue)   // Type → String
        filtersMap[key] = { value: newValue, query: serialized }
        updateURL(serialized)
        onChange(allValues)

    ON URL_CHANGE:
        parsed = parser.parse(urlString)          // String → Type
        filtersMap[key] = { value: parsed, query: urlString }

    RENDER:
        <Context.Provider value={{ updateFilter, filtersMap }}>
            {children}
        </Context.Provider>
END COMPONENT

Benefits: This solution eliminated the performance overhead of cloneElement, decoupled filters from framework internals and made it easy to add new filters without touching framework code. The Context API provides clear data flow that’s easy to debug and test, with type safety through TypeScript.

New Filters UI

Inversion of Control (IoC)

The Context API in React unlocks something truly powerful — Inversion of Control (IoC). This design principle is about delegating control to a framework instead of managing every detail yourself. It’s often summed up by the Hollywood Principle: “Don’t call us, we’ll call you.”

In React, this translates to building flexible components that let the consumer decide what to render, while the component itself handles how and when it happens.

Our Filters framework applies this principle: you don’t have to manage when to update state or synchronise the URL. You simply define your filter components and the framework orchestrates the rest — ensuring seamless, predictable updates without manual intervention.

How Filters Inverts Control

Our Filters framework demonstrates Inversion of Control in three key ways.

• Logic via Props: The framework doesn’t know how to save filters or fetch data — the parent injects those functions. The framework decides when to call them, but the parent defines what they do.
• Content via Children (Composition): The parent decides which filters to render.
• Actions via Callbacks: The framework triggers callbacks when users type, select or apply filters, but it’s your code that decides what happens next — fetch data, update cache or send analytics.

The result? A single, reusable Filters component that works across pipelines, services, deployments or repositories. By separating UI logic from business logic, we gain flexibility, testability and cleaner architecture — the true power of Inversion of Control.

COMPONENT DemoPage:
    STATE filterValues
    FilterHandler = createFilters()

    FUNCTION applyFilters(data, filters):
        result = data
        IF filters.onlyActive == true:
            result = result WHERE item.status == "Active"
        RETURN result

    filteredData = applyFilters(SAMPLE_DATA, filterValues)

    RENDER:
        <RouterContextProvider>
            <FilterHandler onChange = (updatedFilters) => SET filterValues = updatedFilters>
                
                // Dropdown to add filters dynamically
                <FilterHandler.Dropdown>
                    RENDER FilterDropdownMenu with available filters
                </FilterHandler.Dropdown>

                // Active filters section
                <FilterHandler.Content>
                    <FilterHandler.Component parser = booleanParser filterKey = "onlyActive">
                        RENDER CustomActiveOnlyFilter
                    </FilterHandler.Component>
                </FilterHandler.Content>

            </FilterHandler>

            RENDER DemoTable(filteredData)
        </RouterContextProvider>
END COMPONENT

The URL Problem

One of the key technical challenges in building a filtering system is URL synchronization. Browsers only understand strings, yet our applications deal with rich data types — dates, booleans, arrays and more. Without a structured solution, each component would need to manually convert these values, leading to repetitive, error-prone code.

The solution is our parser interface, a lightweight abstraction with just two methods: parse and serialize.

• parse converts a URL string into the type your app needs.
• serialize does the opposite, turning that typed value back into a string for the URL.

This bidirectional system runs automatically — parsing when filters load from the URL and serialising when users update filters.

const booleanParser: Parser<boolean> = {
  parse: (value: string) => value === 'true',   // "true" → true
  serialize: (value: boolean) => String(value)  // true → "true"
}

FiltersMap — The State Hub

At the heart of our framework lies the FiltersMap — a single, centralized object that holds the complete state of all active filters. It acts as the bridge between your React components and the browser, keeping UI state and URL state perfectly in sync.

Each entry in the FiltersMap contains three key fields:

• Value — the parsed, typed data your components actually use (e.g. Date objects, arrays, booleans).
• Query — the serialized string representation that’s written to the URL.
• State — the filter’s lifecycle status: hidden, visible or actively filtering.

You might ask — why store both the typed value and its string form? The answer is performance and reliability. If we only stored the URL string, every re-render would require re-parsing, which quickly becomes inefficient for complex filters like multi-selects. By storing both, we parse only once — when the value changes — and reuse the typed version afterward. This ensures type safety, faster URL synchronization and a clean separation between UI behavior and URL representation. The result is a system that’s predictable, scalable, and easy to maintain.

interface FilterType<T = any> {
  value?: T              // The actual filter value
  query?: string         // Serialized string for URL
  state: FilterStatus    // VISIBLE | FILTER_APPLIED | HIDDEN
}

The Journey of a Filter Value

Let’s trace how a filter value moves through the system — from user interaction to URL synchronization.

It all starts when a user interacts with a filter component — for example, selecting a date. This triggers an onChange event with a typed value, such as a Date object. Before updating the state, the parser’s serialize method converts that typed value into a URL-safe string.

The framework then updates the FiltersMap with both versions:

• the typed value under value and
• the serialized string under query.

From here, two things happen simultaneously:

1. The onChange callback fires, passing typed values back to the parent component — allowing the app to immediately fetch data or update visualizations.
2. The URL updates using the serialized query string, keeping the browser’s address bar in sync and making the current filter state instantly shareable or bookmarkable.

The reverse flow works just as seamlessly. When the URL changes — say, the user clicks the back button — the parser’s parse method converts the string back into a typed value, updates the FiltersMap and triggers a re-render of the UI.

All of this happens within milliseconds, enabling a smooth, bidirectional synchronization between the application state and the URL — a crucial piece of what makes the Filters framework feel so effortless.

Journey of a Filter Value

Conclusion

For teams tackling similar challenges — complex UI state management, URL synchronization and reusable component design — this architecture offers a practical blueprint to build upon. The patterns used are not specific to Harness; they are broadly applicable to any modern frontend system that requires scalable, stateful and user-driven filtering.

The team’s core objectives — discoverability, smooth UX, consistent behavior, reusable design and decoupled elements — directly shaped every architectural decision. Through Inversion of Control, the framework manages the when and how of state updates, lifecycle events and URL synchronization, while developers define the what — business logic, API calls and filter behavior.

By treating the URL as part of the filter state, the architecture enables shareability, bookmarkability and native browser history support. The Context API serves as the control distribution layer, removing the need for prop drilling and allowing deeply nested components to seamlessly access shared logic and state.

Ultimately, Inversion of Control also paved the way for advanced capabilities such as saved filters, conditional rendering, and sticky filters — all while keeping the framework lightweight and maintainable. This approach demonstrates how clear objectives and sound architectural principles can lead to scalable, elegant solutions in complex UI systems.

Powering Harness Executions Page: Inside Our Flexible Filters Component was originally published in Harness Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.