What are the Ask, Plan and Act roles in OrcA?

They are chat roles that decide what an AI agent may do with your MCP servers. In Ask, the model only receives read-only tools and answers questions. In Plan, it also uses capability planning and ends with a numbered plan, without changing anything. In Act, it receives every tool, and changes still ask for your approval by default.

Why use roles if I already have a capability graph?

The capability graph describes what the API needs and in what order; it is read-only advice and never prevents a tool call. The role decides what the agent may do in this conversation. In Ask and Plan, tools that change data are never sent to the model, so it cannot call them. Roles also work with servers that have no capability graph.

Is a role just an instruction in the prompt?

No. OrcA enforces roles in the tools it sends: hidden tools are removed from the request, from the deferred tool catalog and from search results, and a call to one is refused with a message naming the role. The instructions only explain the role to the model.

When should I use Ask, Plan or Act?

Use Ask to explore an API or test a new server with zero risk. Use Plan before multi-step or irreversible actions, to review the steps, missing information and confirmations first. Use Act when the steps are clear, typically after Plan with the Proceed button.

How do roles relate to tool approvals?

The role decides which tools exist for the model; approvals decide when OrcA asks you before using them. In Act, the default preset asks before any tool that may change data, and workspace rules can always allow or never allow a specific tool.

What is an agent harness?

An agent harness is the software layer that runs an agent session. It prepares the instructions, context and tool definitions for the language model, applies approval rules, routes tool calls, and records what happened. OrcA 0.4 is a harness specialised for MCP and API work inside VS Code; it does not edit files or run a terminal.

What is progressive tool discovery in MCP?

Instead of sending every tool definition on every turn, the client sends a small search_tools tool plus a list of tool names, and loads full definitions only when they are needed. OrcA 0.4 searches with each message you send, loads matching tools before the model answers, appends them so prompt caches keep working, and resets them on New Chat.

How do I reduce MCP context bloat?

Serve your API with a search tool (for HAPI, --deferred-tool-search or --capability-graph) and keep orca.chat.toolDiscovery on auto, or set it to always to let OrcA search any server locally. The Harness tab shows the tokens your tools cost upfront compared with the full catalog.

Can OrcA connect to MCP servers not built with HAPI?

Yes. Use Add External MCP Server… with a name, a Streamable HTTP URL and optional headers, or Import MCP Servers… from .vscode/mcp.json and your user mcp.json. External servers get chat, traffic, proxy capture and Add to VS Code. stdio and SSE servers are not supported.

Can I get an OpenAPI contract for a hand-written MCP server?

Yes. Generate Contract infers a deterministic OpenAPI 3.1 document from a connected server's tools, resources, resource templates and prompts. It is linked to the server, so Open Operation in Contract works, and OrcA marks the contract out of date when the server's tools change.

Does OrcA 0.4 support OAuth-protected MCP servers?

Not yet. OrcA connects with static headers, such as a bearer token or an API key, stored in VS Code's secret storage. OAuth support is planned.

What is an MCP-based agent?

An MCP-based agent is a Large Language Model that runs in a loop inside a harness and acts through Model Context Protocol (MCP) tools. In the HAPI MCP stack, the tools come from your OpenAPI and Arazzo contracts, the harness is OrcA or your agent platform, and a role narrows the agent to a job.

Do I need to write code to give an agent tools from my API?

No. HAPI reads an OpenAPI 3.x or Arazzo 1.1 contract and serves each operation or workflow as an MCP tool. With --headless --url, HAPI forwards each tool call to your existing backend, so the contract is the whole integration.

What is an agent harness, and what does OrcA do?

A harness prepares the instructions, context, and tool definitions for the model, applies approvals, routes tool calls, and records what happened. OrcA is a VS Code harness for MCP and API work: it connects models to MCP servers, loads tools progressively, asks before tools that are not read-only, and shows every exchange in its Traffic view. It does not edit files or run a terminal.

How do I stop an agent from loading too many tools?

Serve the contract with --capability-graph or --deferred-tool-search. HAPI defers operation tools behind a tool_search tool, and OrcA loads only the tools each message needs, while listing the names of the rest so the model knows they exist.

How do I test an MCP agent before production?

