The HAPI Capability Graph and Capability Planning address this problem by providing structured guidance for the agent.

HAPI Capability Graph and Capability Planning help an AI agent identify the right MCP tool, the information still missing, and the next safe step before it calls a production API. Teams can optionally add Jev, TypeSafe AI's System One Model, to interpret nuanced user language and rank a bounded set of eligible candidates with structured decisions and confidence.

An AI assistant can understand a request. That is useful. But when the request touches a real business process—booking an appointment, changing an order, onboarding a customer, resolving an account issue—understanding is only the beginning.

The assistant still has to answer the questions that matter:

• What can I safely do right now?
• What information is missing?
• Which tool is the right next tool?
• Should I ask a question, show options, or prepare an action?
• Does this change need authorization or a human confirmation?

Until now, most MCP servers have handed the model a list of tools and hoped it would infer the rest.

That works for a demo. It is not enough for work that matters.

Today, we are excited to share what we have been building for HAPI v1.2: Capability Graph, Capability Planning, and an optional classifier powered by Jev from TypeSafe.

Together, they help turn an API from a menu of possible actions into a decision guide an AI assistant can actually use.

Coming soon in HAPI v1.2. Private Beta is available by request: request a demo.

What are HAPI Capability Graph and Capability Planning?​

HAPI Capability Graph is a contract-first map of what an API can do. It captures what an operation accomplishes, when it applies, whether it reads or changes state, and what must be true before it is useful. Rather than make an agent reason from a flat list of tool names, the graph gives HAPI enough declared context to deterministically shortlist the relevant MCP tools.

Capability Planning asks a narrower, operational question: given the request and explicit business state, what is the next safe step? Its answer is bounded and explainable: the goal is complete, an action is planned, a specific detail or confirmation is required, or there is no declared safe path.

Neither feature duplicates the application. The API contract remains the source of truth for authorization, validation, side effects, and business rules. Planning prepares a proposal; it does not invoke the production API.

The problem with a flat list of tools​

MCP made it possible to connect AI clients to the APIs businesses already trust. That is a big deal. With HAPI, an OpenAPI contract can become MCP tools without rebuilding the backend or duplicating business logic in a prompt.

But a large API can expose dozens—or hundreds—of operations.

To a person, the difference between cancel an appointment, reschedule an appointment, and book a new appointment is obvious. Each has different consequences. Each needs different information. One may be irreversible; another may preserve the customer’s place and simply move it.

To an AI client looking at a flat tool list, those differences are easy to miss. The model has to infer a workflow from names, descriptions, and whatever happened to be said in the conversation. That is where assistants start asking the wrong question, selecting a nearly-right tool, or trying an action before the necessary information exists.

The answer is not more prompt instructions. It is a better contract.

From a pile of tools to a map of what is possible​

Capability Graph gives HAPI a structured understanding of an API’s operations. It can use the signals already in a well-designed OpenAPI contract and, where helpful, a small amount of explicit business context:

• what an operation helps someone accomplish;
• when it should be used—and when it should not;
• whether it reads information, changes something, or removes something;
• what needs to be true before it is useful.

That creates a more useful discovery experience. Instead of presenting an AI client with every operation at once, HAPI can deterministically narrow the field to the tools that fit the request.

Ask to “move my appointment without cancelling it,” and the assistant has a clear reason to consider rescheduling before cancellation. Ask to “find a pediatrician in Morelia,” and discovery can focus on professionals, specialties, and availability—not unrelated billing or account actions.

The API remains the source of truth. HAPI does not create a shadow workflow in an agent prompt. It makes the intent already present in the API easier to use.

The next leap: knowing what is ready​

Finding a relevant tool is only part of the job. The next question is more important:

Given what we know right now, what can happen next?

That is what Capability Planning is for.

Capability Planning lets an MCP client ask HAPI for a bounded, deterministic proposal based on explicit business state. It can tell the client whether a goal is already complete, what is missing, or which safe step can move the conversation forward.

Imagine a healthcare scheduling assistant:

1. A patient asks for a pediatrician next week.
2. The assistant finds verified professionals.
3. The patient selects one.
4. The assistant checks live availability.
5. The patient selects a time.
6. The assistant verifies the details and asks for confirmation before booking.

At every step, the assistant can be conversational and dynamic. But it does not lose the thread of the real process.

If the patient says, “Actually, I want to cancel my current appointment,” the assistant sees a different path: identify the appointment, verify the person, and obtain a clear confirmation before making an irreversible change.

This is not a rigid chatbot script. It is a live decision guide grounded in the current situation.

Four answers that make an assistant more trustworthy​

Capability Planning gives MCP clients four clear outcomes:

That is a much better experience than an assistant guessing, failing, and trying again. It is also a better experience for the teams responsible for the API: the reasons for a next step, a missing detail, or a pause are visible and reviewable.

And one boundary is important: planning does not call the API. It does not book, cancel, charge, update, or delete anything. It prepares a proposal so a person and an AI client can decide what should happen next.

How Jev from TypeSafe AI fits into MCP planning​

Deterministic rules are the right foundation for authorization, policy, and known business transitions. But people do not always describe what they need with the same words your API uses.

“Can you move my visit?”

“I need a different time.”

“Don’t cancel it—I still need the doctor.”

Those are related, but they carry nuance. That is where the optional Jev-powered TypeSafe classifier comes in.

Jev is TypeSafe AI's first public System One Model. TypeSafe describes it as an automation-oriented model that returns typed decisions with probabilities and confidence, rather than generated text for a person to interpret. In HAPI, Jev is not asked to invent an entire workflow or take control of the API. It can help interpret intent and rank a bounded set of already eligible tool candidates. Read TypeSafe's Jev introduction.

The division of responsibility is deliberate:

• HAPI and the API contract keep authorization, policy, and declared safety rules in control.
• Capability Graph builds a deterministic shortlist.
• Jev adds semantic judgment when the user’s language is nuanced or ambiguous.
• Capability Planning explains whether the next step is ready, missing information, or needs a confirmation.

That is the opportunity we are most excited about: conversational intelligence where language is fuzzy, predictable controls where the business process must be exact.

HAPI, Capability Graph, and Jev have different jobs​

No black box. No prompt spaghetti.​

The AI world does not need another layer that quietly reimplements the business.

Your API already carries hard-won knowledge: validation, permissions, state, rates, limits, and rules that have survived real customers and real edge cases. HAPI’s job is to make that knowledge available to MCP clients without copying it into a brittle agent layer.

Capability Graph and Capability Planning build on that principle.

They let teams describe the meaningful parts of a workflow once, alongside the contract they already maintain. They allow assistants to be more useful without turning them into unchecked operators. And they make it possible to introduce semantic AI judgment from Jev without giving up deterministic safeguards.

Who should care?​

This is especially interesting for teams with:

• APIs that expose many MCP tools;
• operations that sound similar but have very different consequences;
• sensitive workflows with real authorization and confirmation requirements;
• assistants that need to guide people through multi-step work without becoming a second application.

Healthcare scheduling is one example. So are customer support, order changes, travel adjustments, financial operations, internal IT workflows, and any service where “what comes next?” has a real business answer.

What is coming next​

Capability Graph, Capability Planning, and the optional Jev-powered classifier are coming in HAPI v1.2.

We are opening a Private Beta for teams that want to try the experience on real APIs and real workflows. We are particularly interested in teams ready to test a focused use case, evaluate the quality of tool discovery, and help shape the right boundaries for planning and controlled execution.

If your API is already the place where your business rules live, you are closer than you think.

Start at jev-mcp.dev, explore the HAPI documentation, or request a Private Beta demo.

Your API already knows what comes next.

Now your AI can too.

Frequently Asked Questions​

The first path feels faster on day one. It's also how a second, hidden application — a shadow of the one you already trust — gets built without anyone deciding to build it.

This series is about the second path: what actually breaks when MCP adoption goes wrong, and the concrete architecture that avoids it. Four posts, one throughline —

MCP is a contract, not a server. Your API stays the authority.

Read the series​

1. How to Adopt MCP Without Creating Technical Debt — start here. The enterprise constraints (security, auth, compliance, deployment) that MCP enthusiasm tends to skip past, and what changes when you design for them from day one.
2. MCP Shadow Implementations: Why Duplicated Business Logic Breaks Trust — the specific failure mode: an MCP server that reimplements what your API already does, and quietly drifts from it. What a shadow implementation costs, and how to keep MCP transparent instead.
3. The Hidden Scaling Problem in MCP — And How to Fix It — MCP standardizes discovery and interaction. It doesn't standardize implementation discipline. What breaks once one integration becomes hundreds.
4. 3-Legged OAuth2 for MCP Apps — the authorization-code + PKCE flow that secures MCP apps for clients like ChatGPT and Claude, and how to keep token handling anchored to your existing identity model instead of inventing a second one.

Who this series is for​

Teams past the demo stage — where an MCP server already works locally, and the next questions are the ones that actually determine whether it survives production: who owns it in a year, what happens when the underlying API changes, and whether the auth model holds up outside a sandbox.

Related reading​

This series shares its core thesis — APIs are the durable contract, MCP is an interface to it — with two other places on this blog:

• API-first vs. MCP-first and its practical follow-ups, From OpenAPI to MCP to AI Agent and MCP Elicitation Is a Symptom, Not a Strategy, work through the same idea hands-on: turning a real OpenAPI spec into a live MCP server and agent prompt, and treating a chatty tool design as a signal to fix the contract instead.
• AI Made Code Cheap. Ownership Is Still Expensive. makes the economic version of this series' argument: generating an MCP implementation per API is nearly free with AI, and owning all of them for the next five years isn't.
• Stateless MCP Servers the Enterprise Way covers the architectural sibling to "no shadows" — why the MCP layer itself shouldn't hold state your business systems already own.

Different entry points, same architecture underneath it.

That distinction may become one of the most important architecture lessons of the AI era.

Today, almost anyone inside an engineering organization can open an AI coding assistant and say:

"Here is my API. Build an MCP server for it."

A few minutes later, there is code.

It feels like productivity.

Now imagine an enterprise with 10 APIs.

Still manageable.

Now imagine 100 APIs.

Now imagine 1,000 APIs, each exposing five, ten, or fifty operations.

Suddenly, AI has helped us create an entirely new software estate sitting beside an estate we already had.

And we should ask an uncomfortable question:

Did AI eliminate work—or did it simply make technical debt cheap enough that we stopped noticing we were creating it?

This post continues the same thesis as API-first vs. MCP-first: APIs remain the durable contract, and MCP is an interface to it, not a replacement for it. What follows is the economic argument for why that distinction matters at scale — From OpenAPI to MCP to AI Agent shows exactly what "translate, don't reproduce" looks like as a single, real command, and the MCP With No Shadows series covers the enterprise-adoption side: technical debt, drift, scaling, and OAuth.

The new enterprise problem isn't generating code​

For decades, software development had a natural constraint: code was expensive to produce.

You needed engineers. Engineers needed time. Projects needed budgets.

That friction forced organizations to ask:

Is this worth building?

Generative AI changes that equation.

An engineer can now describe what she wants and receive hundreds of lines of reasonable code in seconds.

That is extraordinary.

But it creates a new architectural problem.

When the marginal cost of generating software approaches zero, the temptation is to generate software for everything.

And MCP gives us a very concrete example.

Suppose an enterprise already operates 1,000 REST APIs.

Each API exposes an average of five operations that should become AI-accessible.

That's roughly:

1,000 APIs × 5 operations = 5,000 MCP tool surfaces.

One approach is straightforward:

Give every API to an AI coding assistant and ask it to create an MCP implementation.

AI can absolutely do that.

But the important question isn't:

"Can AI generate 1,000 MCPs?"

It is:

"Why should the enterprise own 1,000 additional implementations just so AI can access capabilities the enterprise already owns?"

That is a very different question.

Welcome to the MCP Multiplication Tax​

Let's call this the MCP Multiplication Tax.

It starts innocently.

You have:

API → Business capability

Then AI arrives, and we create:

API → Business capability

plus:

MCP implementation → same business capability

The organization hasn't necessarily created a new capability.

It has created another implementation surface for reaching an existing capability.

Now multiply that across the enterprise.

10 APIs become 10 MCP projects.

100 become 100.

1,000 become 1,000.

And the multiplication doesn't stop at source code.

Each implementation potentially introduces its own:

• code
• dependencies
• tests
• CI/CD
• deployment
• vulnerabilities
• observability
• authentication integration
• authorization behavior
• documentation
• versioning
• debugging
• operational ownership

The tokens consumed generating those MCPs are almost the least interesting part of the equation.

The real bill arrives after generation.

Tokens are cheap compared with ownership​

We could estimate how many millions of tokens an enterprise might consume asking coding agents to generate thousands of MCP tools.

It would make an interesting spreadsheet.

But it could also distract us from the larger economic problem.

Suppose AI makes the initial implementation 10× cheaper.

Great.

What happens next year?

An API changes.

A security requirement changes.

A scope changes.

An endpoint is deprecated.

A parameter changes from optional to required.

A response schema changes.

A vulnerability is discovered in a dependency.

An observability standard changes.

A new authentication mechanism is introduced.

The generated code doesn't magically disappear from your software inventory.

Someone—or another AI—must understand, modify, validate, test, deploy, monitor, and eventually retire it.

So perhaps we need a new equation for the AI era:

Cost of software ≠ cost of generating software.

Cost of software = generation + validation + integration + operation + synchronization + maintenance + eventual retirement.

AI attacks the first term aggressively.

It helps with several others.

But it does not make them zero.

And at enterprise scale, multiplication matters more than individual efficiency.

Are we creating abundance-driven technical debt?​

Technical debt traditionally came from scarcity.

"We don't have enough time."

"We need to ship."

"We'll refactor later."

AI introduces something different:

technical debt created by abundance.

We can generate another service.

So we do.

We can generate another adapter.

So we do.

We can generate another MCP server.

So we do.

Each individual decision appears inexpensive.

The architecture becomes expensive collectively.

That changes the responsibility of architects.

The question used to be:

How can we build this?

Increasingly, the important question will be:

Should this software exist at all?

That may sound strange during an era obsessed with generating more software.

I think it becomes more important precisely because generating software is becoming so easy.

Your API already knows how your business works​

Consider what mature enterprise APIs already contain.

The API represents a contract around an existing business capability.

And when an OpenAPI description is maintained properly, it can describe much of what another machine needs to understand that capability:

paths, operations, parameters, schemas, authentication mechanisms, scopes, responses, errors, descriptions, and constraints.

That is valuable machine-readable information.

Now MCP introduces another machine interface.

The immediate instinct is:

"Let's implement the MCP version."

But there is another architectural approach:

Don't reproduce the capability. Translate the contract.

That difference is fundamental.

Instead of:

API → MCP code → AI

think:

API Contract → MCP interface → AI

The API remains where the capability lives.

MCP becomes another way of exposing it.

One capability. One source of truth. Multiple interfaces.​

This leads to a principle I believe enterprises should seriously consider:

One capability. One source of truth. Multiple interfaces.

Your REST API might serve applications.

Your CLI might serve engineers.

Your web application might serve humans.

And MCP might serve AI agents.

Those consumers don't require four copies of your business logic.

They require different interfaces to the same capability.

That distinction becomes especially important as AI interfaces multiply.

Today, we are discussing MCP.

Tomorrow there will be additional agent protocols, interfaces, and interaction models.

If every new interface requires enterprises to regenerate and maintain their business capabilities, we are heading toward enormous software duplication.

The better architecture is one in which interfaces can evolve while the underlying business capability remains authoritative.

MCP should not become the shadow of your API​

A duplicated MCP implementation doesn't stay identical to the API it was copied from. The API changes; the shadow doesn't change with it, unless someone remembers to update it too. Now API behavior ≈ MCP behavior — approximately, not exactly — and keeping that approximation close enough is itself ongoing work, multiplied by every implementation you created instead of exposing.

The goal isn't to maintain a perfect shadow. It's to avoid needing one. (I go deeper on exactly how this drift happens, and what to do instead, in MCP Shadow Implementations: Why Duplicated Business Logic Breaks Trust.)

What does this mean for HAPI MCP?​

This is one of the architectural ideas behind HAPI MCP.

The premise is deliberately simple:

MCP is a contract, not a server.

If an enterprise already has APIs describing and implementing its business capabilities, HAPI MCP shouldn't require those capabilities to be rewritten simply because an AI agent needs access to them.

Instead, the existing API remains authoritative.

HAPI MCP transparently exposes that API through MCP.

Conceptually:

Existing API → OpenAPI contract → HAPI MCP → MCP tools → AI

The business logic stays where it belongs.

In the API.

The API team continues improving its API.

Security remains anchored to the API architecture.

Observability remains connected to real API execution.

And the MCP interface becomes a machine-facing projection of that existing contract rather than another independent implementation of the business capability.

That changes the scaling equation.

What happens when you reach 1,000 APIs?​

This is where architecture stops being theoretical.

At 10 APIs, almost anything works.

You can manually generate MCP servers.

Review them.

Fix them.

Deploy them.

Maintain them.

At 100 APIs, patterns start to matter.

At 1,000 APIs, architecture becomes economics.

The organization has to think about:

How many artifacts are we creating?

How many systems need patching?

How many repositories need governance?

How many implementations can drift?

How many security surfaces are we adding?

How many engineering hours are required simply to keep equivalent capabilities equivalent?

This is why measuring only AI token consumption misses the bigger story.

Suppose AI becomes dramatically cheaper next year.

The argument becomes even stronger.

Because the cheaper code generation becomes, the easier it becomes to accidentally generate an enormous amount of software nobody really needed to own.