Test plans offline with hapi graph audit and hapi graph simulate, then test conversations in OrcA. The Context tab shows goals, required facts, and gates, and the Traffic view shows each model round and tool call with latency, tokens, and cost.

How do I deploy an MCP server built from an OpenAPI contract?

Run hapi deploy with an HTTPS contract URL and your backend URL to deploy a headless MCP server to Cloudflare Workers, or select Deploy MCP Server on the contract in OrcA.

What is MCP context bloat, and how do I avoid it?

Context bloat happens when an MCP server sends every tool definition with every request, so the model spends its context on tools it never uses and picks the wrong one more often. Serve the contract with --capability-graph or --deferred-tool-search, and let a harness such as OrcA load tools progressively.

What is progressive tool discovery?

Progressive tool discovery sends a small search tool and a few always-loaded tools instead of the full catalog. OrcA loads matching tools before the model answers each message, lists the names of the remaining tools so the model knows they exist, and appends discovered tools without reordering them, which keeps prompt caches valid.

What are the x-hapi extensions in OpenAPI?

They are OpenAPI extensions that HAPI compiles into its capability graph: x-hapi-capability and x-hapi-intent for discovery, x-hapi-effects and x-hapi-prerequisites for behavior, x-hapi-planning for state transitions, x-hapi-client-facts for facts people establish, x-hapi-outcome for failure responses, and x-hapi-event for webhooks.

Why does capability_plan always return clarification-required?

Usually because some required facts are never produced by an operation and are not declared as client facts. Run hapi graph audit to list these orphan requirements, then declare selections, confirmations, and identity checks in x-hapi-client-facts.

Why does every search tool ask for confirmation?

HAPI marks every POST, PUT, PATCH, and DELETE operation as destructive unless the contract sets tool hints, and clients such as OrcA ask before any tool that is not read-only. Add x-readOnlyHint: true and x-destructiveHint: false to read-only searches that use POST.

Does HAPI tool search work across languages?

No. HAPI search matches words in tool names, descriptions, and arguments. Write summaries in the language of your users, or add their terms to descriptions; OrcA's catalog of tool names reduces, but does not remove, the impact of a language mismatch.

What is an intent-based API?

An intent-based API contract adds a decision layer to an API description: when each operation applies, what it changes, which verified facts it requires and produces, and what a failure means. HAPI compiles this metadata into a capability graph, so an agent can map a request to a goal and receive a deterministic plan that names the missing information.

Are Arazzo workflows and HAPI intent-based contracts redundant?

No. Arazzo workflows encode fixed sequences that must always run together. Intent-based contracts let a planner decide which atomic operations, and which workflows, to run from the current state. A workflow with x-hapi-planning becomes one atomic step in those plans.

Are Arazzo workflows all-or-nothing?

No. An Arazzo workflow stops at the first step whose success criteria fail, but earlier steps have already changed state in the source API. Neither Arazzo nor HAPI undoes earlier steps automatically, so compensation is a design decision.

Are API workflows idempotent?

Only when every step is idempotent or carries an idempotency key. A step that creates a record with a new identifier is not idempotent, so running the workflow twice creates two records.

Is an OpenAPI description enough for AI agents?

It is enough to call an API, not to use it safely. OpenAPI describes paths, schemas, status codes, and security, but not when an operation is the right choice, what it changes, what must already be true, or what a failure means for the next step.

Does intent-based planning stop LLM hallucinations?

It limits their impact. The model still interprets the request, but permissions, prerequisites, ordering, and confirmations come from the contract and are enforced deterministically. The planner never invents facts; it accepts only facts the client verified and reports the missing ones.

What is the MCP Multiplication Tax?

The MCP Multiplication Tax is the hidden cost of generating a separate MCP implementation for every API an enterprise owns, instead of exposing existing APIs through MCP. Generating the code is nearly free with AI; owning, securing, and maintaining a second implementation of every business capability for the rest of its life is not.

Does AI reduce the total cost of owning an MCP server, or just the cost of writing it?

AI mostly reduces generation cost, which is usually the smallest part of a system's lifetime cost. Validation, integration, security review, observability, synchronization with the source API, and eventual retirement still have to happen, generated code or not — and at enterprise scale, those recurring costs multiply by however many separate implementations exist.

Should every API get its own hand-built or AI-generated MCP implementation?

Not if the API already has a maintained OpenAPI specification. A separate implementation per API means separate code, dependencies, auth wiring, and drift risk for every one of them. Translating the existing OpenAPI contract into MCP tools directly avoids creating a second implementation surface for a capability that already exists.

What is 'shadow software' in the context of MCP?

Shadow software is a second implementation of a capability that already exists behind an API, built so an AI agent can reach it through MCP. If the API changes and the shadow doesn't change with it, the two start returning different behavior for the same capability — one for REST consumers, another for AI agents — and keeping them in sync becomes its own ongoing maintenance burden.

How does HAPI MCP avoid duplicating existing API implementations?

HAPI treats MCP as a contract, not a server: it reads an existing OpenAPI (or Arazzo) document and exposes it through MCP directly, rather than generating a standalone implementation that has to be kept in sync by hand. The API stays the one source of truth; MCP becomes another interface to it, the same way a web app or a mobile client is.

What is MCP elicitation?

MCP elicitation is a standardized feature (elicitation/create) that lets a server pause mid-task and ask the connected user for structured, schema-validated information through the client, instead of guessing a missing value or failing the request outright.

Is MCP elicitation a bad practice?

No, but it's easy to overuse. Elicitation is the right tool for confirming a destructive action or asking for something only the user can know. It's the wrong tool for filling in a required field your API already knows is required, or for chaining together a multi-step process — both of those are design problems elicitation just papers over.

How do I reduce the need for elicitation in my MCP tools?

Design each API operation to be atomic and explicit about its required parameters in the OpenAPI spec, so an agent can see what's required before it calls the tool instead of finding out mid-call. For processes that genuinely need multiple steps, define the sequence explicitly with HAPI Workflows (Arazzo) instead of letting the model improvise it through back-and-forth elicitation.

What's the difference between elicitation and a multi-step workflow?

Elicitation asks a human for one flat, primitive value mid-call, at runtime, on demand. A workflow defines the dependency between steps — 'this step's input comes from that step's output' — as an explicit, deterministic sequence the server executes, with no back-and-forth with the user needed to figure out what comes next.

Can HAPI Workflows replace MCP elicitation for multi-step processes?

For the class of elicitation that exists only to chain calls together — 'what's the ID from the last step?' — yes. HAPI Workflows, built on the Arazzo specification, let you define that dependency once as data, so the sequence runs deterministically instead of relying on the model to ask and remember it correctly every time.

What data can I request through MCP elicitation?

The MCP spec restricts elicitation's requestedSchema to flat objects with primitive properties only — strings, numbers, booleans, and enums, no nested objects or arrays of objects. It also explicitly forbids requesting sensitive information through elicitation.

What does it mean for an MCP server to be stateless?

A stateless MCP server processes every request independently, using only the information that request itself carries, instead of inferring context from an earlier request on the same connection. If something needs to persist across requests, it's referenced by an explicit identifier — an orderId, a jobId, a task handle — that the client sends again, not held in server memory.

Does a stateless MCP server mean the business has no state at all?

No. Orders, customer records, and long-running jobs all have real state — it just doesn't belong inside the MCP layer. A stateless MCP server references that state explicitly through IDs and handles instead of hiding it inside a process or a connection, leaving the actual state where it already lives: the business system of record.

Why doesn't HAPI MCP use the stdio transport?

stdio couples an MCP server's lifecycle to a local client process and typically pulls credentials from the local environment, which is workable for personal tooling but harder to govern at enterprise scale. HAPI MCP uses HTTP-based, headless deployment instead, so authentication, authorization, and credentials stay at well-defined network boundaries regardless of deployment target — cloud, on-premises, hybrid, or air-gapped.

How does statelessness help an MCP server scale?

When every request is self-contained, any healthy server instance can handle it — a restart doesn't erase an in-progress conversation, a retry doesn't need to recover hidden memory, and traffic can be load-balanced freely. That's what lets a stateless MCP layer run behind a load balancer, in a container, or at the edge, with the same behavior every time.

What is MCP's sessionless direction / explicit state handles?

It's a pattern where, if an operation needs to continue across multiple requests, the server returns an explicit handle and the client sends that same handle back on the next request — rather than the server inferring continuity from an open connection. The state becomes visible and portable instead of implicit, which is exactly what a stateless MCP layer needs to support genuinely long-running work.