AI productivity needs an architecture counterweight​

There is a strange paradox developing.

AI gives individual developers extraordinary leverage.

An engineer can produce more code, faster than ever.

But an enterprise does not necessarily want maximum code production.

It wants maximum business value with minimum unnecessary complexity.

Those are not the same thing.

A developer might celebrate:

"AI generated our MCP server in 15 minutes."

An architect should ask:

"What did we just commit ourselves to owning for the next five years?"

Both perspectives matter.

But at enterprise scale, the second question becomes increasingly important.

The next AI optimization may be deleting the generation step​

We often talk about optimizing prompts.

Optimizing context windows.

Reducing tokens.

Compressing schemas.

Using smaller models.

Caching responses.

All of those can matter.

But sometimes the largest optimization comes before inference even begins:

Don't generate software you don't need.

If an API already expresses a business capability, perhaps the most efficient MCP implementation is not another implementation at all.

Perhaps it is a transparent interface over the capability that already exists.

That means fewer generated artifacts.

Less duplicated logic.

Less synchronization.

Less infrastructure.

Less security surface.

Less maintenance.

And, yes, fewer tokens spent repeatedly asking AI to recreate representations of systems we already built.

AI changed the architect's job​

There was a time when architecture helped organizations figure out how to build difficult things.

AI is changing the constraint.

Increasingly, building isn't the difficult part.

Resisting unnecessary building might be.

When an engineer can generate another service in minutes, architectural discipline becomes more valuable, not less.

We need people asking:

Does this need to be code?

Does this capability already exist?

Can we expose rather than reproduce it?

Where is the source of truth?

What happens when the original changes?

Who owns this five years from now?

And perhaps the most important:

Are we using AI to reduce complexity—or simply using AI to create complexity faster?

What "Translate, Don't Reproduce" Looks Like in Practice​

This isn't a hypothetical trade-off. It's the difference between two commands.

Generating a standalone MCP implementation for one API — the version that becomes another repository, another CI pipeline, another thing that drifts — starts with an AI coding assistant and a prompt. Multiply that by however many APIs the organization owns, and the multiplication tax starts compounding immediately: 1,000 prompts, 1,000 repositories, 1,000 things that can drift from the API they were supposed to represent.

Translating the existing contract instead looks like this:

hapi serve --specs ./openapi.yaml --url https://api.internal.example.com --headless

One command. No generated repository. No second implementation to patch when the API's auth scheme changes next quarter. The OpenAPI document is read, not reproduced — the same spec the REST clients already trust becomes the MCP contract, computed fresh every time the server starts, never drifting because there's nothing to keep in sync.

At one API, both approaches look similar. At 1,000, one of them is still one command per API, and the other is 1,000 things somebody has to own. That gap is the multiplication tax, made concrete.

Code is becoming abundant. Simplicity is becoming scarce.​

That may be one of the defining engineering challenges of the next few years.

AI will generate astonishing amounts of software.

Some of it will create enormous value.

Some of it will exist only because creating it became almost free.

Enterprises need to learn the difference.

For MCP, my position is simple:

Don't create another implementation of a capability merely because another interface needs access to it.

Keep the light on your APIs.

Keep them authoritative.

Make them machine-readable.

Design them well.

Then expose those capabilities to humans, applications, automation systems, and AI through the interfaces each consumer needs.

That's the philosophy behind HAPI MCP:

Your APIs already do the work. MCP should make them accessible to AI—not make you build them again.

Because in the AI era, the competitive advantage may not belong to the company that generates the most code.

It may belong to the company that knows which code it never needed to generate.

Frequently Asked Questions​

See the one-command version for yourself. Run hapi serve --specs <your-openapi-spec> --headless against an API you already own, then read From OpenAPI to MCP to AI Agent for the full path from that command to a live server and a ready-to-use agent prompt — zero additional implementations to own.

MCP elicitation is a real, spec-defined capability, and it solves a real problem. It's also becoming a convenient place to hide a design problem instead of fixing it.

This is the third post in a series about building MCP the API-first way. The first makes the case that APIs — not MCP — are the durable contract. The second walks through turning a production OpenAPI spec into a live MCP server and a ready-to-use agent prompt, zero code. This one is about a specific symptom that shows up once that server is live: how often it needs to stop and ask.

What Elicitation Actually Is​

The MCP specification defines elicitation/create: a server-to-client request that pauses a tool call and asks the connected user for structured input, validated against a JSON Schema the server provides. The client responds with one of three actions — accept (with the data), decline, or cancel — and the server continues from there.

It's a genuinely useful primitive, and the spec is deliberate about its shape. Two constraints matter more than they might look at first:

1. The requested schema is flat and primitive-only. Strings, numbers, booleans, and enums — no nested objects, no arrays of objects. The spec is explicit that this is intentional, "to simplify client implementation."
2. Servers must not request sensitive information through elicitation. It's designed for a missing username, a confirmation, a choice between options — not for carrying meaningful business data into a call.

Put those together and elicitation's actual design target becomes clear: one small, simple gap, confirmed on the spot. It was never meant to be the mechanism that assembles a whole request out of pieces, or that stitches one API call to the next. If your server is asking it to do that, the schema constraints will fight you the entire way.

The Real Question: Why Was the Model Guessing?​

Every elicitation call starts from the same place: the model tried to call a tool and didn't have something it needed. Before reaching for elicitation as the fix, it's worth asking why that value wasn't already available — because the answer usually points somewhere more useful than "ask the user."

There are really only two honest answers:

The tool's input contract didn't say the field was required. If an operation genuinely can't run without a channel or a recipientId, and your OpenAPI spec doesn't mark it required, the model has no way to know it needs to supply one until the call already failed — or until your server stops mid-task to ask. That's not a limitation of the model. It's a spec that describes the operation less precisely than the operation actually behaves.

The value depends on a previous step's result. "Which club?" only comes up because nothing told the agent that this call needs the output of an earlier call. That's not missing information — it's a missing sequence. Elicitation papers over it by asking the human to relay a value the system already computed two steps ago.

Neither of those is what elicitation was built for. Both are fixable before the model ever has to ask.

Fix One: Make the Contract Say What It Means​

hapi serve --dry-run computes the exact tool list a live server exposes, including the required-parameter summary for every operation, straight from the OpenAPI spec:

hapi serve --dry-run --output markdown --specs ./openapi.yaml --headless

1. **getStats**: Get Athlete Stats - Returns the activity stats of an
   athlete... Required parameters: id (integer).
2. **sendMessage**: Send a message. No required parameters.

That second line is the tell. If sendMessage genuinely can't run without a recipient, "No required parameters" isn't a convenience — it's a gap that's going to surface at runtime, either as a failed call, a guessed value, or an elicitation request asking the user for something the spec should have already declared. The fix costs nothing at runtime: mark the field required in the OpenAPI document, and every consumer — the live MCP server, the dry-run preview, and any agent reasoning about the tool — sees the same accurate contract before a single call is made.

It's the same principle behind how HAPI derives readOnlyHint and destructiveHint for every tool from the HTTP method or explicit x-* extensions, and how the hapi-agent-prompt-generator skill writes "never guess a required parameter — ask the user for clarification" directly into the generated Tool-Use Policy. Precision in the spec is what lets every layer above it — the annotations, the agent prompt, the model's own judgment — stop guessing.

Fix Two: Make the Sequence a Workflow, Not a Conversation​

The second case is different. There's nothing wrong with the individual operations — getLoggedInAthleteClubs and getClubActivitiesById are both perfectly well-specified. The problem is that nothing connects them. The model has to either ask "which club?" or guess, because the dependency between the two calls only exists in its head, re-derived every single time.

That's exactly what HAPI Workflows, built on the Arazzo specification, are for: expressing the dependency once, as data, instead of leaving it to be reconstructed in conversation.

workflowId: reviewClubActivity
steps:
  - stepId: findClub
    operationId: getLoggedInAthleteClubs
    outputs:
      clubId: $response.body#/0/id

  - stepId: fetchActivities
    operationId: getClubActivitiesById
    parameters:
      - name: id
        value: $steps.findClub.outputs.clubId

(Illustrative shape — see the HAPI Workflows guide for the full, valid Arazzo syntax.)

fetchActivities doesn't need to ask anything, because findClub's result is already wired into its input. Serve it and validate it offline before anything runs:

hapi arazzo validate --specs ./workflow.arazzo.yaml
hapi workflows serve --specs ./workflow.arazzo.yaml --headless

The sequence is explicit, deterministic, and runs the same way every time — not reconstructed by an LLM's best guess about what the last tool call probably returned.

A Quick Way to Tell Which Fix You Need​

Where Elicitation Is Actually the Right Call​

None of this is an argument against elicitation. It's an argument against reaching for it first.

Confirming a destructive action — "you're about to cancel this subscription, confirm?" — is precisely the scenario the spec's three-action accept/decline/cancel model was built for, and precisely the boundary a well-written agent prompt's Guardrails section should already be enforcing before the tool is even called. Asking for something that is genuinely a human judgment call, not a system fact your API could have supplied, is the other legitimate case.

There's also a practical reason to keep elicitation for exactly these narrow cases and nothing more: not every MCP client has implemented it yet. A server that depends on elicitation to complete ordinary, non-destructive operations only works with the subset of clients that support it. A server whose ordinary operations are fully specified — and whose multi-step processes are explicit workflows — works everywhere, and reserves elicitation for the one job every client that supports it will actually need it for: getting a human's explicit yes.

The Lesson​

If your MCP server needs to stop and ask, ask a harder question first:

Was that information genuinely unknowable in advance — or did it leak out of a spec that should have said "required," or a sequence that should have been a workflow?

Fix the spec. Wire the sequence. Save elicitation for the one thing nothing else can do: asking a human what only a human can decide.

Frequently Asked Questions​

See it in your own spec. Run hapi serve --dry-run --output table --specs <your-openapi-spec> and check the required-parameter column against what your operations actually need — that gap is usually where elicitation was about to start doing a spec's job for it.

Many software companies have spent years, and sometimes decades, turning business rules, customer needs, operational lessons, security controls, and hard-won reliability into production APIs.

Then AI arrives, and the first instinct is often: We need to rebuild the platform for agents.

That can be a costly mistake.

Milano Software is taking a more practical path. Instead of replacing its reliable API platform to make it useful to AI, the company is exploring how to expose selected capabilities through the Model Context Protocol (MCP). HAPI MCP provides the bridge.

The goal is not to make the APIs obsolete. The goal is to make them HAPI: accessible to AI consumers while preserving the platform, business logic, and deployment model Milano already trusts.

This collaboration has also been an important source of real-world feedback and validation for HAPI MCP version 0.8, especially for enterprise environments where "just deploy it in the public cloud" is not a valid answer.

The business lesson: AI adoption should compound previous investments​

Milano Software provides business management technology for salons, spas, fitness businesses, retail operations, and other service-based companies. Its public product portfolio covers capabilities such as appointment booking, customer relationship management, point of sale, inventory, reporting, payments, and marketing. Its Klickbook platform extends that experience through a cloud-based booking and business management solution. (Milano Software, Klickbook)

Those capabilities represent more than endpoints.

Behind each API operation are years of decisions:

• What information is required to create an appointment?
• Which staff members can provide a service?
• How should inventory change after a sale?
• What happens when a booking is moved or cancelled?
• Which customer, payment, or operational rules must always be enforced?

That is where the real value lives.

Rebuilding those capabilities in a separate "AI-native" platform would not automatically create more intelligence. It could create duplicated logic, inconsistent behavior, new security boundaries, more systems to operate, and another place where defects can hide.

In business terms, that means more cost, more risk, and a longer road to customer value.

The better question is:

How can an AI application use the trusted capabilities that already exist?

That is the problem HAPI MCP is designed to solve.

What does it mean to make an API "HAPI"?​

Making an API HAPI does not mean translating every endpoint into an MCP tool and dropping the entire catalog into an agent’s context.

It means creating a controlled AI-facing capability layer over the existing API estate.

MCP is an open standard that connects AI applications with external systems. An MCP server can expose tools that allow a model to retrieve information, invoke an API, or perform an action through a defined schema. (MCP introduction, MCP tools specification)

HAPI MCP builds on that model with an API-first principle:

MCP is a contract for AI consumers, not a reason to replace the service behind the contract.

The existing API remains the system interface. It continues to serve web applications, mobile applications, integrations, automation, and developers. HAPI MCP adds an interface designed for AI clients and agents.

This separation matters because APIs and MCP serve related but different consumers:

One does not need to replace the others. They can work as layers of the same architecture.

Why not expose every API operation to the agent?​

Milano has many APIs and many possible AI use cases. That creates opportunity, but it also creates an important design challenge.

An API catalog is usually organized for software developers. An AI agent does not navigate that catalog the same way a developer does.

If hundreds of narrowly defined operations are exposed at once, the model must spend more context and reasoning capacity deciding which tool to use. Similar tools may compete with one another. Tool descriptions become more difficult to distinguish. The probability of selecting the wrong operation, or supplying the wrong arguments, can increase.

The shortcut is not "convert everything."

The shortcut is to start with a valuable business intent and expose only the capabilities required to fulfill it.

For example, a future scheduling assistant may need to:

1. Identify a customer.
2. Find eligible services and staff;
3. check real availability;
4. create or modify an appointment; and
5. return a clear confirmation.

The underlying platform may use several API calls to complete that work. The AI consumer should not necessarily be forced to understand every internal step.

HAPI MCP can present a smaller, purpose-built tool surface aligned with the user’s intent while allowing Milano’s existing APIs to remain the source of truth.

This is context engineering, not merely protocol conversion.

How does HAPI MCP reduce the cost and risk of enterprise AI adoption?​

1. It protects the investment already made in APIs​

Reliable APIs contain proven business logic. Reusing them avoids creating a second implementation that must be developed, tested, secured, documented, monitored, and maintained.

The business impact is direct: less duplicated engineering and a shorter path from AI experiment to working capability.

2. It creates a controlled boundary for AI​

An AI model should not receive unrestricted access to every internal operation simply because the API exists.

The MCP layer can expose a curated set of tools for a specific role or use case. Teams can decide what the agent is allowed to see, which actions it can request, and which capabilities should remain unavailable.

That makes the AI surface deliberate instead of accidental.

3. It supports incremental delivery​

Milano does not need to complete every AI use case before delivering the first one.

The roadmap can move capability by capability:

• select one meaningful user outcome;
• identify the trusted APIs behind it;
• expose a focused MCP toolset;
• test how agents behave;
• validate with real stakeholders; and
• expand based on evidence.

Each use case becomes a manageable product decision, not a platform rewrite.

4. It keeps deployment choices open​

Enterprise software does not live in one universal environment. Some customers use public cloud services. Others require on-premise deployment, hybrid integration, or networks with limited or no external connectivity.

HAPI MCP was designed from day zero with these enterprise realities in mind. The MCP layer can run close to the APIs and data it needs to access, including on-premise and air-gapped environments. It can also support public-cloud and hybrid architectures where those models fit the organization.

This is strategically important: AI enablement should not force a customer to abandon its infrastructure, security posture, or data-location requirements.

5. It creates an architecture that can evolve​

MCP is becoming an important interface for AI applications, but it is still one part of a broader software architecture.

Keeping the underlying APIs intact preserves optionality. Milano can serve today’s AI assistants, tomorrow’s agents, conventional applications, partner integrations, and deterministic workflows without betting the entire platform on one interaction model.

Why on-premise and air-gapped AI matter​

Public demonstrations of AI often assume three things: the application can reach the internet, the data can leave the environment, and a managed cloud service can be added without friction.

Enterprise deployments are not always that simple.

An on-premise or air-gapped environment may exist because of privacy obligations, customer contracts, security policy, latency, system dependencies, or operational control. These are not edge cases to dismiss. They are architecture requirements.

This changes the AI adoption conversation.

The question is no longer only, "Which model should we use?" It becomes:

• Where will the model run?
• Where will the MCP server run?
• Can tool execution remain inside the trusted boundary?
• How will authentication and authorization be enforced?
• What information can enter the model context?
• How will actions be logged and reviewed?
• Can the solution operate when external services are unavailable?

HAPI MCP cannot make governance decisions on behalf of an enterprise. It can, however, provide an architecture that respects those decisions instead of assuming them away.

That distinction is essential for companies like Milano Software, whose platform must work in the environments its customers actually operate.

What did Milano Software validate in HAPI MCP 0.8?​

The most valuable product feedback rarely comes from a perfect demo. It comes from applying a product to a real platform with real constraints, numerous APIs, and a roadmap that must produce business value.

Through my collaboration with Imran Zalfackruddin, CEO of Milano Software, HAPI MCP 0.8 has benefited from feedback grounded in those realities.

The collaboration has reinforced several principles behind HAPI MCP:

• Enterprises need a path to AI that builds on their reliable APIs.
• MCP tools should be organized around use cases and user intent.
• Large API estates require curation and progressive exposure.
• On-premise and air-gapped deployment cannot be treated as an afterthought.
• Cloud, on-premise, and hybrid environments should be architecture choices, not product limitations.
• Feedback from API owners is as important as feedback from AI developers.

This validation is meaningful because Milano is not evaluating MCP as an isolated technology experiment. MCP is part of a larger plan to evolve an established software platform toward AI-enabled solutions.

That is exactly the environment HAPI MCP is intended to support.

Where does Clawne Me fit?​

HAPI MCP makes trusted software capabilities accessible to AI. Clawne Me focuses on making those AI capabilities accessible to people.

This is an important separation.

A business owner should not need to understand API paths, JSON schemas, MCP transports, model configuration, or agent infrastructure to ask for an outcome.

They should be able to say:

• "Find open appointment times for Friday afternoon."
• "Which products need to be reordered this week?"
• "Summarize yesterday’s sales and cancellations."
• "Follow up with customers who missed their appointments."

The user interacts with a specialized Clawne through a familiar channel. The Clawne interprets the request. HAPI MCP provides the controlled connection to the business capabilities. Milano’s APIs execute the trusted logic.

The stack becomes:

People → Clawne Me → HAPI MCP → Milano APIs → Business systems

Each layer has a clear responsibility:

• Clawne Me simplifies delegation and human–AI interaction.
• HAPI MCP provides the contextual and controlled AI interface.
• Milano APIs preserve business logic and reliable execution.
• La Rebelion Labs develops and shares the practical architecture patterns behind this approach.

Together, they demonstrate a broader idea: enterprise AI becomes more useful when it meets businesses where they already are.

What should other API-first companies learn from this collaboration?​

Do you need to rebuild your platform to become an AI company?​

No. In many cases, rebuilding is the slower and riskier path. If the current APIs reliably expose valuable business capabilities, add an AI-facing layer before considering a replacement.

Should every endpoint become an MCP tool?​

No. Begin with user intent. Expose a focused set of tools required for one outcome, validate agent behavior, and expand deliberately.

Is MCP only for public-cloud AI?​

No. MCP servers can run locally or remotely. The correct topology depends on security, data, connectivity, and operational requirements. The official MCP architecture explicitly supports local and remote server models. (MCP architecture overview)

Does MCP replace REST or gRPC?​

It should not have to. REST and gRPC remain strong interfaces for applications and developers. MCP provides a complementary contract designed for AI consumers.

What is the best first AI use case?​

Choose a task that is valuable, bounded, measurable, and already supported by reliable APIs. Avoid beginning with the largest possible autonomous agent. Start with a capability where success and failure are easy to observe.

The bigger idea: preserve reliability while changing the interface​

AI changes how people can interact with software. It does not erase the need for trusted business logic, security, predictable execution, observability, or operational discipline.

That is why Milano Software’s approach matters.

The company is not treating its existing platform as technical debt that must be discarded before AI can begin. It is treating its APIs as strategic assets that can be made available to a new class of consumer.

HAPI MCP provides the shortcut, not by skipping architecture, but by avoiding unnecessary reinvention.

There is still serious work ahead. Milano has many APIs and use cases on its roadmap. Each capability must be designed, scoped, secured, tested, and validated. But the path is now clearer:

1. Keep the reliable platform.
2. Select the business outcome.
3. Curate the required API capabilities.
4. Expose them through HAPI MCP.
5. Connect them to the right AI experience.
6. Learn, validate, and expand.

That is a more responsible way to accelerate AI adoption, and a more sustainable way to become an AI-enabled software company.

Thank you, Milano Software and Imran​

I want to thank Milano Software and Imran Zalfackruddin for the feedback, practical challenges, and validation they have contributed to HAPI MCP 0.8.

Building an enterprise-ready product requires more than implementing a protocol. It requires listening to organizations that have reliable platforms, real customers, demanding environments, and meaningful AI roadmaps.

This collaboration is helping HAPI MCP become stronger for on-premise, air-gapped, hybrid, and public-cloud use cases.

And it confirms the principle that started this work:

Your APIs do not need to be replaced to participate in the AI era. They need the right interface for AI.

That is how we make APIs HAPI.

Suggested SEO metadata​

SEO title: Milano Software Accelerates Enterprise AI Adoption with HAPI MCP

Meta description: Learn how Milano Software is using HAPI MCP to connect reliable enterprise APIs with AI across on-premise, air-gapped, hybrid, and cloud environments, without rebuilding its proven platform.

Primary keyword: enterprise AI adoption with HAPI MCP

Secondary keywords: API to MCP, enterprise MCP server, on-premise MCP, air-gapped AI, Milano Software AI, Model Context Protocol, Clawne Me, La Rebelion Labs

Suggested LinkedIn post​

The fastest path to enterprise AI may be the platform you already have.

Milano Software has spent years building reliable APIs around real business operations: appointments, customers, inventory, payments, reporting, and more.

Rebuilding that platform "for AI" would duplicate logic, add risk, and delay value.

Our collaboration is exploring a better path: preserve the APIs and make selected capabilities available to AI through HAPI MCP.

This work has provided valuable feedback and real-world validation for HAPI MCP 0.8, especially for on-premise and air-gapped environments. Public cloud and hybrid deployments remain options, but they should be choices, not requirements.

Thank you to Milano Software and Imran Zalfackruddin for helping us test the principle behind HAPI MCP:

Your APIs do not need to be replaced to participate in the AI era. They need the right interface for AI.

That is how we make APIs HAPI.

#HAPIMCP #ModelContextProtocol #EnterpriseAI #APIs #AgenticAI #ClawneMe #LaRebelionLabs

What's usually missing is the last mile: turning that spec into something an agent can actually discover, call safely, and reason about, without you writing an MCP server by hand, and without your team improvising a system prompt from scratch every time a new API needs one.

This is exactly what the HAPI CLI automates, end to end, from a spec you already have.

The Gap Between "It Has an OpenAPI Spec" and "An Agent Can Use It"​

An OpenAPI document is a contract for deterministic clients, code that already knows which endpoint to call and how to parse the response. An AI agent needs more than that contract to act well:

• A tool list it can actually reason about, names, descriptions, and parameters, not a 3,000-line YAML file.
• A sense of scale, is this five tools or fifty? Every tool definition an agent has to hold in context costs real tokens, before a single user turn happens.
• A policy, when should it call a tool at all, what needs a human's explicit go-ahead, what happens when a call fails.

None of that lives in the OpenAPI spec itself. Historically, closing that gap meant a developer reading the whole spec and writing all of it by hand, for every API, every time.

Step 1: From OpenAPI to a Running MCP Server​

Point hapi serve at any OpenAPI document, local, remote, doesn't matter, and it's live:

hapi serve strava \
  --specs https://docs.mcp.com.ai/apis/openapi/strava-connector.yaml \
  --url https://www.strava.com/api/v3 \
  --headless

That's the whole setup. --headless skips the REST/Swagger surface and exposes only the MCP endpoint, every operationId in the spec becomes an MCP tool, with the same validation, security scheme handling, and error behavior your API already has. Nothing was rewritten. Nothing was reimplemented. The OpenAPI document is the MCP server, generated on the fly.

Step 2: Preview Before You Commit, --dry-run​

Before you deploy anything, you want to know exactly what an agent connecting to this server will see. hapi serve --dry-run computes the tool list without binding a port or starting anything:

hapi serve --dry-run \
  --specs https://docs.mcp.com.ai/apis/openapi/strava-connector.yaml \
  --url https://www.strava.com/api/v3 \
  --headless

NAME          READ-ONLY  DESTRUCTIVE  OPEN-WORLD  DESCRIPTION                     DESC LEN
getStats      true       false        true        Get Athlete Stats - Returns...  71
...

13 tools · ~2140 tokens (estimate; rule of thumb: ~4 chars/token over the tools/list payload)
Fewer tools and shorter descriptions reduce MCP context bloat. Read more: https://docs.mcp.com.ai/

Two things happen here that are easy to miss the value of until you've been burned by them:

1. readOnlyHint/destructiveHint/openWorldHint are computed automatically, from the HTTP method (GET → read-only, POST/PUT/DELETE → destructive) or from x-readOnlyHint/x-destructiveHint extensions when your spec already declares them. This is the same annotation data MCP clients use to decide how cautiously to treat a tool.
2. The token estimate is a context-bloat check, not decoration. A tool list that costs a few thousand tokens before a user has typed anything is a well-documented cause of worse tool selection and higher latency. Seeing the number before you ship the server is the whole point, it's a kubectl top for your tool list.

Step 3: From Tool List to Agent System Prompt​

A tool list isn't a system prompt. An agent that's good at using these tools needs a role, an objective, a tool-use policy, an operational process, defined error handling, and explicit guardrails, the same six-part structure any well-built agent prompt needs, regardless of which API sits underneath it:

• Role & Scope, who the agent is, its expertise, and its boundaries.
• Objective, the exact end-state it's trying to reach for the user.
• Available Tools & Policy, what each tool does, and when it should (and shouldn't) be called.
• Operational Process, a step-by-step reasoning loop: analyze, plan, execute, verify, respond.
• Error Handling & Edge Cases, what to do when a tool fails, returns nothing, or needs a human.
• Guardrails & Boundaries, hard limits on destructive actions that need confirmation or are forbidden outright.

--output markdown generates exactly this template, with Available Tools already filled in from the live tool descriptors:

hapi serve --dry-run --output markdown \
  --specs https://docs.mcp.com.ai/apis/openapi/strava.json \
  --url https://www.strava.com/api/v3 \
  --headless

Everything HAPI can derive deterministically is filled in, including naming the actual destructive tools (updateLoggedInAthlete, starSegment, createActivity, and so on) directly inside the Guardrails placeholder, so whoever completes it isn't starting from a blank page. Everything that requires understanding what the API is for, the Role, the Objective, the Policy, the Process, is left as a clearly marked <PLACEHOLDER: ...>, never a guess dressed up as a finished answer.

That's where the companion skill comes in. Pipe the dump straight to your coding agent of choice:

hapi serve --dry-run --output markdown --specs ./openapi.yaml --headless \
  | claude -p '/hapi-agent-prompt-generator complete the placeholders from the hapi serve dump'

hapi-agent-prompt-generator reads the API's actual purpose, the spec, the provider's docs if it's a known public API, the implementation if you have it, and writes the real thing. For Strava's full API, that produces something like:

# Role
You are Strava Coach, an expert endurance-sports coaching assistant built
on the Strava API v3. Your domain is the connected athlete's own training
data... You are not a medical, nutrition, or injury-diagnosis professional.

# Tool-Use Policy
- Only call a tool when the request needs live Strava data or an explicit
  action on the athlete's account...
- Treat the five write tools, updateLoggedInAthlete, starSegment,
  createActivity, updateActivityById, createUpload, as requiring the
  athlete's explicit "yes, do it"...

# Guardrails & Boundaries
- Never execute updateLoggedInAthlete, starSegment, createActivity,
  updateActivityById, or createUpload without the athlete's explicit
  confirmation of the exact change immediately beforehand...

No <PLACEHOLDER: ...> markers left, no generic filler, a prompt grounded in what this specific API actually does, generated from a spec you didn't have to touch.

The skill ships with the HAPI CLI and works the same way from Claude Code, Codex CLI, or GitHub Copilot CLI, ask whichever agent you already use to install it for itself; there's one canonical skill file, not a different install procedure per tool.

Bonus: The Same Workflow Prepares a ChatGPT App Submission​

Submitting an MCP server as a ChatGPT App requires a chatgpt-app-submission.json file: app_info, per-tool annotations and justifications, test_cases, negative_test_cases, normally assembled by hand, by reading through your own source code. It's the exact same "deterministic where possible, honest placeholder otherwise" idea, just aimed at a different output:

hapi serve --dry-run --output json \
  --specs https://docs.mcp.com.ai/apis/openapi/strava-connector.yaml \
  --url https://www.strava.com/api/v3 --headless \
  | claude -p '/hapi-apps-dump complete the placeholders from the hapi serve dump'

Tool names, descriptions, and annotations come straight from the same computation --output markdown and the live MCP server use, one source of truth, not three implementations that can quietly drift apart. app_info.description, each tool's justifications, and the test cases are left as placeholders until the hapi-apps-dump skill (or you) fill them in with real, specific content.

Two different deliverables, a system prompt and a submission file, from the same dry-run, the same tool computation, the same zero-code starting point: your existing OpenAPI spec.

Why This Is the API-First Play​

None of this required touching the backend. No new endpoints, no MCP SDK, no hand-rolled tool schemas that quietly drift out of sync with the real API the moment someone ships a change. The OpenAPI spec you already maintain, the one with real auth, real validation, real production traffic behind it, is the only source of truth, for the REST API, the MCP server, and the agent prompt alike.

That's the actual argument for API-first in an agentic world: not that APIs are a legacy format AI agents tolerate, but that a spec you were already going to maintain is now doing three jobs instead of one, for free.

Quick Reference​

# 1. Serve any OpenAPI/Arazzo document as a live MCP server
hapi serve --specs <document> --url <backend-url> --headless

# 2. Preview the tool list, no port bound, no server started
hapi serve --dry-run --specs <document> --url <backend-url> --headless

# 3a. Generate an AI agent system-prompt template
hapi serve --dry-run --output markdown --specs <document> --headless \
  | claude -p '/hapi-agent-prompt-generator complete the placeholders from the hapi serve dump'

# 3b. Generate a ChatGPT App submission scaffold
hapi serve --dry-run --output json --specs <document> --headless \
  | claude -p '/hapi-apps-dump complete the placeholders from the hapi serve dump'

Frequently Asked Questions​

Ready to try it on your own API? Install the HAPI CLI and run hapi serve --dry-run --output markdown --specs <your-openapi-spec>, see your own tool list, your own token estimate, and your own agent prompt in under a minute.

MCP is moving toward a clearer architectural truth: servers should be stateless.

The current MCP specification says that every request must contain the information needed to process it. Servers must process requests independently and must not infer context from an earlier request—even when requests arrive over the same connection or stream. If state must outlive one request, it needs an explicit identifier that the client sends again. MCP specification

For HAPI MCP, this is not a new feature announcement.

It is validation of a design choice.

HAPI MCP was created around a simple idea:

MCP is a contract, not a server.

That distinction matters more now than ever.

Statelessness is the architectural sibling to the MCP With No Shadows series: shadows are about where business logic lives, this is about where state lives. Both come back to the same rule — the MCP layer is an interface, not a second system of record. See also API-first vs. MCP-first for the broader thesis this post assumes throughout.

The problem: too many MCP servers became mini-applications​

When teams hear "MCP server," they often start building a long-running process with hidden memory, local credentials, filesystem access, session assumptions, and business logic embedded inside it.

It can work in a demo.

Then reality arrives.

A request is retried. A container restarts. Traffic is load-balanced. An agent changes clients. A customer wants an air-gapped deployment. Security asks where credentials live. Operations asks how to trace a failed action. The conversation moves to another device.

Now the "MCP server" is no longer a simple interface. It has quietly become another application platform to secure, operate, scale, patch, and explain.

That is unnecessary technical debt when the business capability already exists behind a trusted REST or gRPC API.

The API is already where the business rules, permissions, data ownership, transactions, audit trails, and operational knowledge should live.

HAPI MCP does not ask enterprises to rebuild that foundation.

It turns the existing API contract into an AI-facing contract.

Statelessness is an enterprise design choice​

Stateless does not mean that business systems have no state.

An order has a state. A customer record has a state. A long-running export has a state. A Kubernetes deployment has a state.

The difference is where that state belongs.

A stateless MCP layer does not hide it inside a process or bind it to a connection. It references the real state explicitly:

• orderId
• customerId
• jobId
• deploymentId
• cursor
• taskHandle

This is not a small implementation detail. It is the difference between a reliable distributed system and a conversational illusion.

MCP’s sessionless direction formalizes the same pattern through explicit state handles: when an operation needs continuity, the server returns a handle and the client sends it again on the next request. The state is visible, portable, and controllable—not guessed from an open connection. SEP-2567

That maps naturally to well-designed APIs.

Why HAPI MCP never implemented stdio​

HAPI MCP has always favored HTTP-based, headless deployment because our goal was never to turn an agent’s local machine into the center of enterprise integration.

stdio can be useful for local developer tools and personal integrations. It is not "bad."

But it introduces a different operational model: a local process, an environment that may contain credentials, a lifecycle coupled to a client runtime, and assumptions that become harder to govern at scale.

HAPI MCP was designed for a different reality:

• Existing APIs are already networked capabilities.
• Enterprise authentication and authorization belong at well-defined boundaries.
• Deployments may be public cloud, private cloud, on-premises, hybrid, or air-gapped.
• Security teams need clear control of credentials, policies, and audit trails.
• Operations teams need standard observability and scalable infrastructure.
• AI clients should be replaceable without forcing a rewrite of business integrations.

The MCP specification itself distinguishes these models: it defines authorization for HTTP-based transports, while stdio implementations typically retrieve credentials from the local environment. MCP specification

For HAPI MCP, HTTP was not an afterthought. It was the correct boundary.

MCP is the interface. APIs remain the authority.​

A useful mental model is this:

The model should reason.

The system should authorize.

The API should execute.

The database or business platform should own durable state.

HAPI MCP sits between AI consumers and existing services as a protocol adapter and capability boundary. It should not become your CRM, ERP, workflow engine, filesystem, secret vault, or replacement backend.

That approach gives teams a practical rule:

Do not move business state into MCP just because the interface is conversational.

Expose the capability. Preserve the authority.

Statelessness makes MCP easier to scale and safer to govern​

When each MCP request is self-contained, the architecture gets simpler in the ways enterprises care about most.

Reliability​

Any healthy instance can process a request. A restart does not erase the meaning of a conversation. A retry does not require recovering hidden server memory. A client can reconnect without reconstructing an invisible session.

Security​

There is less hidden state to leak, fewer local environments carrying secrets, and a clearer place to apply OAuth/OIDC, API keys, mTLS, gateway policy, and least-privilege authorization.

HAPI MCP can preserve the API’s authentication and authorization design instead of inventing a second identity model around an agent runtime.

Observability​

A request can carry correlation and trace context. The current specification includes OpenTelemetry-compatible traceparent, tracestate, and baggage metadata. MCP specification

That means an organization can follow one action across:

AI request → HAPI MCP tool call → API gateway → backend service → business system.

This is how teams prove what happened, debug failures, and audit agent-driven actions.

Portability​

A stateless MCP contract can run behind a load balancer, in a Cloudflare Worker, in a container, on a private network, or inside an air-gapped environment.

That is essential for HAPI MCP’s enterprise mission: enable AI adoption without forcing customers to expose or rebuild their reliable systems.

Stateless does not mean context-free​

This is the part many teams get wrong.

A stateless server can still support rich, context-aware work. The context simply has to be explicit and intentional.

Some context belongs with the agent:

• User conversation history
• The user’s goals
• Preferences
• Prior reasoning
• Plans across multiple tools

Some belongs in the request:

• Tool arguments
• Tenant or resource identifiers
• Correlation IDs
• Explicit handles for durable tasks
• Authorized identity context

Some belongs in the system of record:

• Customer data
• Inventory
• Orders
• Cases
• Policies
• Long-running job status

HAPI MCP helps maintain those boundaries. It does not pretend that one persistent MCP process should hold all of them.

The HAPI MCP position: do not rebuild what already works​

The market spent its first MCP phase asking:

Can OpenAPI generate MCP tools?

Yes. That is increasingly the easy part.

The harder questions are:

• Which capabilities should an agent receive?
• Which parameters should the model control?
• What authorization is required for each action?
• Where does durable state belong?
• How do tools compose into predictable outcomes?
• How do we trace and prove an action?
• How do we support cloud, hybrid, on-premises, and air-gapped deployments?

HAPI MCP was built for those questions.

It transforms existing OpenAPI-described APIs into controlled MCP capabilities without asking organizations to replace their architecture. It supports the principle that REST and gRPC remain the systems of execution for developers, applications, and business services—while MCP becomes the contract that lets AI consumers use those capabilities safely.

Your APIs do not need to be rebuilt for AI.

They need the right interface.

The lesson for MCP builders​

If your MCP server needs a long-lived hidden session to work, ask a hard question:

Is that state genuinely part of the MCP layer—or did application state leak into the integration layer?

Use explicit IDs for durable work. Keep authorization close to the protected resource. Keep business rules in business services. Keep context where it belongs. Treat each MCP call as a controlled request, not a message inside a magical private conversation.

That architecture is easier to test, easier to scale, easier to secure, and easier to trust.

For HAPI MCP, the principle remains simple:

MCP is a contract, not a server. APIs are the authority. HAPI MCP is the interpreter.

Stateless MCP is not a limitation.

It is what allows AI interfaces to become dependable enterprise infrastructure.

Frequently Asked Questions​

See the same principle applied to business logic, not just state, in the MCP With No Shadows series — starting with why duplicated business logic breaks trust.

And that disagreement has a cost.

More code to maintain. More tests to write. More infrastructure to operate. More security policies to keep aligned. More places where production behavior can drift.

Most importantly, you may accidentally create two versions of the truth:

Your API behavior and your MCP behavior.

There is a simple analogy for this problem: light and shadows.

A physical shadow appears when an opaque object blocks light. Change the position of the light, and the shadow changes. Morning shadows look different from noon shadows. Move the object, and its shadow moves too.

Software can develop shadows in much the same way.

Build an MCP server that independently reimplements what your API already does, and you have created a shadow implementation.

It may look exactly like the original today.

But what happens tomorrow?

Your API changes.

Traffic increases.

Authentication rules evolve.

A validation rule gets fixed.

A new parameter appears.

The business changes its pricing logic.

Someone patches the API but forgets about the MCP implementation.

Now the shadow no longer matches the object casting it.

That is exactly the architectural problem HAPI MCP was designed to avoid.

This post is part of the MCP With No Shadows series on adopting MCP without quietly rebuilding your application behind it — see also how to adopt MCP without creating technical debt and the hidden scaling problem in MCP. It's also the deep dive behind the "shadow" section of why AI made code cheap but ownership still expensive.

The idea behind HAPI MCP is simple:

Do not rebuild your application for AI. Make the APIs you already trust transparently accessible to AI.

The light should remain pointed at your APIs.

What Is an MCP Shadow?​

Let's define the term first.

In this context, an MCP shadow is an MCP implementation that duplicates capabilities, business logic, validation, integration behavior, or operational responsibilities already implemented by an existing API.

Imagine this architecture:

Application → Business Logic → REST API

Then AI arrives.

The organization creates:

AI Agent → MCP Server → New Business Logic → Backend

At first, everything looks fine.

The MCP tools produce the expected answers.

The demos work.

The AI can finally interact with the business.

But something subtle happened.

You did not simply create another interface.

You created another implementation.

Now there are two systems representing the same business capability.

The REST API implements one version.

The MCP server implements another.

The shadow has been born.

How Do MCP Shadows Form?​

A shadow needs three things: a light source, an object blocking the light, and a surface where the shadow appears.

The software analogy is surprisingly useful.

The light: your engineering investment​

Your engineering organization continuously shines effort into your production APIs:

Security.

Testing.

Observability.

Performance.

Reliability.

Business logic.

Authorization.

Documentation.

Compliance.

Years of engineering work may already exist behind those endpoints.

The object: duplicated MCP implementation​

Instead of allowing AI consumers to reach those capabilities through the existing API contract, you build another MCP-specific implementation.

Some API logic gets copied.

Some gets simplified.

Some gets rewritten.

Some gets interpreted differently.

The MCP implementation becomes an opaque layer between AI and the API.

The shadow: behavioral drift​

Eventually, the MCP implementation begins behaving differently from the API.

And just like a physical shadow, its shape depends on conditions.

Shadows Change Depending on the Light​

Think about your own shadow outside.

At noon, with the sun directly overhead, your shadow might be small.

Near sunset, that same person can cast a shadow several times their height.

The person did not change. The conditions did.

Software behaves similarly.

An MCP implementation might work beautifully during development.

Ten requests.

One developer.

A predictable dataset.

Almost no concurrency.

Then production happens.

10 requests become 10,000.

Authentication becomes multi-user.

Rate limits appear.

Retries happen.

Network failures happen.

Backend latency increases.

Models make unexpected tool calls.

Several agents invoke the same capability simultaneously.

Suddenly, the shape of your shadow changes.

That MCP-specific implementation now has its own reliability profile, scaling characteristics, failure modes, security considerations, observability requirements, and operational burden.

You didn't just expose an API to AI.

You created another system.

And another system must be operated.

The Most Dangerous Shadow Is Duplicated Business Logic​

Imagine an ecommerce platform already has:

POST /orders

Behind that endpoint might be years of work:

• inventory validation
• pricing rules
• customer authorization
• fraud checks
• discounts
• taxes
• payment processing
• fulfillment rules
• audit logging
• error handling

Now someone creates an MCP tool:

create_order

There are two architectural possibilities.

Option A: Reimplement the capability​

The MCP server contains logic for interpreting the order, validating products, calculating some values, checking permissions, and eventually interacting with backend systems.

Now there are two implementations of create order.

Option B: Expose the existing capability​

The MCP tool maps the model's request into the existing API contract.

The API remains responsible for executing the business capability.

The architecture becomes:

AI → MCP → API → Business Logic

The MCP is an interface.

The API remains the system of record.

That distinction matters enormously.

What Happens When the API Changes?​

Suppose tomorrow the business adds a mandatory deliveryMethod field.

With duplicated MCP logic, someone must remember:

1. Update the API.
2. Update API clients.
3. Update the MCP implementation.
4. Update MCP validation.
5. Update MCP tests.
6. Verify that both implementations behave consistently.

Miss step three and something interesting happens.

Traditional applications and AI agents can now produce different business outcomes while supposedly using the same capability.

That is architectural drift.

And drift rarely announces itself with a big red warning.

It usually appears slowly.

One edge case here.

One authorization difference there.

One outdated validation rule.

Until somebody asks:

"Why did the AI allow this when the application doesn't?"

Now you have to investigate two systems.

Why Is a Single Source of Truth Important for MCP?​

Because MCP should not require organizations to duplicate everything they already built for APIs.

If your API is already the production contract for a business capability, keep it that way.

The ideal architecture is closer to:

Human applications → API

Automation → API

CLI → API

AI agents → MCP → API

Different consumers.

Same underlying capability.

That gives your architecture a clear source of truth.

When business logic changes, change it where it belongs.

When security changes, change it where it belongs.

When validation changes, change it where it belongs.

When reliability needs improvement, improve the system everyone already depends on.

Your engineering investment compounds instead of splitting.

Make Your APIs Transparent​

This is where I like reversing the shadow analogy.

Transparent objects allow light to pass through them.

That is how I want MCP to behave.

Not as another opaque application containing another version of my business.

But as a contextual interface through which AI can discover and invoke capabilities already represented by APIs.

Think:

AI Consumer ↓ MCP Contract ↓ API Contract ↓ Production Business Logic

The MCP layer provides what the AI needs:

tool discovery, tool descriptions, schemas, contextual interfaces, authorization integration, and model-friendly capability exposure.

But execution remains anchored to the existing API.

MCP becomes a window, not another building.

How Does HAPI MCP Work?​

This philosophy is one of the reasons I built HAPI MCP around a simple principle:

MCP is a contract, not a server.

HAPI MCP starts with APIs.

If an organization already exposes capabilities through REST APIs described using OpenAPI, those contracts can become the foundation for MCP tools.

Instead of asking:

"How do we rewrite this application as an MCP server?"

We ask:

"Which existing API capabilities should AI consumers be allowed to use?"

That is a very different architectural question.

HAPI MCP can expose selected API operations as MCP capabilities while the underlying APIs continue doing what they already do.

The basic model becomes:

Agent / AI Application ↓ MCP ↓ HAPI MCP ↓ Existing REST APIs ↓ Existing Business Systems

The API does not need to become an MCP application.

And the MCP layer does not need to become another copy of the application.

If the API Changes, the MCP Changes With It​

This is where API-first architecture becomes especially valuable.

Your OpenAPI contract already describes things such as:

paths,

operations,

parameters,

request bodies,

response schemas,

authentication mechanisms,

security scopes,

and errors.

That contract can become the bridge between traditional software consumers and AI consumers.

Instead of maintaining:

API implementation + MCP implementation

the goal is closer to:

API implementation + machine-readable contract + MCP projection

That word — projection — matters.

The MCP representation should ideally be a projection of the underlying capability rather than an independent implementation of it.

The API remains the source.

MCP becomes another way of seeing it.

But Should Every API Endpoint Become an MCP Tool?​

Absolutely not.

Making APIs transparent to MCP does not mean blindly dumping your entire OpenAPI specification into an agent's context.

A large API can contain hundreds or thousands of operations.

An AI agent rarely needs all of them.

This introduces another important HAPI MCP principle:

API design and MCP tool design solve different problems.

Your API may expose capabilities optimized for developers.

Your MCP surface should expose capabilities optimized around AI intent and context.

For example, a commerce platform might have hundreds of endpoints.

A customer-support agent may only need:

find_customer

get_order

check_order_status

issue_refund

Those tools can still ultimately execute against the same production APIs.

We reduce the context exposed to the model without duplicating the business logic behind the context.

That distinction is critical.

Curate the MCP surface. Do not duplicate the application.

Why HAPI MCP?​

Because the cost of AI adoption should not include rebuilding systems that already work.

Enterprises have spent years — sometimes decades — building reliable APIs.

Those APIs already contain enormous organizational knowledge.

They have been:

tested,

secured,

observed,

scaled,

integrated,

documented,

audited,

and hardened by production traffic.

Why throw that investment away because the next consumer happens to be an AI agent?

HAPI MCP takes the opposite approach.

Keep your APIs.

Keep your business logic.

Keep your production systems.

Keep improving them.

Then expose the right capabilities to AI through MCP.

This reduces duplicated logic and helps reduce the maintenance surface introduced by AI adoption.

More importantly, it gives teams a cleaner architectural boundary:

Business capability belongs to the API.

AI context belongs to MCP.

What About Authentication and Authorization?​

The same principle applies.

If authorization rules already belong to your API architecture, MCP should not become an excuse to invent a second authorization universe.

OAuth scopes, identity, permissions, and resource access should remain connected to the systems ultimately protecting the business capability.

Otherwise, authorization itself becomes another shadow.

Imagine:

API says: DENIED

MCP says: ALLOWED

That is more than technical debt.

That can become a security incident.

The closer MCP remains to the existing API contract and authorization model, the smaller that divergence surface becomes.

MCP Should Add Context, Not Duplicate Capability​

There is a useful architectural boundary here.

MCP absolutely adds value.

It gives AI systems a standardized way to discover and invoke capabilities.

It provides descriptions models can reason about.

It allows us to design tool surfaces around user intent.

It gives agents a contextual interface into existing systems.

But none of that requires MCP to own the business implementation.

That is the distinction I believe matters as MCP architectures mature.

APIs execute capabilities.

MCP contextualizes capabilities for AI consumers.

And HAPI MCP connects those worlds.

The Architecture Gets Simpler​

Compare the two approaches.

Shadow architecture​

Applications → API implementation → Backend

and independently:

AI → MCP implementation → Duplicated Logic → Backend

Now you maintain two paths.

Two behavioral surfaces.

Potentially two security models.

Two reliability profiles.

Two places to debug.

Transparent architecture​

Applications → API

CLI → API

Automation → API

AI → HAPI MCP → API

Everything eventually converges on the same production capabilities.

One source of truth.

Different interfaces.

That is much closer to how I believe AI should enter existing enterprise architectures.

Where Should the Light Go?​

This might be the most important question.

Every engineering organization has limited light.

Limited developers.

Limited budget.

Limited testing capacity.

Limited security resources.

Limited operational attention.

Where should that light shine?

I would rather put it here:

APIs

Make them more reliable.

Make them faster.

Improve authorization.

Improve observability.

Improve documentation.

Improve contracts.

Improve business logic.

Improve tests.

Because every consumer benefits.

Your web application benefits.

Your mobile application benefits.

Your integrations benefit.

Your automation benefits.

And through HAPI MCP, your AI consumers benefit too.

That is leverage.

Don't Maintain the Shadow. Illuminate the Source.​

AI agents are becoming another important consumer of enterprise capabilities.

That does not mean enterprises need another copy of their applications.

We already learned this lesson with APIs.

Separate interfaces from business capabilities.

Create contracts.

Centralize business rules.

Design clear boundaries.

Then let many different clients consume those capabilities.

MCP should extend that architecture, not undo it.

So when somebody asks:

"Should we build an MCP server for this application?"

I think there is a better question:

"Do we already have APIs representing these capabilities?"

If the answer is yes, start there.

Then ask:

"Which of those capabilities should AI consumers see, and how should they be represented as tools?"

That is the space HAPI MCP is designed for.

Not rebuilding your application.

Not copying your business logic.

Not creating another operational shadow.

But making the APIs you already trust accessible to a new generation of consumers.

Keep the light on your APIs.

Make the MCP layer transparent.

One source of truth. Many consumers. No shadow implementation.

That is the architecture behind HAPI MCP.

HAPI MCP transparently exposes your APIs as MCP.

Every few months, our industry declares the next abstraction layer "the new HTTP."

First it was SOAP.

Then REST. Then GraphQL. Then gRPC.

Now, it's MCP.

The excitement is understandable. Model Context Protocol (MCP) is changing how AI agents discover and use software. It removes friction. It standardizes tool access. It gives language models a common interface.

But that doesn't mean APIs are going away.

Quite the opposite.

I believe the future is API-first, MCP-enabled.

Not MCP-first.

The Wrong Question​

The discussion often starts with a question like this:

"If agents are the future users of software, shouldn't we build for agents first?"

I think that's the wrong question.

The better question is:

What is the most stable contract a platform can expose over the next 10-20 years?

My answer is still:

APIs.

Whether REST, gRPC, or another protocol that hasn't been invented yet.

APIs Solve a Different Problem​

People sometimes compare REST APIs and MCP as if one replaces the other.

They don't.

They solve different problems.

REST APIs answer:

• How do applications communicate?
• How is data represented?
• How are systems versioned?
• How are requests authenticated?
• How are responses cached?
• How are SLAs enforced?
• How are services monitored?

MCP answers something else:

• What tools are available?
• How should an AI discover them?
• How should the model invoke them?
• What metadata helps the model use them correctly?

Those are complementary questions.

Not competing ones.

Developers Are Not Going Away​

One assumption behind "MCP-first" thinking is that AI agents will become the primary consumers of software.

Maybe.

But even if that happens...

Someone still builds the software.

Someone still designs the APIs.

Someone still versions the contracts.

Someone still debugs production.

Someone still integrates systems.

Even autonomous agents need reliable interfaces underneath.

Ironically, many AI agents themselves generate REST calls today.

Because APIs remain the most deterministic interface available.

APIs Are the Infrastructure​

Think about the Internet.

Browsers don't replace HTTP.

Mobile apps don't replace HTTP.

SDKs don't replace HTTP.

GraphQL didn't replace HTTP.

Even gRPC often runs over HTTP/2.

Every new abstraction eventually sits on top of the previous one.

MCP feels similar.

It is another abstraction.

A useful one.

But underneath?

There is usually an API.

Sometimes REST.

Sometimes gRPC.

Sometimes GraphQL.

Sometimes something proprietary.

The foundation hasn't changed.

The interface exposed to the AI has.

MCP Is an Adapter, Not the Product​

One reason I built HAPI MCP the way I did is because I never wanted developers rewriting APIs just because AI arrived.

Organizations have spent years designing APIs.

They have:

• security reviews
• governance
• documentation
• SDKs
• monitoring
• observability
• rate limiting
• compliance
• audit trails

Why throw that away?

Instead, expose those capabilities through MCP.

The API remains the source of truth.

MCP becomes another consumer.

Exactly like:

• a web frontend
• a mobile application
• an SDK
• a partner integration

The difference is simply that the consumer happens to be an AI agent.

Today's MCP Could Be Tomorrow's Legacy Protocol​

History is surprisingly consistent.

Technology stacks evolve.

Standards evolve.

Frameworks evolve.

Developer preferences evolve.

Imagine rebuilding your backend every time the industry discovers a new protocol.

SOAP.

REST.

GraphQL.

gRPC.

MCP.

Whatever comes next.

That is expensive.

Instead, stable organizations invest in one thing:

A durable business API.

Everything else becomes an adapter.

That adapter may change every five years.

Your business logic shouldn't have to.

Enterprise Architecture Already Solved This​

Enterprise integration has used this pattern for decades.

Core systems expose stable interfaces.

Around them sit adapters.

Examples include:

• API gateways
• ESBs
• messaging systems
• event buses
• GraphQL layers
• mobile backends
• SDK generators

MCP fits naturally into that architecture.

It becomes another presentation layer.

Not the domain model.

Not the source of business rules.

Not the canonical integration contract.

AI Doesn't Eliminate APIs—It Increases Their Value​

Here's something interesting.

As AI adoption grows, API quality becomes even more important.

Why?

Because agents amplify inconsistency.

Humans compensate for poor APIs.

Agents don't.

If an endpoint behaves differently every Tuesday...

An AI won't magically fix that.

If your documentation is outdated...

The model inherits that confusion.

If your API isn't deterministic...

The agent becomes unreliable.

Good APIs become even more valuable in an AI-native world.

Not less.

My Architecture Preference​

If I were designing a cloud platform today, my stack would look something like this:

Business Logic
        │
REST / gRPC APIs
        │
-------------------------
│          │           │
SDKs     Web Apps     Mobile Apps
│
MCP Adapter
│
AI Agents

Notice something important.

The APIs don't exist because humans consume them.

They exist because they are the most stable integration contract in the system.

Everything else builds on top.

What About Skills?​

I think the same philosophy applies to AI Skills.

Skills are fantastic.

They improve discovery.

They provide context.

They help models make better decisions.

But they are not where your business logic belongs.

They describe capabilities.

They don't replace implementation.

Just like MCP.

A Better Mental Model​

Instead of asking:

"Should I build APIs or MCP?"

Ask:

"What is my canonical interface?"

For me, the answer is simple.

The API.

Everything else becomes an adapter.

That includes:

• MCP
• Skills
• SDKs
• CLI tools
• Chat interfaces
• Future agent protocols we haven't invented yet

Adapters evolve.

Core contracts should not.

Practical Guidance for Builders​

If you're designing an AI-ready platform today, consider this approach:

1. Design your APIs first. Make them deterministic, versioned, observable, and secure.
2. Keep business logic in the API layer. Avoid duplicating rules across agent-specific interfaces.
3. Expose APIs through MCP. Let AI agents consume existing capabilities instead of creating parallel implementations.
4. Use Skills to improve discoverability. Help models understand when and how to use your capabilities.
5. Treat AI interfaces as extensions. They are valuable access channels, not replacements for your platform's foundation.

This approach reduces duplication, simplifies governance, and makes your platform resilient to future protocol changes.

Frequently Asked Questions​

Will MCP replace REST APIs?​

Probably not. MCP standardizes how AI agents discover and invoke capabilities, while REST APIs define how systems communicate. They address different layers of the architecture.

Should every API have an MCP interface?​

Not necessarily. Expose the capabilities that benefit AI-driven workflows. Internal or low-level APIs may never need an MCP representation.

Can I build an AI-native application without REST?​

Yes. Some applications may use gRPC, GraphQL, messaging, or other protocols internally. The broader principle remains the same: keep a stable integration contract and layer AI-specific interfaces on top.

Is MCP important?​

Absolutely. It is one of the most promising standards for AI interoperability today. The question isn't whether to support MCP—it's where it belongs in your architecture.

The Bigger Picture​

MCP is one of the most exciting developments in the AI ecosystem. It lowers the barrier for agents to interact with software and accelerates interoperability across platforms.

But interoperability is not the same as architecture.

History has shown that durable software platforms separate core business capabilities from access mechanisms. Web browsers, mobile apps, SDKs, CLIs, and now AI agents are all different ways of reaching the same underlying services.

That is why I remain convinced that the future is not MCP-first.

It is API-first, MCP-enabled.

Because protocols will evolve.

Agents will evolve.

Models will evolve.

The businesses that succeed will be the ones whose foundations don't have to be rebuilt every time the industry invents a new way to consume software.

👉 The HAPI MCP Registry is now available in the ChatGPT marketplace, officially aligning with the ecosystem driven by OpenAI.

And this is bigger than a feature release.

This is a shift in how APIs and AI finally connect.

🧠 What Is the HAPI MCP Registry (and Why It Matters Now)​

Short answer: It's a centralized, public registry of MCP servers powered by HAPI MCP, a framework designed to turn APIs into AI-ready tools.

Long answer (the one that matters):

For years, we've built APIs as products. But AI agents don't "use" APIs the way developers do.

They need:

• Context
• Structure
• Discoverability
• Governance

That's exactly where MCP (Model Context Protocol) comes in.

And the HAPI MCP Registry solves the missing layer:

👉 A place where agents can discover, understand, and safely use real-world capabilities.

⚡ Why This Changes the Game (For Real)​

Q: Why should leadership care about MCP registries?

Because this is how you:

• Avoid shadow AI implementations
• Prevent duplicate integrations
• Enable controlled AI adoption at scale

Translation: You're not building AI from scratch, you're activating existing assets.

Q: What problem does this solve technically?

Before:

• Every agent needed custom integration
• APIs had to be adapted manually
• Governance was fragmented

Now:

• APIs → MCP → Registry → Agent consumption

Translation: You move from integration chaos → standardized execution layer

Q: How does this impact product delivery?

You can now:

• Turn APIs into features instantly
• Expose capabilities to AI without new backend work
• Launch AI-driven features faster

Translation: Your roadmap accelerates without increasing engineering load.

🔍 What Makes HAPI MCP Registry Different​

There are already tools trying to "connect APIs to AI."

Most of them:

• Add wrappers and create shadow APIs
• Force you to re-implement logic in their system
• Create new infrastructure
• Introduce lock-in

HAPI MCP takes a different stance:

👉 MCP is the contract, not the platform

That means:

• No re-implementation of business logic
• No duplication
• No vendor dependency

Just:

• Your APIs
• Standardized into MCP
• Ready for agents

🧩 How It Works (Simple Mental Model)​

Think of it like this:

Your API → HAPI MCP Server → Registry → AI Agent

That's it.

No:

• Reinvented backends
• Complex pipelines
• Fragile integrations

🌍 Why This Matters for the AI Economy​

Let's zoom out.

We're entering a world where:

• Agents are the new users
• APIs are the new interfaces
• MCP is the new contract

The problem?

👉 Everything is fragmented.

Different tools. Different integrations. Different standards (or no standards).

The HAPI MCP Registry is a step toward fixing that:

✔ Standard discovery ✔ Standard interaction ✔ Standard governance

🔥 Real Use Cases​

1. Enterprise AI Enablement​

Instead of building new AI systems:

👉 Expose internal APIs as MCP tools
👉 Let agents operate safely within boundaries

2. Telco / Open Gateway​

Think about:

• SIM Swap APIs
• Device Location
• Number Verification

Now imagine:

👉 Agents consuming them securely via MCP

That's monetization at scale.

3. Developer Ecosystems​

Instead of:

• Docs + SDKs + manual integration

You get:
👉 Plug-and-play AI capabilities

🧠 The Bigger Vision​

This is not just about a registry.

This is about:

👉 Turning every API into an AI capability layer

And ultimately:

👉 Building the execution layer of the AI economy

That's the real play.

🚀 What's Next​

This is just the beginning.

More HAPI MCPs are coming:

• New integrations
• More enterprise-ready tools
• Expanded registry capabilities

And yes... Open sourcing the HAPI MCP framework is on the horizon.

👉 This will evolve into a full distribution layer for AI-native APIs

🤝 Your Turn​

If you're building:

• APIs
• Platforms
• AI tools
• Agent workflows

You need to look at this now.

👉 Explore the HAPI MCP Registry in ChatGPT
👉 Test it
👉 Break it
👉 Tell me what's missing

Because the future of AI won't be built in isolation.

It will be built on shared, standardized capabilities.

💬 Final Thought​

We've spent years building APIs for humans.

Now we're finally building them for agents.

And this time...

We're doing it right.

Be HAPI and Go Rebels! ✊🏽

Back in the day, database engineers learned this lesson the hard way.

We didn't call it "AI cost optimization." We called it bad query design.

And it hurt.

The déjà vu: from SQL disasters to AI chatbots​

I was reading a LinkedIn post about a chatbot that cost $3K to build... and $28K/month to run.

And instantly, I had flashbacks.

To teams building dynamic SQL queries like this:

SELECT * FROM users WHERE name = 'Adrian'

But instead of using parameters, they would literally inject values into strings:

"SELECT * FROM users WHERE name = '" + userInput + "'"

At first, everything worked.

Then scale happened.

And everything broke.

What went wrong back then (and now)​

1. Every query looked "new" to the database​

Databases rely on query plan caching.

When you use prepared statements, the database sees:

SELECT * FROM users WHERE name = ?

It builds a plan once → reuses it forever.

But with dynamic queries?

Every variation is a brand new query:

SELECT * FROM users WHERE name = 'John'
SELECT * FROM users WHERE name = 'Jane'
SELECT * FROM users WHERE name = 'Mike'

➡️ The database can't reuse the plan efficiently
➡️ It recompiles again and again
➡️ Performance drops hard

2. Complexity kills performance silently​

The worse part?

It doesn't fail immediately.

It degrades slowly:

• CPU spikes
• Memory pressure increases
• Latency creeps up
• Costs rise quietly

Until one day:

"Why is everything so slow?"

3. Scale exposes the flaw​

At small scale:

"It works fine."

At real scale:

"This is burning money."

Now look at the chatbot story again​

Same pattern. Different technology.

Let's translate:

The real problem: treating every request as unique​

In the LinkedIn example:

80% of queries were just variations of the same 12 questions

But the system treated them like:

100% brand new problems.

That's the mistake.

Not the model. Not the infra. The design.

The principle we forgot​

Systems should recognize patterns. Not ignore them.

Databases solved this years ago:

• Prepared statements
• Query plan caching
• Indexing strategies

But in AI systems?

We're back to:

"Let's just send everything to the model."

Unfortunately, that approach is a recipe for:

• High costs
• Unpredictable performance
• Scaling nightmares

The modern "prepared statements" for AI​

The fix they implemented is basically database engineering... applied to AI.

1. Semantic cache (query plan cache equivalent)​

Instead of exact matches:

• Use embeddings
• Detect "close enough" questions
• Return cached answers

➡️ Same intent → same response
➡️ Zero model cost

2. Response templates (precomputed queries)​

For high-frequency questions:

• Predefine structured responses
• Skip the model entirely

➡️ Instant responses
➡️ Predictable cost

3. Model routing (query optimizer)​

Not all queries deserve the same treatment:

• Simple → cheap model or cache
• Complex → expensive model

➡️ Just like a query optimizer choosing execution paths

Business impact (this is what matters)​

Let's translate this to what leaders actually care about:

• 75% cost reduction ($28K → $7K/month)
• Faster response times (cache hits = instant)
• Better scalability (predictable cost curve)
• Lower operational risk (no runaway bills)

The dangerous illusion: "cheap AI build"​

Here's the uncomfortable truth:

The build cost is a demo metric The run cost is a business metric

And most teams optimize for the wrong one. If you focus on building something quickly without considering the long-term costs, you might end up with a system that's expensive to operate. This is especially true in AI, where every model call can incur significant costs.

Why this keeps happening​

Because AI development today feels like:

• Early web development
• Early microservices
• Early cloud adoption

Everyone is focused on:

"Can we make it work?"

Instead of:

"Can we make it scale?"

History repeating itself​

We've seen this before:

• Monoliths → microservices chaos
• Cloud → bill shock
• APIs → integration sprawl

Now:

AI → token burn without control

The shift: from "AI features" to "AI systems"​

If you're building AI in production, this is the mindset shift:

❌ Old thinking​

• Every request is unique
• Let the model handle it
• Optimize later

✅ New thinking​

• Most requests are patterns
• Design for reuse first
• Control cost at the architecture level

Where this connects to MCP​

This is exactly where MCP + API-first design changes the game.

Instead of:

Unstructured prompts → expensive model calls

You move toward:

• Structured tools
• Deterministic workflows
• Reusable operations

➡️ The system becomes predictable
➡️ Costs become controllable
➡️ Behavior becomes auditable

The takeaway (don't ignore this)​

If your AI system treats every request as new... your bill will grow faster than your users.

And the worst part?

You won't notice until it's already expensive.

Final thought​

We didn't fix dynamic SQL because it was "cool."

We fixed it because:

It was inefficient, unsafe, and impossible to scale.

AI systems are hitting that exact same moment.

The teams that win won't be the ones with the smartest models.

They'll be the ones who remember:

Efficiency is architecture, not an afterthought.

How are you designing your AI system to recognize patterns instead of treating every request as unique?

Over the last year, a clear pattern has emerged inside large enterprises experimenting with AI automation. What starts as scattered experimentation quickly evolves into a structured platform strategy.

The organizations that succeed are not the ones deploying the best model. They are the ones building the right architecture around the model.

And that architecture almost always follows the same evolution.

In many large organizations today, AI adoption is moving through three recognizable phases.

Phase 1 — AI Experimentation​

This is the discovery phase.

Teams explore tools like:

• open-source LLM frameworks
• local model hosting
• developer AI assistants
• simple workflow builders
• prototype chat interfaces

The goal is simple:

Understand what AI can do.

Developers experiment. Innovation teams build proofs of concept. Some teams automate small tasks.

At this stage, the environment looks chaotic — many tools, many ideas, little governance.

But experimentation is necessary.

It helps organizations learn where AI creates real value.

Phase 2 — Governance and Platform Infrastructure​

Once experimentation shows value, leadership begins asking harder questions.

Questions like:

• Where are these models running?
• Who has access to sensitive data?
• How do we audit AI decisions?
• How do we prevent security risks?
• How do we ensure regulatory compliance?

This is when enterprise AI platforms emerge.

Instead of scattered experiments, organizations build structured environments that include:

• model infrastructure
• access monitoring
• governance controls
• compliance frameworks
• internal tooling

The focus shifts from experimentation to control and stability.

This is also where concepts like AI sovereignty become central.

Phase 3 — Real Automation and Integration​

This is where things get interesting. With a governed platform in place, organizations can finally focus on making AI useful for real teams.

The focus shifts from:

"What can the model answer?"

to

"What can AI actually do inside the business?"

This is where integration architecture becomes critical. AI is only useful when it can interact with internal systems — APIs, databases, analytics platforms, CRMs, ticketing tools, and more.

That means:

• automating workflows • querying internal systems • generating operational reports • coordinating actions across tools

And this reveals the real bottleneck in enterprise AI adoption: integration.

AI Sovereignty, Strategic Priority​

For regulated industries — telecom, finance, healthcare, government — AI cannot operate as a black box.

Organizations need control over:

Compute Sovereignty​

Models must run on trusted infrastructure.

Sometimes that means private cloud. Sometimes internal clusters. Sometimes controlled hybrid environments.

Data Sovereignty​

Sensitive information must remain within enterprise boundaries.

This includes:

• customer data
• operational systems
• internal documentation
• proprietary analytics

Software Sovereignty​

Enterprises cannot depend entirely on a single vendor ecosystem.

They need modular architectures that allow them to:

• switch providers
• replace components
• maintain long-term platform control

Operational Sovereignty​

Every AI action must be:

• auditable
• observable
• governed

Without these capabilities, large organizations simply cannot deploy AI safely.

The Real Enterprise AI Architecture​

Many people imagine enterprise AI as a single platform.

The reality is very different.

Enterprise AI typically operates as a layered architecture.

A typical enterprise AI stack looks something like this.

Layer 1 — Business Users and Educated Consumers​

At the top of the stack are the people who actually need automation.

Some are not AI engineers, but they are the ones who will benefit most from AI-driven automation, and must educate themselves on how to use it effectively.

They are:

• operations teams
• product managers
• analysts
• support teams
• internal platform users

Their needs are practical.

They want to:

• automate repetitive work
• query internal systems
• generate reports
• coordinate workflows
• retrieve operational data

Most of them prefer natural language interactions rather than APIs.

Layer 2 — Applications and AI Interfaces​

Users interact with AI through various interfaces.

Examples include:

• enterprise chat assistants
• internal AI portals
• conversational automation tools
• developer AI environments

These interfaces translate human requests into structured actions.

But by themselves, they cannot automate anything.

They still need systems behind them.

Layer 3 — Agent and Workflow Engines​

This layer orchestrates automation.

Typical responsibilities include:

• coordinating multiple AI steps
• executing workflows
• managing task dependencies
• invoking tools
• connecting actions together

Examples of capabilities in this layer include:

• workflow builders
• automation orchestration
• agent coordination
• task routing

This layer turns a single AI response into a sequence of actions.

Layer 4 — Integration Layer​

This is where the real value appears.

AI becomes powerful only when it can interact with enterprise systems.

Examples include:

• internal APIs
• operational platforms
• databases
• analytics services
• CRM systems
• ticketing tools

Without integration, AI remains just a chatbot.

With integration, it becomes an operational automation engine.

This is where standardized integration protocols become extremely important.

Instead of every team writing custom AI integrations, organizations benefit from exposing internal capabilities through standardized interfaces that agents can discover and use safely.

Protocols designed for AI-native integrations are emerging as a key component of this architecture.

Layer 5 — AI Platform Infrastructure​

Below the integration layer sits the model infrastructure.

This includes:

• hosted models
• internal LLM clusters
• inference services
• evaluation pipelines

These platforms provide the raw AI capabilities.

But by themselves they do not solve business problems.

They simply power the higher layers.

Governance and Security — A Cross-Cutting Vertical​

Governance is not a separate layer. It is a vertical capability that spans the entire stack.

This includes:

• access monitoring
• model evaluation
• data privacy enforcement
• compliance auditing
• usage tracking
• AI policy enforcement

For regulated industries, governance is not optional.

It is the foundation that allows AI to exist in production.

Making AI Useful for Non-Technical Teams​

The technology itself is rarely the biggest obstacle.

The real challenge is usability., making AI useful for non-technical teams.

Enterprise AI systems must serve people who are not developers.

Typical users include:

• business analysts
• operations managers
• product teams
• support teams
• strategy groups

These users often ask for things like:

• "Pull customer metrics from three systems and generate a weekly report."
• "Find all tickets related to this issue and summarize root causes."
• "Create a workflow to notify teams when system health drops."

They do not want to write code.

They want AI to interact with enterprise systems safely on their behalf.

This is where agent-based workflows combined with standardized integrations become powerful.

Why Integration Becomes the Bottleneck​

In almost every enterprise AI deployment, the same pattern emerges.

The hardest problem is not the model.

It is connecting AI to internal systems safely.

Organizations quickly discover challenges like:

• inconsistent APIs
• authentication complexity
• governance restrictions
• data access limitations
• fragmented internal tooling

Each integration becomes a mini-project.

This slows down adoption dramatically.

To scale AI automation, enterprises need repeatable integration patterns.

The Rise of AI-Native Integration Protocols​

To address this problem, a new category of integration protocols is emerging.

These protocols are designed specifically for AI agents interacting with enterprise systems.

Instead of building custom integrations for every tool, organizations expose capabilities through standardized interfaces that agents can:

• discover automatically
• understand programmatically
• invoke safely

This approach creates several advantages.

Discoverability​

Agents can inspect available capabilities dynamically.

Standardized schemas​

Tools expose structured definitions of what they can do.

Reduced integration work​

Developers implement once instead of building custom connectors repeatedly.

Safer automation​

Governance controls can operate at the protocol level.

These characteristics make integration layers far more scalable.

In practice, many organizations are starting to implement architectures where AI agents interact with internal systems through standardized tool interfaces exposed via integration servers.

This pattern simplifies automation while maintaining enterprise security requirements.

The Next Evolution: Agent Ecosystems​

As enterprise AI platforms mature, another pattern is becoming clear.

AI systems are evolving from chat interfaces into agent ecosystems.

Instead of a single assistant answering questions, organizations are deploying networks of agents that can:

• execute workflows
• retrieve information
• coordinate systems
• trigger automations
• generate insights

These agents rely heavily on integration layers that expose enterprise capabilities in a consistent way.

Without this layer, agents cannot operate effectively.

With it, organizations unlock entirely new automation capabilities.

Practical Guidelines for Enterprise AI Adoption​

Based on what many organizations are experiencing today, several guidelines are emerging.

1. Governance must come first​

AI cannot scale without security and compliance frameworks.

Governance must be built into the architecture from the beginning.

2. Open experimentation accelerates learning​

Early experimentation with open tools helps teams understand real use cases quickly.

Controlled environments allow safe exploration.

3. Integration architecture determines success​

AI becomes useful only when it connects to enterprise systems.

Organizations should design integration layers intentionally.

4. Modular architectures outperform monolithic platforms​

Successful AI environments combine multiple specialized tools rather than relying on a single vendor solution.

5. Agent workflows unlock real automation​

The future of enterprise AI is not chatbots.

It is AI-driven operational workflows.

The Quiet Cornerstone of Enterprise AI​

If there is one architectural insight becoming increasingly clear, it is this:

The integration layer determines whether enterprise AI succeeds or fails.

Without structured integration patterns, AI systems remain isolated assistants.

With the right integration architecture, they become automation engines capable of transforming enterprise operations.

Protocols designed for AI-native integrations are rapidly becoming the cornerstone of this layer.

They provide a standardized way to expose enterprise systems to AI agents safely, enabling scalable automation without rewriting integrations repeatedly.

The Path Forward​

Over the next few years, enterprise AI platforms will likely converge toward a common architecture:

• governed model infrastructure
• modular orchestration layers
• AI-native integration protocols
• agent-driven workflows
• business-accessible automation interfaces

The organizations that embrace this architecture early will move faster.

Not because they have better models.

But because they have built the platform that allows AI to operate safely across the enterprise.

And once that platform exists, automation stops being an experiment.

It becomes a new operating model for the business.

FAQ: Enterprise AI automation and architecture​

Q: What is enterprise AI automation?
A: Enterprise AI automation is the use of AI systems, agents, and workflows to execute business tasks across internal tools, data sources, and operational systems in a governed and secure way.

Q: Why are enterprises moving from AI experimentation to AI operations?
A: Once early pilots show value, organizations need security, compliance, observability, and repeatable delivery. The focus shifts from trying AI tools to building a governed operating platform.

Q: What does a typical enterprise AI architecture look like?
A: It usually includes business users, AI interfaces, agent and workflow engines, an integration layer connected to enterprise systems, and AI platform infrastructure. Governance and security span all of these as a cross-cutting vertical.

Q: Why is governance not optional in enterprise AI?
A: Enterprise AI must be auditable, observable, privacy-aware, and compliant before it can be trusted in production, especially in regulated industries such as finance, healthcare, telecom, and government.

Q: What is AI sovereignty in enterprise AI?
A: AI sovereignty means retaining control over compute, data, software choices, and operations so the enterprise can run AI in a trusted, governable, and vendor-resilient way.

Q: Why does the integration layer determine enterprise AI success?
A: AI creates business value only when it can safely interact with internal systems. Without integration, it remains a chatbot. With integration, it becomes an operational automation engine.

Q: What is the biggest challenge in enterprise AI adoption?
A: In most organizations, the biggest challenge is not the model. It is making AI useful for non-technical teams while connecting it safely to enterprise systems through repeatable integration patterns.

Q: What are AI-native integration protocols?
A: They are standardized ways for AI agents to discover, understand, and invoke enterprise capabilities safely, reducing custom integration work and making automation more scalable.

Q: What is the future of enterprise AI platforms?
A: The architecture is converging toward governed model infrastructure, modular orchestration, AI-native integration protocols, agent-driven workflows, and business-accessible automation interfaces.

For decades, the IDE was the center of software development. Everything revolved around it: edit → run → debug → commit.

Now something else is emerging.

A control plane for AI agents.

The Quiet Shift: From AI Assistants to AI Teams​

For the past few years, most AI coding tools followed a simple pattern:

Developer + AI assistant

Think of tools like Copilot or inline AI suggestions.

You write the code. The AI helps.

But the Codex app introduces a different model entirely.

Instead of one assistant, you manage multiple AI agents working in parallel.

Example workflow:

• Agent 1 implements a new feature
• Agent 2 writes unit tests
• Agent 3 refactors the database layer
• Agent 4 reviews the changes

All happening simultaneously on the same codebase.

Each agent runs in its own isolated environment, often using Git worktrees to avoid conflicts.

Your job is no longer to write every line.

Your job becomes orchestrating the work.

The Codex App: A Command Center for Software Development​

OpenAI describes the Codex app as a command center for agentic coding where multiple tasks run across projects in parallel.

Instead of working file-by-file, developers can:

• spin up agents for tasks
• monitor progress across projects
• review diffs generated by agents
• approve or reject changes
• automate long-running development tasks

The system organizes agents into threads and projects so you can track work across many workflows at once.

In other words:

You manage software production, not just code editing.

Why This Matters More Than It Looks​

The real disruption isn’t the tool.

It’s the change in the developer role.

Traditionally:

Human writes code
AI helps with autocomplete

Now:

Human orchestrates agents
Agents write most of the code

The human moves up a level of abstraction.

From implementation → coordination.

This is similar to how DevOps changed operations:

• admins stopped managing individual servers
• they orchestrated infrastructure with automation

Now developers may stop writing every line and start orchestrating intelligent workers.

The IDE Is Becoming Secondary​

One of the most interesting signals from early Codex users is that some projects were completed without opening an IDE at all.

The workflow looked like:

1. Define tasks
2. Launch agents
3. Review diffs
4. Merge results

The IDE becomes a verification environment, not the main workspace.

Or as some engineers are starting to describe it:

The IDE is where code gets reviewed, not where it gets written.

A New Category of Dev Tools Is Emerging

We are entering a new category of developer infrastructure:

Agent orchestration platforms.

Think about the layers forming:

Layer 1 — Models​

LLMs capable of coding and reasoning.

Layer 2 — Agents​

Autonomous systems executing tasks.

Layer 3 — Orchestration​

Tools coordinating many agents together.

Layer 4 — Interfaces​

Control panels for supervising the system.

The Codex desktop app sits in layer 3 and 4.

And that’s where the biggest opportunities may appear.

Why This Matters for the AI Ecosystem

If agents become the primary actors in development, something else becomes critical:

Standardized ways for agents to access tools, APIs, and data.

Agents don’t just write code.

They need to:

• query APIs
• access services
• interact with infrastructure
• call tools
• coordinate with other agents

This means the future dev stack likely needs:

• agent-native APIs
• standardized tool interfaces
• structured orchestration protocols

Without that, every agent ecosystem becomes fragmented.

The Bigger Pattern: Agent Operating Systems

What we’re starting to see is the early version of something bigger:

Agent operating systems.

Where the developer:

• assigns goals
• delegates tasks
• supervises execution

And the agents perform the work.

This pattern is emerging across tools:

• AI coding agents
• research agents
• automation agents
• DevOps agents

The orchestration layer becomes the new control plane of software development.

The Role of Developers in the Agent Era

The developer role is evolving.

Not disappearing.

But changing.

Instead of:

👨‍💻 writing code all day

Developers increasingly become:

🧑‍✈️ supervisors of intelligent systems

They define architecture, intent, and constraints.

The agents implement.

The Next Generation of Developer Tools

If this trajectory continues, developer tooling may look very different in the next few years.

Instead of:

Editor
Terminal
Debugger

We may see tools centered around:

Agent dashboards
Task orchestration
Workflow supervision
Execution logs
Diff approval systems

Less editing.

More orchestration.

The Bigger Question

The real question now isn’t whether AI will write code.

That’s already happening.

The real question is:

Who controls the agents?

Because once agents become the workers of software development, the most important infrastructure becomes:

• orchestration layers
• agent ecosystems
• tool interoperability

And that’s where the next generation of developer platforms will compete.

Final Thought

We are moving from:

👨‍💻 developer + AI assistant

to

🧑‍✈️ developer supervising a team of AI agents.

And if that continues, the tools we use will change accordingly.

The next generation of dev tooling will likely look less like editors…

and more like control panels for agent workflows.

Traditional APIs were built for humans and frontends. AI agents change the equation.

And this is where most teams misunderstand Model Context Protocol (MCP).

They think MCP solves integration complexity automatically.

It doesn't.

It standardizes discovery and interaction — but implementation discipline still matters.

Let's break this down clearly.

Traditional APIs vs MCP: What Actually Changes?​

How do traditional APIs work?​

Traditional REST APIs require every client to:

• Read documentation
• Implement authentication flows
• Format requests correctly
• Handle errors manually
• Track version changes
• Maintain compatibility

If you have:

• 1 API
• 5 clients
• 3 authentication methods
• 2 versions

You don't have 1 integration problem.

You have 30.

Now replace "clients" with:

• ChatGPT connectors
• Claude Desktop
• Internal agents
• Workflow bots
• Edge agents
• Telco network AI
• Enterprise copilots

That model does not scale.

What Is Model Context Protocol (MCP)?​

MCP changes the integration contract.

Instead of hardcoded REST calls, it provides:

• Runtime tool discovery
• Schema introspection
• Agent-native communication
• Structured inputs and outputs
• Standard interaction patterns

Well, at least that's the promise, and what HAPI MCP delivers - without the fragmentation, without coding, and with enterprise-grade discipline.

Any MCP-compatible agent can:

1. Connect to a remote MCP endpoint
2. Inspect available tools
3. Understand their schema
4. Execute them without custom coding

This is plug-and-play for agents.

But here's the part most people miss.

The Hidden Problem: MCP Server Fragmentation​

MCP standardizes how agents talk to servers.

It does not standardize how servers are built internally.

Two teams can implement an MCP server for the same API and end up with:

• Different auth logic
• Different error handling
• Different retry policies
• Different token exchange flows
• Different schema interpretations
• Duplicated backend logic
• Security inconsistencies

Now you have a new problem:

MCP interface standardization + backend chaos.

This is where architecture discipline matters.

MCP servers are not just wrappers.

They are distributed system components.

Why MCP Servers Must Be Treated as Distributed Systems​

An MCP Server:

• Runs independently
• Calls upstream APIs
• Handles authentication delegation
• Translates schemas
• Applies business logic
• Returns structured responses

That is a system.

Not a simple adapter.

If you let each team build MCP servers differently:

• Security posture varies
• OAuth flows break inconsistently
• Error semantics change
• Agent behavior becomes unpredictable
• Maintenance cost explodes

In enterprise environments, this is unacceptable.

This is exactly why HAPI MCP exists.

What is the best way to fix this problem?​

HAPI MCP solves the missing layer.

It standardizes the server implementation engine, not just the protocol interface.

Instead of:

"Every team builds its own MCP server logic"

You get:

"Deploy MCP servers from OpenAPI specs — the engine handles the rest."

Let's analyze why that matters.

1️⃣ Authentication Is Centralized, Not Re-Invented​

One of the hardest problems in MCP ecosystems is OAuth.

Especially 3-legged flows:

• User → Client (ChatGPT, Claude)
• Authorization Server (LinkedIn, Strava, etc.)
• Resource Server

Without discipline, each MCP server re-implements:

• PKCE
• Token exchange
• Bearer forwarding
• Refresh token handling
• Error propagation

This is standard, HAPI MCP provides a secure, consistent implementation for all servers.

Authentication is:

• Consistent
• Repeatable
• Delegated properly
• Secure by design

You don't rewrite OAuth per server.

You deploy.

2️⃣ Error Handling Becomes Deterministic​

Agents rely on predictable behavior.

If one MCP server returns:

{ "error": "not_found" }

And another returns:

{ "message": "Missing resource" }

Your agent logic breaks.

HAPI MCP ensures:

• Consistent error semantics
• Standardized response shapes
• Uniform status mapping

This reduces agent hallucination and workflow failures.

3️⃣ No Business Logic Duplication​

One of the silent architectural sins:

Teams duplicating logic inside MCP servers that already exists upstream.

For example:

• Re-validating data unnecessarily
• Re-implementing filtering
• Duplicating rate limiting
• Recreating transformation layers

HAPI MCP treats the server as:

• A standardized orchestration layer
• Not a logic duplication layer

It respects upstream authority.

This keeps systems clean.

4️⃣ Contract Changes Don't Break Everything​

Traditional APIs break clients when contracts change.

MCP allows runtime introspection.

But if your server implementation is inconsistent:

You still break behavior.

HAPI MCP enforces:

• Schema alignment with OpenAPI
• Predictable tool exposure
• Controlled updates
• Versioning discipline

This is critical for enterprise.

5️⃣ Enterprise Governance Is Built-In​

CIOs and platform teams ask:

• Who deployed this MCP server?
• Which auth flow is used?
• Where are tokens stored?
• How is auditing done?
• Can we run this on-prem?
• What about airgapped environments?

HAPI MCP answers:

• Deployable on-prem or cloud
• Same engine everywhere
• Standard behavior
• Governance-ready
• Compatible with regulated environments

This is not "just another wrapper tool."

This is infrastructure.

Business Impact: Why This Matters

Let's translate technically into business language.

Without Standardized MCP Servers​

• Higher integration costs
• Inconsistent AI results
• Security risk
• Maintenance overhead
• Vendor lock chaos
• Harder audits

With HAPI MCP​

• Faster AI rollout
• Lower integration cost
• Predictable agent behavior
• Enterprise-ready governance
• Reduced duplication
• AI strategy that scales

Time saved = money saved Consistency = risk reduction Standardization = long-term leverage

Frequently Asked Questions​

What problem does MCP solve?

MCP standardizes how AI agents discover and interact with tools at runtime, removing hardcoded integrations.

Is MCP enough by itself?

No. MCP defines the interaction protocol, but it does not standardize server implementation discipline.

Why do MCP implementations vary?

Because teams interpret authentication, error handling, and schema translation differently unless an engine enforces consistency.

How does HAPI MCP improve MCP servers?

HAPI MCP provides a standardized execution engine that ensures:

• Unified authentication handling
• Predictable error semantics for all servers
• Schema consistency
• Enterprise-grade governance

Can HAPI MCP run on-premise?

Yes. It supports cloud and on-prem deployments, including regulated and partially disconnected environments.

Does HAPI duplicate backend logic?

No. It acts as a standardized orchestration layer and respects upstream APIs as the source of truth.

Strategic Recommendation: Treat MCP as Infrastructure​

If you are building:

• Enterprise AI copilots
• Telco network APIs
• Platform team AI integrations
• Agent ecosystems
• Multi-provider connectors

You cannot treat MCP servers as lightweight wrappers.

You must treat them as:

• Standardized infrastructure components
• Governed distributed systems
• Secure orchestration layers

That is the HAPI MCP philosophy.

Final Thought​

MCP is the future of agent-native integration.

But:

MCP without implementation discipline becomes fragmentation.

HAPI MCP is not about replacing the protocol.

It is about making it reliable.

If your goal is:

• AI at scale
• Enterprise governance
• Predictable agent behavior
• No duplicated backend chaos

Then the path is clear.

Standardize the engine.

Deploy with confidence.

Build once.

Scale everywhere.

That's the HAPI MCP way.

If you deploy an MCP Server manually from scratch, OAuth becomes a project.

If you deploy an MCP Server using HAPI MCP from an OpenAPI specification, OAuth becomes a configuration option.

That's a little big difference.

In the AI era, security is product strategy.

Every serious MCP implementation will eventually face the same question:

How do we let AI clients like ChatGPT or Claude access user data securely — without storing passwords or reinventing OAuth every time?

The answer isn't new. It's not exotic. It's not experimental.

It's 3-Legged OAuth2 — Authorization Code Flow.

And inside MCP Apps, it becomes even more interesting.

Let's break it down clearly, practically, and from an enterprise-ready perspective.

What Is 3-Legged OAuth2 (Authorization Code Flow)?​

3-Legged OAuth2 is the industry-standard way for a third-party application to access user data without the user sharing their password.

The “three legs” represent three actors:

1. Resource Owner → The User
2. Client → The Application (e.g., ChatGPT, Claude Desktop)
3. Authorization Server → The Identity Provider (e.g., LinkedIn, Facebook, Google)

The flow works like this:

1. User clicks “Connect LinkedIn.”
2. The client redirects the user to LinkedIn.
3. The user logs in directly at LinkedIn.
4. LinkedIn asks: “Do you allow this app to access your data?”
5. If approved, LinkedIn sends an authorization code back to the client.
6. The client exchanges that code for an access token.
7. The client can now call APIs securely on behalf of the user.

No password sharing. No credential storage. No trust leaks.

This pattern is standardized and widely adopted across the internet.

How 3-Legged OAuth Works in MCP Apps​

Now here's where things get interesting.

In a traditional web app, the client directly calls the resource server.

In MCP Apps, the architecture introduces a clean separation.

Instead of three actors, you now have four parties involved:

1. Resource Owner → The User
2. OAuth Client → ChatGPT, Claude Desktop, or another MCP Client
3. Authorization Server → LinkedIn, Strava, Facebook, etc.
4. Resource Server → The MCP Server

Let's visualize this properly.

🔐 MCP OAuth Applied​

Let's see this with a practical example, where a user wants to connect their LinkedIn profile to ChatGPT via an MCP Server.

Step-by-Step MCP OAuth Flow​

1. User tells ChatGPT:

   “Get my LinkedIn profile.”

2. ChatGPT (OAuth Client) calls the MCP Server, which initiates the OAuth flow when not authenticated.
3. The MCP Server tries to call LinkedIn APIs but gets a 401 Unauthorized response.
4. The MCP Server responds to ChatGPT, indicating that it needs to authenticate via OAuth and provides discovery information about the OAuth endpoints.
5. ChatGPT (OAuth Client) initiates the Authorization Code flow.
6. User is redirected to LinkedIn (Authorization Server).
7. User authenticates and grants consent.
8. LinkedIn issues an authorization code.
9. ChatGPT passes the authorization code back to the MCP Server.
10. The MCP Server handles the token exchange.
11. MCP Server calls LinkedIn APIs with the proper access token.
12. The result flows back: LinkedIn → MCP Server → ChatGPT → User.

What changed?

👉 The MCP Server acts as the secure resource boundary.
👉 The client never sees or stores upstream provider tokens.
👉 The system remains compliant with OAuth standards.

This is critical for enterprise use.

You don't need to build custom auth logic for every provider, try HAPI MCP CLI, or runMCP Server in the cloud from your OpenAPI spec, and the OAuth flow is handled for you.

Why This Pattern Matters for AI Systems​

In AI agent ecosystems, we need:

• Delegated access
• Revocable permissions
• Token isolation
• Standard compliance
• No password storage
• Clear separation of responsibility

3-Legged OAuth delivers exactly that.

And because it is standardized, it becomes:

• Repeatable
• Auditable
• Secure by design
• Familiar to security teams

That last point is important.

When you walk into an enterprise environment, the fastest way to get rejected is by inventing custom authentication mechanisms.

Security teams trust OAuth2 Authorization Code Flow.

The Problem Most Developers Face​

Here's the friction.

If you build MCP servers manually, you must:

• Implement OAuth redirect endpoints
• Handle authorization code exchange
• Store and refresh access tokens
• Manage token expiration
• Secure client secrets
• Handle PKCE (Proof Key for Code Exchange)
• Deal with multiple providers
• Maintain compliance

That is a lot of surface area.

And every provider behaves slightly differently.

Multiply that across:

• LinkedIn
• Strava
• Facebook
• Google
• Custom enterprise identity providers

Now it becomes operational debt.

The MCP Specification Already Solved This​

The Model Context Protocol defines:

• How MCP Clients interact with MCP Servers
• How authentication should be handled
• How standardized discovery endpoints work
• How secure delegation must operate

That means:

OAuth in MCP is not an afterthought. It is part of the protocol design.

This is powerful.

It makes OAuth not just possible — but predictable.

Where HAPI MCP Changes the Game​

Now let's talk about implementation reality.

If you deploy an MCP Server manually from scratch, OAuth becomes a project.

If you deploy an MCP Server using HAPI MCP from an OpenAPI specification, OAuth becomes configuration.

That's the difference.

HAPI MCP includes:

• Built-in OAuth flow handling
• Authorization Code + PKCE support
• Token exchange management
• Refresh token lifecycle handling
• Secure token isolation
• Standards-compliant MCP endpoints

You don't write the OAuth engine.

You define your OpenAPI spec.

You deploy.

The rest is handled.

Bonus: For Greenfield API providers, you can design your API with OAuth in mind from the start, HAPI MCP CLI will generate the necessary scaffolding for you to focus on your core API logic.

What This Means for Builders​

Let's answer the most common questions clearly.

❓ Do I need to implement OAuth manually for every MCP App?

No.

If you deploy via HAPI MCP, the OAuth handling is built-in.

You configure providers. You deploy your MCP server. The flow works.

❓ Does ChatGPT or Claude need custom OAuth logic?

No.

They act as OAuth clients following the standard Authorization Code Flow.

The protocol alignment makes this repeatable.

❓ Is this secure enough for enterprise use?

Yes — because:

• It follows OAuth2 Authorization Code Flow
• It supports PKCE
• Tokens are isolated
• Passwords are never shared
• Access can be revoked at the provider level

Security teams understand this pattern.

That reduces friction during procurement.

❓ What about compliance and auditing?

Because the flow is standardized:

• Logs can be centralized
• Access tokens are time-bound
• Consent is explicit
• Revocation is supported

This aligns with regulated industries.

Especially important in:

• Telco
• Banking
• Healthcare
• Government

Business Impact: Why This Matters​

Let's translate this from a technical perspective to business language.

🚀 Faster Time to Market

No custom OAuth implementation per provider.

💰 Lower Engineering Cost

No repeated auth boilerplate across MCP Apps.

🛡️ Reduced Security Risk

Standard, battle-tested authentication pattern.

🔁 Repeatable Deployment Model

Same OAuth behavior across all MCP servers.

📈 Enterprise Sales Enablement

Security teams approve faster when OAuth2 is used correctly.

Authentication is not a feature.

It's an approval accelerator.

A Real Example

Imagine you build:

• A Strava MCP
• A LinkedIn MCP
• A Valorant MCP

Without standardization, each becomes its own OAuth project.

With HAPI MCP:

1. Define the OpenAPI spec.
2. Configure OAuth provider.
3. Deploy MCP server.
4. Connect from ChatGPT, Claude, or any compliant client.

Done.

Same pattern. Same security. Same behavior.

Repeatable.

The Hidden Strategic Advantage

AI systems are moving toward:

• Agentic workflows
• Tool chaining
• Delegated data access
• Multi-provider integrations

If authentication is inconsistent, your agent ecosystem collapses.

If authentication is standardized, your system scales.

3-Legged OAuth2 is not optional.

It's foundational infrastructure.

Final Takeaway

3-Legged OAuth2 (Authorization Code Flow) is the secure bridge between:

• AI clients (ChatGPT, Claude)
• User data providers (LinkedIn, Strava, etc.)
• MCP Servers
• End users

It is standardized. It is repeatable. It is enterprise-approved.

And when deployed via HAPI MCP, it becomes automatic.

No password handling. No custom auth engine per server. No authentication chaos.

Just deploy your MCP server from your OpenAPI spec.

OAuth is handled.

Secure by default. Composable by design. Ready for AI.

If you're building MCP-native systems, the real question is not:

“Should I implement OAuth?”

It's:

“How fast can I standardize it across every MCP I deploy?”

Because the future of AI integration belongs to the teams that treat authentication as infrastructure — not an afterthought.

Be the team that gets it right from day one. Be HAPI, and Go Rebels! ✊🏼

FAQ: 3-Legged OAuth2 in MCP Apps​

Q: What is 3-Legged OAuth2 in MCP apps?
A: It is the OAuth2 Authorization Code Flow where users grant consent to AI clients like ChatGPT or Claude, and MCP servers access APIs securely without user passwords.

Q: Why is Authorization Code + PKCE recommended for MCP?
A: Authorization Code + PKCE reduces token interception risks and is the standard secure pattern for delegated access in modern AI and enterprise applications.

Q: Do ChatGPT and Claude need custom OAuth logic for each provider?
A: No. They operate as OAuth clients using standardized flow mechanics, while the MCP server manages provider-specific token exchange and secure access.

Q: Does the MCP server store user passwords?
A: No. Users authenticate directly with the identity provider, and the system works with scoped tokens and consent, not raw credentials.

Q: Is this pattern enterprise-ready for compliance and audits?
A: Yes. OAuth2 with explicit consent, revocation, token lifecycles, and centralized logging aligns with common enterprise security and audit expectations.

Q: What problem does HAPI MCP solve in OAuth implementation?
A: HAPI MCP turns OAuth from custom engineering work into configuration by handling authorization flow, token exchange, refresh lifecycle, and MCP-compliant endpoints.

Q: Can I use the same OAuth model across LinkedIn, Strava, and Google MCP servers?
A: Yes. The core Authorization Code pattern stays consistent across providers, which makes MCP deployments repeatable and easier to scale.

Q: What is the business impact of standardized OAuth in MCP?
A: It speeds up delivery, lowers engineering overhead, reduces security risk, and improves enterprise adoption by using a trusted authentication standard.

MCP enthusiasm is real. Enterprise constraints are also real.

Security. Auth. Compliance. Deployment pipelines. Audit logs. None of that disappears because we’re excited about agents.

The hard truth? Most teams building MCP servers today are moving fast — and quietly laying the foundation for the next generation of technical debt.

This is where the conversation needs to change.

This is where HAPI MCP enters.

What Is MCP—and Why Enterprises Are Paying Attention?​

Model Context Protocol (MCP) is emerging as the standard way to connect AI models to tools, APIs, and systems in a structured, secure way.

In simple terms:

MCP lets AI safely call your APIs.

For enterprises, that’s powerful. It means:

• AI agents interacting with internal systems
• Chat interfaces becoming operational tools
• Automation powered by real business APIs

But here’s the catch:

The excitement around MCP is developer-driven. The constraints around adoption are enterprise-driven.

If you ignore the second, you create invisible risk.

The Real Villains in MCP Adoption​

🚫 Reinventing Infrastructure​

Most teams building MCP servers today are reimplementing OAuth.

It works... Until you need:

• Token rotation
• Scope management
• Audit logging
• Cross-environment policies
• Compliance validation

Now your “quick integration” becomes a parallel security stack.

That’s not innovation. That’s duplication.

🚫 Breaking Existing Deployment Models​

Some MCP implementations assume:

• New deployment pipelines
• Separate AI infrastructure
• Special server environments

That might work in a startup lab.

In enterprise environments? That’s friction. And friction kills adoption.

🚫 Creating AI-Specific Silos​

When AI integrations live outside your existing architecture, you create:

• Separate auth
• Separate logging
• Separate deployment
• Separate ownership
• Separate codebases - and therefore separate maintenance

Silos become permanent. They become “that AI thing” that no one wants to touch.

🚫 Invisible Technical Debt​

This is the dangerous one.

AI pilots often “work.” But they bypass enterprise guardrails to move fast.

Months later, someone asks:

• Can we audit this?
• Can we scale this?
• Can we support 10 teams using it?
• Can we pass a security review?

If the answer is “not without rework,” you’ve created invisible debt.

🚫 AI Pilots That Can’t Scale​

The biggest failure pattern:

1. Cool demo
2. Executive excitement
3. Security review
4. Architectural rethink
5. Restart from scratch

That’s not speed. That’s waste.

The Shift: You Don’t Need a New AI Infrastructure​

Here’s the mindset change:

You don’t need a new auth system for AI. You don’t need a new deployment model for MCP. You don’t need an AI silo.

You need MCP that respects your existing stack.

That’s the difference.

Introducing HAPI MCP: The Stack That Respects Your Stack​

HAPI MCP is designed around one principle:

Adopt MCP without creating technical debt.

Instead of replacing your architecture, HAPI:

• Plugs into your existing authentication
• Aligns with your current deployment pipelines
• Works within your compliance model
• Avoids creating AI-specific infrastructure

You move fast — without breaking what already works.

How HAPI MCP Eliminates Technical Debt​

The traditional approach involves reimplementing OAuth, duplicating code for token management, and building custom audit logging. This works temporarily—until you need to rotate tokens, manage scopes, or scale across environments.

Suddenly, you're maintaining a custom security infrastructure.

With HAPI MCP, you don’t need a new auth system or logic for AI.

HAPI MCP plugs directly into your existing auth and deployment flow.

Which means:

• Faster shipping
• Lower security risk
• Real enterprise adoption
• Reduced long-term maintenance cost

That’s the difference between a demo and a platform.

HAPI MCP in an Enterprise Context​

HAPI integrates with what you already run.

Not what you wish you ran. Not what a greenfield startup runs.

Your stack.

This includes:

• Existing OAuth or OIDC providers
• Existing API gateways
• Existing deployment pipelines
• Existing cloud or on-prem models

No new auth layer. No new deployment model. No AI silo.

Just MCP layered cleanly into your architecture.

Why This Matters​

Ship MCP Without Rewriting Everything​

The most common blocker for MCP adoption is the fear of extensive rework. HAPI eliminates this by enabling you to:

Use MCP without touching your existing auth flow.

You focus on filtering and exposing APIs to AI—not reinventing security. HAPI handles the integration alignment, resulting in less friction, fewer security escalations, and faster delivery.

Avoid Parallel AI Infrastructure​

Building a separate MCP server with its own auth and deployment creates a parallel system that’s invisible to your security and platform teams. This introduces shadow infrastructure, bypasses compliance, and creates long-term maintenance costs.

The key concern isn’t “Can we build this?”

It’s:

Are we creating infrastructure we’ll regret in 18 months?

HAPI ensures:

• AI integrations sit inside your governance model
• No shadow infrastructure
• No compliance bypass
• No parallel auth systems

Adopt MCP without creating architectural debt.

From Pilot to Production​

Is it possible to build a quick MCP pilot that scales to 20 production use cases?

The risk isn’t failure. The risk is rework.

When MCP is built in isolation, scaling requires redesign.

With HAPI:

• Pilot → Production is incremental
• No architectural rewrite
• Faster path to measurable ROI

You move from experimentation to operational AI — safely.

MCP Enthusiasm Is High. Enterprise Constraints Are Real.​

Let’s address the tension directly.

Yes, MCP unlocks:

• Agent-driven workflows
• AI-powered automation
• Tool orchestration
• Intelligent operations

But enterprises cannot ignore:

• Security models
• Compliance frameworks
• Deployment standards
• Audit requirements

The organizations that win will not be the fastest experimenters.

They will be the fastest safe adopters.

FAQ: Adopting MCP Without Technical Debt​

What causes technical debt in MCP implementations?​

• Reimplementing authentication
• Creating AI-specific infrastructure
• Bypassing existing deployment models
• Ignoring compliance and audit alignment

Can MCP integrate with existing OAuth systems?​

Yes. A properly designed MCP stack should plug into your current OAuth/OIDC provider instead of replacing it for one-off AI integrations.

How do you scale MCP from pilot to production?​

By ensuring:

• Zero code duplication
• Auth reuse
• Deployment reuse
• Governance alignment
• Observability integration

If those are separate, scaling requires rework.

Why do AI pilots fail to scale?​

Because they’re built outside enterprise architecture guardrails.

When security and platform teams get involved, redesign becomes mandatory.

The Business Case: Speed Without Risk​

Let’s translate this into enterprise language.

Cost Avoid duplicating infrastructure and future rework.

Risk Align AI integrations with existing governance from day one.

Time-to-Market Ship MCP integrations in hours — not months of security negotiation.

Scalability Move from 1 pilot to 20 production use cases without architectural reset.

That’s how you move fast — without creating debt.

The Bottom Line​

You can move fast and safely.

You can ship MCP integrations in hours.

You can avoid rewriting auth, deployments, or workflows.

You can adopt MCP without creating a parallel AI infrastructure.

But only if your MCP stack respects your existing stack.

That’s the shift.

That’s the relief.

And that’s why HAPI MCP is positioned not as “another MCP tool” — but as the enterprise-ready stack for sustainable AI adoption.

Because the real goal isn’t to launch an AI demo.

It’s to build AI capability without architectural regret.

Now what?

To make your tools truly useful, they need to be accessible—whether by your team, your organization, or the global community of AI developers. This guide covers how to take your MCP server from localhost to production, and how to register it so it can be discovered.

The Connectivity Challenge​

The Model Context Protocol (MCP) is revolutionizing how AI models connect to external tools. However, a protocol is only as good as its reach. If your server only lives on your laptop, its potential is limited.

Developers face several hurdles:

1. Deployment Fatigue: Configuring Docker, k8s, or serverless functions for every new tool.
2. Discovery: How do AI agents find your tool?
3. Security: Exposing internal APIs to LLMs safely.

The Solution: Build Once, Deploy Everywhere​

The philosophy behind the HAPI ecosystem is simple: Standardization. whether you are running a simple script or a complex enterprise API, the interface should be consistent.

We support three primary deployment modes:

1. Local: For dev/test loops. (HAPI MCP Servers are remote-only, even when local.)
2. Containerized (Docker): For standard enterprise hosting.
3. Edge (Cloudflare Workers): For low-latency, global availability.

⚡ Quick Start: 3 Ways to Run​

Option A — Run Locally with HAPI CLI​

The fastest way to test. Great for development loops.

1. Install HAPI

   # Linux / macOS
   curl -fsSL https://get.mcp.com.ai/hapi.sh | bash
   
   # Windows (PowerShell)
   iwr -useb https://get.mcp.com.ai/hapi.ps1 | iex
   

2. Serve your MCP

   hapi serve pet-store \
     --port 3030 \
     --headless \
     --url https://petstore.swagger.io/v2 \
     --openapi https://petstore.swagger.io/v2/swagger.json
   

3. Verify it works With a quick curl command, you can verify your server is speaking MCP:

   curl -s -X POST http://localhost:3030/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
   

Option B — Run with Docker​

Perfect for self-hosting on a VPS or within your internal Kubernetes cluster.

docker run -p 3030:3030 \
  -v ~/.hapi:/app/.hapi \
  hapimcp/hapi-cli:latest \
  serve pet-store \
  --port 3030 \
  --headless \
  --url https://api.my-service.com

Option C — Deploy to Cloudflare Workers​

Go global instantly. This method deploys your MCP server to the edge, making it incredibly fast for distributed AI agents.

hapi login
hapi deploy \
  --name mcp-pet-store \
  --project pet-store \
  --openapi ./specs/petstore.json \
  --url https://api.my-service.com

🌍 Registering with the MCP Registry​

Deployment is only half the battle. Discovery is the other.

To make your server discoverable by standard generic clients:

1. Prepare Metadata: Ensure you have a clear name, description, and valid OpenAPI spec.
2. Submit to Registry: Follow the steps in the official MCP registry documentation or the summary in our MCP Servers GitHub repo.
3. Automate (Coming Soon - vote this feature!): We are considering hapi register to automate this flow directly from the HAPI CLI.

🔐 Security First​

When moving from local to remote, security models change.

• Authentication: Always fully authenticate requests to your backend. HAPI manage OAuth flows defined in your OpenAPI spec.
• Isolation: Use environment variables for API keys; never hardcode them.
• Monitoring: Log your MCP tool invocations. Knowing what the AI is asking your tools is crucial for debugging and auditing.

Frequently Asked Questions​

Ready to deploy? Check out the HAPI CLI Documentation and get started today.

Not because they reason better, but because they act without boundaries.

Agent Skills exist to fix that.

They define what an agent can do, how it can do it, and under what constraints — in a way machines can enforce, not humans hope for.

What Is an Agent Skill? (Simple Definition)​

An Agent Skill is a structured, declarative capability that an AI agent can invoke to perform an action through a system.

• Not a suggestion — it's enforceable
• Not a prompt — it's structured
• Not open-ended — it has boundaries

A capability with rules that machines enforce.

Why Agent Skills Became Inevitable​

Prompt-driven agents don't scale beyond experimentation.

At small scale, prompts feel powerful and flexible.
At enterprise scale, they create unacceptable risk:

The Prompt Problem​

• 🚨 Agents hallucinate actions that don't exist
• 🔓 Permissions are implicit and unenforceable
• 🌫️ Execution paths are opaque and unpredictable
• ❌ Security reviews are nearly impossible
• 📝 Audits have no structured artifacts to examine

The Industry Response​

Skills emerged because enterprises demanded control.

The industry responded with:

• Shared Skill specifications (not vendor-locked)
• Standard schemas for cross-platform compatibility
• Public registries and catalogs for discovery
• Installation, versioning, and tracking mechanisms
• Observability and governance tooling

Skills are now appearing everywhere — AI frameworks, runtime environments, marketplaces, and enterprise dashboards.

Skills vs Prompts: The Real Difference​

Understanding this distinction is critical for building production-grade AI systems.

The Core Distinction​

Prompts decide what to try.
Skills define what is allowed.

Prompts ask. Skills authorize.

Skills vs Tools vs Workflows: Clearing the Confusion​

These terms are often used interchangeably. They shouldn't be.

The Hierarchy of Agent Capabilities​

🔧 Tools are low-level primitives

• Individual functions or API calls
• Example: get_user(id) or send_email(to, subject, body)
• No decision-making, just execution

🔄 Workflows are pre-wired sequences

• Fixed chains of predetermined steps
• Example: "When form submitted → validate → save → send email"
• No agent choice, just automation

🎯 Skills are bounded capabilities that agents choose to invoke

• Define what CAN be done and under what constraints
• Example: "Search customer database (read-only, max 100 results, audit logged)"
• Agent decides WHEN to use them based on context

Why This Matters​

Skills sit at the decision boundary between reasoning and execution.

• The model reasons about what to do
• The Skill authorizes what can be done
• The tool executes the actual action

This separation is what makes AI agents governable.

Agent Skills Are Becoming a Standard Layer​

What started as framework-specific abstractions is now converging into industry standards.

The Standardization Wave​

Foundation:

• Shared specifications (like MCP)
• Common schemas and interfaces
• Cross-platform compatibility

Distribution:

• Public registries and catalogs
• Installation and discovery tooling
• Version management

Operations:

• Usage tracking and observability
• Permission management
• Audit logging and compliance

Why This Matters​

This is how sustainable AI ecosystems form.

Not around models (which change constantly)
But around capabilities (which systems can rely on)

When Skills become standardized:

• Developers can publish once, run anywhere
• Enterprises can audit once, trust everywhere
• Agents can discover capabilities dynamically
• Security teams can govern at the Skill level

Why MCP Matters for Agent Skills​

Critical insight: Skills don't live in the model. They live in systems.

The model generates reasoning. Systems provide capabilities.

What MCP Provides​

The Model Context Protocol (MCP) solves the infrastructure problem for Skills:

Execution Layer:

• Transport-agnostic communication (stdio, HTTP, SSE)
• Remote skill invocation across boundaries
• Standardized request/response patterns

Enterprise Requirements:

• Security boundaries and permissions
• Air-gap compatibility for sensitive environments
• Authentication and authorization hooks

Governance & Compliance:

• Audit trails for all skill invocations
• Usage tracking and monitoring
• Policy enforcement points

The Transformation​

MCP turns Skills from abstract ideas into operational infrastructure.

• Before MCP: Each framework had its own Skill implementation
• After MCP: Skills work across frameworks, runtimes, and platforms
• Result: True interoperability and enterprise adoption

The Mental Model to Remember​

Reasoning stays with the model.
Authority stays with the system.

Skills are where that line is drawn.

This separation ensures:

• AI can be creative within bounds
• Systems maintain control
• Humans can audit and govern
• Security isn't dependent on prompt engineering

FAQ: Understanding Agent Skills​

Q: What is an Agent Skill?
A: An Agent Skill is a structured, declarative capability that an AI agent can invoke to perform an action through a system. Unlike prompts, Skills define explicit boundaries, permissions, and execution rules that machines can enforce.

Q: How do Agent Skills differ from prompts?
A: Prompts are implicit natural language suggestions with trust-based, non-deterministic behavior. Skills are explicit structured capabilities with contract-based, auditable, and governable execution. Prompts decide what to try; Skills define what is allowed.

Q: What's the difference between Skills, tools, and workflows?
A: Tools are low-level primitives (individual functions), workflows are pre-wired sequences (fixed automation), and Skills are bounded capabilities that agents choose to invoke. Skills sit at the decision boundary between AI reasoning and system execution.

Q: Why do AI agents need Skills instead of just prompts?
A: Prompt-driven agents don't scale at enterprise level. They can hallucinate actions, have implicit permissions, opaque execution paths, and are impossible to audit. Skills provide the control, governance, and security that enterprises demand.

Q: What role does MCP play with Agent Skills?
A: MCP (Model Context Protocol) provides a transport-agnostic execution layer for Skills, enabling remote skill invocation, enterprise security boundaries, air-gap compatibility, and audit/governance hooks. MCP turns Skills from ideas into infrastructure.

Q: Are Agent Skills becoming a standard?
A: Yes. What started as framework-specific abstractions is converging into shared specifications, common schemas, public registries, installation tooling, and usage tracking. Skills are becoming the standard unit of agent execution, governance, and enterprise adoption.

Q: Can Agent Skills be audited for security?
A: Yes. Unlike prompts, Skills are structured with explicit schemas, making them auditable and governable. They provide clear artifacts for security reviews, permission tracking, and execution path analysis.

Q: Where do Agent Skills execute?
A: Skills don't live in the model—they live in systems. The model handles reasoning, while Skills execute in controlled environments with proper security boundaries and governance. This separation ensures authority stays with the system, not the AI.

What Comes Next: The Skill-First Future​

Agent Skills are now the fundamental unit of:

✅ Agent execution — how AI agents perform actions
✅ Platform governance — how organizations control AI behavior
✅ Security review — how teams audit AI capabilities
✅ Enterprise adoption — how AI becomes production-ready

Your Next Steps​

The rest of this section explores how to:

• Design Skills that are secure and maintainable
• Build Skills using MCP and standard patterns
• Evaluate Skills for quality and safety
• Deploy Skills across environments
• Govern Skills at enterprise scale

We're treating Skills as systems — because that's what they are.

The era of prompt-only agents is ending.
The era of Skill-driven systems is here.

Where agents stop guessing — and start acting

AI agents don’t fail because they’re not smart.
They fail because they don’t know what they’re allowed to do.

Skills are the missing layer between reasoning and execution.
They turn vague prompts into explicit, auditable, testable actions.

This section is the home of everything you need to understand, design, and operationalize Skills using the Model Context Protocol (MCP).

What are Skills?​

A Skill is a structured, declarative capability that an AI agent can invoke safely and deterministically.

Think of a Skill as:

• A contract, not a prompt
• A capability, not a suggestion
• A tool with boundaries, not a magic trick

At a technical level, a Skill is:

• Defined using MCP
• Exposed as a tool with a clear schema
• Executed by systems, not the model itself

Reasoning stays with the model.
Authority stays with the system.

Why Skills exist (and prompts are not enough)​

Prompt-only agents break at scale.

They:

• Hallucinate actions
• Overreach permissions
• Leak secrets
• Fail silently
• Cannot be audited, tested, or governed

Skills exist to solve that.

They allow you to:

• Explicitly declare what an agent can do
• Control how and when execution happens
• Separate decision-making from authority
• Build agents that pass security, compliance, and platform reviews

If prompts are thoughts, Skills are hands.

Skills are not plugins. Not functions. Not workflows.​

Skills are often misunderstood.

They are not:

• Plugins (too UI-driven)
• Functions (too low-level)
• Workflows (too rigid)

Skills live in between.

They are:

• Composable
• Discoverable
• Context-aware
• Governable

This is why MCP matters: it gives Skills a standardized, machine-readable contract that works across:

• IDEs
• Agents
• Runtimes
• Enterprises
• Air-gapped environments

What you’ll learn in this section​

This Skills section is not a tutorial dump.
It’s a mental model + execution guide.

Here you’ll learn how to:

🔹 Design Skills​

• How to think in capabilities, not endpoints
• How to model inputs, outputs, and constraints
• How to avoid over-privileged Skills

🔹 Build Skills​

• API-to-MCP (a2m) Skill patterns
• Tool schemas that scale
• Error handling for agents (not humans)

🔹 Test & Evaluate Skills​

• Skill evaluation (mcp-eval)
• Deterministic vs probabilistic behavior
• Guardrails, contracts, and failure modes

🔹 Deploy Skills​

• Local vs remote MCP servers
• Enterprise-ready Skill exposure
• Air-gap and zero-trust patterns

🔹 Govern Skills​

• Skill registries
• Versioning and deprecation
• Security reviews and auditability

Who this section is for​

This section is written for people building real systems, not demos.

• Platform teams defining agent capabilities
• API teams turning services into agent-ready tools
• Security teams asking “what can this agent actually do?”
• Product leaders trying to ship AI features without chaos
• Builders who want agents that survive production

If you’ve ever asked:

“How do we control what the agent can do?”

You’re in the right place.

Skills are the unit of scale for agents​

Agents don’t scale by being smarter.
They scale by being better constrained.

Skills are:

• The unit of execution
• The unit of security
• The unit of governance
• The unit of enterprise adoption

This section exists because Skills are not optional anymore.

They are the foundation.

Start here​

If you’re new:

• Read What is a Skill?
• Then API → MCP Skills (a2m)
• Then Skill Evaluation & Safety

If you’re advanced:

• Jump straight to Skill Lifecycle Management
• Or Enterprise Skill Architectures

Either way — welcome.

This is where agents become systems. Be HAPI, and Go Rebels! ✊🏼

In this guide, we'll explore 4 different ways to run and deploy MCP servers using the HAPI CLI.

Bonus: Agent Skills provided to automate MCP server deployment.

1. Local Development (The Quickest Way)​

For rapid iteration and testing, running your MCP server locally is the best approach. You can instantly spin up a server and inspect its tools using the official MCP Inspector.

In this example, we'll run an OpenAI Tools server.

# Run the MCP Server Locally and pipe to Inspector
hapi serve openai-tools \
  --headless \
  --port 3030 \
  --url https://api.openai.com/v1 | bunx @modelcontextprotocol/inspector

Find more MCP server definitions in the official MCP Registry.

What's happening here?​

• hapi serve: Starts the MCP server.
• --headless: Runs without a UI (optimized for machine interaction).
• --port 3030: Binds the server to port 3030.
• | bunx @modelcontextprotocol/inspector: Pipes the output directly to the MCP Inspector, allowing you to interact with your tools in a web interface locally.

2. Docker Containers (The Portable Way)​

If you need to ship your server to Kubernetes, ECS, or any container orchestration platform, Docker is the industry standard. We provide a pre-built image hapimcp/hapi-cli that is ready to serve.

docker run --name hapi-openai -d \
  -p 3030:3030 \
  hapimcp/hapi-cli:latest serve \
  --openapi https://docs.mcp.com.ai/servers-apis/openapi/openai-tools.yaml \
  --headless \
  --url https://api.openai.com/v1

Breakdown:​

• hapimcp/hapi-cli:latest: The official HAPI CLI Docker image.
• --openapi ...: Specifies the OpenAPI definition for the server (defining the tools/resources).
• -p 3030:3030: Maps the container port to your host.

Your server is now running in a container, ready to accept connections on port 3030!

3. Cloudflare Workers (The Scalable Way)​

For a serverless solution with global low latency, Cloudflare Workers is the ultimate deployment target. HAPI CLI handles the entire build and deployment process for you.

hapi deploy --name openai-tools \
  --project openai \
  --openapi https://docs.mcp.com.ai/servers-apis/openapi/openai-tools.yaml \
  --url https://api.openai.com/v1

You'll see output like this:

📝 Generating temporary Wrangler config...
⚙️ Deploying to Cloudflare Workers...
🌍 Live at: https://openai-tools.runmcp.workers.dev
✅ Deployed successfully!

Why Cloudflare Workers?​

• Zero Cold Starts: Instant response times.
• Global Distribution: Deployed to 300+ cities worldwide.
• Cost Effective: Pay only for what you use.

4. Fly.io (The Global Way)​

For those who prefer running on Fly.io, you can deploy your MCP server instantly using our pre-built image, bypassing the need for Dockerfiles or complex overrides.

fly machine run hapimcp/hapi-cli:latest --command "hapi serve" \
  -e openapi="https://docs.mcp.com.ai/servers-apis/openapi/openai-tools.yaml" \
  -e url="https://api.openai.com/v1"

Why Fly.io?​

• Instant Machines: Boot full VM instances in milliseconds.
• Global Anycast: Run close to your users.
• Pre-built Image: No build step required—just run.

Agent Skills to Automate Deployment​

To make deployment even easier, we provide Agent Skills that automate the entire process of deploying MCP servers across different platforms. You can find this and more skills in the mcp.com.ai skills registry.

npx skills add https://github.com/mcp-com-ai/api-to-mcp-skills --skill api-to-mcp

Summary​

Ready to build your own? Check out the full documentation at docs.mcp.com.ai.

🏁 Done. Be HAPI, and go Rebels! ✊