What is an MCP shadow implementation?

An MCP shadow is an MCP server that duplicates capabilities, business logic, validation, or authorization already implemented by an existing API, instead of exposing that API directly. It can look identical to the original at first, then quietly drift as the API changes and the shadow doesn't.

Why is duplicating API logic into an MCP server risky?

Because it creates two implementations of the same business capability that can disagree. If the API and the MCP shadow diverge — a validation rule fixed in one but not the other, an authorization change applied to one but not the other — traditional clients and AI agents can produce different outcomes for what's supposed to be the same operation.

Should every API endpoint become an MCP tool?

No. Curating which capabilities an agent actually needs — and designing tool descriptions around AI intent — is a separate problem from avoiding duplication. You can expose a small, curated set of MCP tools that still execute against the same production API, with no shadow implementation behind any of them.

How does HAPI MCP prevent shadow implementations?

HAPI MCP treats your OpenAPI contract as the source of truth and projects it into MCP tools directly, rather than generating a standalone implementation that has to be manually kept in sync. When the API changes, the MCP projection reflects it — there's no second codebase that can quietly fall behind.

Does keeping MCP transparent affect authentication and authorization?

It should improve it. If authorization rules stay anchored to the API that already enforces them, there's no second identity or permission model for MCP to get out of sync with. A shadow that diverges on authorization — the API denies an action the MCP layer allows — is a security incident, not just a bug.

12 posts tagged with "Best Practices" | The control plane for MCP in real environments

Ask, Plan, Act: Agent Roles That Decide What Your MCP Agent May Do

An AI agent with access to your API can read data and change it. The question is not whether it can do something, but whether it should, right now. OrcA answers that with three roles: Ask, Plan and Act. You choose how much the agent may do in each conversation, and OrcA enforces it in the tools the model receives, not only in its instructions.

OrcA 0.4: An MCP Agent Harness in VS Code, for Any MCP Server

OrcA 0.4 turns VS Code into an agent harness for MCP and API work. Connect any Streamable HTTP MCP server, not only HAPI ones. Let the agent load tools as the conversation moves instead of drowning in 40 schemas per turn. Read and edit exactly what the model is told, and see the goals, facts and plans behind a multi-step request. Still free, still no telemetry (by default).

How to Build and Manage MCP-Based Agents from Your API Contracts

What you will learn

How to build an MCP-based agent without writing tool code.
How to define capabilities in OpenAPI 3.x contracts with intent-based planning.
How to give the agent a transparent harness in VS Code.
How to test, measure, deploy, and manage an MCP-based agent over time.

How to Design OpenAPI Contracts That Guide AI Agents

What you will learn

How to enrich an OpenAPI contract for progressive tool discovery.
How to declare effects, intent, and planning facts for AI agents.
How to model business state and human-established facts.
How to audit, simulate, and serve the capability graph.
How to verify agent behavior in VS Code.

How to Make Intent-Based Contracts and APIs AI-Ready

What you will learn

How intent-based planning balances model interpretation with deterministic enforcement.
How to make an OpenAPI contract intent-based AI contract.
How to verify contracts and workflows.
How to observe re-planning behavior in VS Code.

MCP With No Shadows: Adopting MCP Without Rebuilding Your Stack

Every team adopting MCP eventually hits the same fork in the road: reimplement your business capabilities as an MCP server, or expose what you already have through one.

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.

AI Made Code Cheap. Ownership Is Still Expensive.

AI has dramatically reduced the cost of writing code. It has not reduced the cost of owning 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."

12 posts tagged with "Best Practices"

Ask, Plan, Act: Agent Roles That Decide What Your MCP Agent May Do

OrcA 0.4: An MCP Agent Harness in VS Code, for Any MCP Server

How to Build and Manage MCP-Based Agents from Your API Contracts

How to Design OpenAPI Contracts That Guide AI Agents

How to Make Intent-Based Contracts and APIs AI-Ready

MCP With No Shadows: Adopting MCP Without Rebuilding Your Stack

AI Made Code Cheap. Ownership Is Still Expensive.

MCP Elicitation Is a Symptom, Not a Strategy

Stateless MCP Servers the Enterprise Way

MCP Shadow Implementations: Why Duplicated Business Logic Breaks Trust