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.

How do I debug an MCP server in VS Code?

Install OrcA 0.3, right-click a running server in the MCP Servers view and choose Connect, then run OrcA: Show Traffic. Every JSON-RPC request, response and notification appears in a live timeline with latency, size and status. You can open any payload as JSON, diff two calls, copy a call as cURL, and replay it.

How can I see what GitHub Copilot sends to my MCP server?

In OrcA, right-click the server and choose Expose via Proxy, then Add to VS Code and pick Through OrcA (captured). OrcA registers a local proxy address (http://127.0.0.1:7331/mcp/ ) in .vscode/mcp.json. Copilot keeps working as usual, and every request it sends shows up in OrcA Traffic with the client name.

Can I chat with my MCP server without an API key?

Yes. OrcA's Chat can use the language models VS Code makes available to extensions, such as GitHub Copilot's models, which need no extra key. OpenAI, Anthropic, Groq, OpenRouter, Ollama, LM Studio and any OpenAI-compatible endpoint are also supported; their keys are stored in VS Code's secret storage.

Is OrcA an alternative to MCP Inspector?

For day-to-day work inside VS Code, yes. OrcA connects to several MCP servers at once, lists their tools, resources and prompts, lets an LLM use them in a chat, and records both the LLM rounds and the MCP tool calls in one correlated graph. It also captures traffic from other MCP clients through a local proxy. Calling a single tool by hand from a form is planned for a later release.

Does OrcA send my traffic or prompts anywhere?

No. OrcA has no telemetry and no vendor SDKs. Traffic stays in memory with secrets redacted, the chat only contacts the LLM provider you selected, the proxy listens on 127.0.0.1 only, and nothing is written to disk unless you save a session file.

Does OrcA support OAuth-protected MCP servers?

Not yet. OrcA 0.3 connects with static headers such as a bearer token (Set Headers…). OAuth-protected servers are detected and reported; OAuth support is planned for an upcoming release.

OrcA (Orchestrator for APIs and Agents) is a VS Code extension, part of the HAPI MCP Stack. It turns OpenAPI and Arazzo contracts into MCP servers inside the editor: it finds your contracts, previews their MCP tools, runs them locally with the HAPI CLI, deploys them, and registers them with your AI assistant.

How do I turn an OpenAPI or Swagger spec into an MCP server in VS Code?

Install OrcA, open your OpenAPI 3.x file, and click Run with HAPI in the editor title bar. OrcA starts hapi serve on a free port and shows the server in the MCP Servers view; Add to VS Code then registers it in .vscode/mcp.json. Swagger 2.0 documents need converting to OpenAPI 3 first.

Can I see which MCP tools an API will expose before running it?

Yes. OrcA's Dry Run runs hapi serve --dry-run and opens the tool list beside your contract as JSON (a ChatGPT App submission dump), Markdown (an AI-agent system prompt template), YAML, or a table. No server is started.

What happens if port 3000 is already in use?

OrcA checks that the port is really free before starting HAPI. If port 3000 is taken, it starts on the next free port and notes it; if you chose the port yourself, it asks and offers the next free one. It never gives two of its own runs the same port.

Does OrcA replace the runMCP VS Code extension?

Yes. The runMCP VS Code extension is deprecated and all of its features, including deploying and managing MCP servers, now live in OrcA.

What is a deterministic workflow for an AI agent?

A deterministic workflow is an explicit sequence of approved operations, prerequisites, and failure paths. An AI agent may interpret a user's request, but the workflow defines how the resulting business action executes and how the outcome is verified.

What is the difference between AI planning and deterministic execution?

AI planning interprets ambiguous language, proposes an outcome, and asks for missing details or approval. Deterministic execution carries out the approved operations in a declared order, applies API validation and authorization, and handles known failures or compensation paths.

How do HAPI Workflows expose deterministic workflows through MCP?

HAPI Workflows validates an Arazzo workflow that references documented OpenAPI operations, then exposes each supported workflow as an MCP tool. An agent can request a meaningful outcome instead of manually coordinating every low-level API call.

Does HAPI Workflows replace Camunda or Temporal?

Not necessarily. Camunda, Temporal, and other workflow engines remain appropriate when they own durable process state, timers, people tasks, or complex orchestration. HAPI Workflows provides an API-contract and MCP layer for declared OpenAPI workflows; it should complement, not duplicate, an existing system of record.

Why expose a workflow as an MCP tool instead of every API endpoint?

A workflow tool gives the agent a meaningful outcome with declared step dependencies, rather than asking it to reconstruct a business process from unrelated low-level operations. The underlying APIs remain the authority for authentication, authorization, validation, and business rules.

What is HAPI Capability Graph?

HAPI Capability Graph is a contract-first representation of what API operations accomplish, when they apply, what effects they have, and which prerequisites must be true. It helps an MCP client narrow a large tool list to the operations that fit the user's request.

What is Capability Planning for MCP?

Capability Planning evaluates explicit business state and returns a bounded next-step proposal. It can report that a goal is complete, that an action is ready, that information or confirmation is missing, or that no declared safe path exists. Planning prepares an action; it does not call the production API.

How do HAPI Capability Graph and Jev from TypeSafe AI work together?

HAPI and the API contract define the allowed tools, policies, prerequisites, and deterministic shortlist. Jev can optionally interpret nuanced user language and rank that already eligible shortlist with structured decisions and confidence. Jev does not replace API authorization, business rules, or HAPI planning.

Does Capability Planning execute API actions?

No. Capability Planning does not book, cancel, charge, update, delete, or otherwise call the API. It returns an explainable proposal so the MCP client and user can decide whether to execute the next approved action.

Why use a Capability Graph instead of giving an AI agent every MCP tool?

A flat list forces an AI agent to infer workflow, prerequisites, and risk from tool names alone. A Capability Graph lets HAPI deterministically focus discovery on relevant operations and make missing information, confirmation requirements, and safe next steps explicit.

The control plane for MCP in real environments

The Problem

AI Projects Fail When They Create Shadow Systems

Teams rebuild API logic in agent code. Duplicate business rules in LLM prompts. Lose governance. Accumulate technical debt. There's a better way.

HAPI MCP — Your APIs, AI-Ready. No Shadows.

OASMCPArazzoLLMs

No shadow code: Your API is the single source of truth. No duplicate logic in agent layers.
No shadow IT: Same auth, same policies, same audit trails. Governance flows through automatically.
No rewrites: OpenAPI specs become MCP tools instantly. Update the spec, tools update.

Works with your existing stack: HAPI Server for auto-generation, runMCP for scaling, OrcA for orchestration, QBot + chatMCP for interfaces. Deploy in seconds! Not hours, not weeks.

Read the Docs See How It Works

Impact

Why Teams Choose HAPI MCP

Real business value. No technical debt. Deploy AI faster without compromising governance.

Zero Shadow Code

Your APIs are the runtime. No duplicate logic in agent layers. One source of truth, always in sync.

Deploy in Seconds

OpenAPI to MCP tools automatically. What takes competitors months happens before you finish your coffee.

Keep Governance

Auth, RBAC, rate limits, audit trails—inherited from your APIs. Compliance teams sleep better.

Scale Effortlessly

runMCP handles serverless elasticity and long-running tasks. Cold-start fast, stay warm for throughput.

Predictable Workflows

OrcA orchestrates multi-step tasks deterministically. No brittle prompt chains or guesswork.

Stay Portable

Works with any MCP client—ChatGPT, Claude, QBot, custom agents. No vendor lock-in.

Who Wins With HAPI

Executives

Ship AI initiatives without ballooning cost. Keep teams focused on outcomes, not rewrites and integration sprawl.

Architects & PMs

Design with OpenAPI/Arazzo, run with MCP. Clear contracts, policy inheritance, and versioned workflows keep risk low.

Engineers & Ops

Deploy once. HAPI Server + runMCP scale tools; QBot/chatMCP give fast feedback; OrcA keeps executions deterministic.

Your Stack, Already Wired

HAPI Server

Turns OpenAPI into MCP tools automatically—contracts stay in sync with your source of truth.

runMCP

Autoscaling execution and testing for MCP tools; cold-start fast, stay warm when workflows run long.

OrcA

Deterministic planning and orchestration for multi-tool tasks; no brittle prompt spaghetti.

QBot

CLI TUI for power users to interact with MCP tools directly from terminal or scripts.

chatMCP

Conversational client that speaks MCP natively for support, ops, and internal assistants.

Agents

Build agentic systems from standard APIs—no custom glue. Connect MCP clients across platforms.

What Teams Say

“We pointed HAPI at our Swagger and had MCP tools in production in a week.”

“Security loved it—policies and audit trails stayed exactly as before.”

“OrcA plus runMCP gave us deterministic, scalable workflows without prompt spaghetti.”

FAQs

Do we need to rewrite our services?

No. HAPI MCP lifts your existing OpenAPI specs directly into MCP tools. Your auth, validation, and business rules remain unchanged.

Is this just another MCP server?

It’s the Headless API model: your API is the runtime. HAPI Server reflects it as MCP; runMCP scales it; OrcA orchestrates it. No duplicate logic.

Which clients can consume the tools?

Any MCP client: ChatGPT, Claude, QBot, Agentico.dev, chatMCP, bespoke orchestrators—vendor-neutral by design.

How do we keep control and compliance?

Your API remains the single source of truth. Policies, RBAC, rate limits, and audit logs flow through automatically; no shadow logic.

What about security and privacy?

Scoped credentials, per-tool permissions, and auditable calls are inherited from your API layer. HAPI adds guardrails and observability for regulated environments.

Get the HAPI MCP Briefing

Tactical updates on MCP, OpenAPI-first patterns, and how teams ship AI without rewrites.

Request a Demo

See HAPI MCP in action — from spec to MCP tools to OrcA-run workflows across QBot and chatMCP.

Stop Building Shadow Systems. Make Your APIs AI-Ready Today.

AI Projects Fail When They Create Shadow Systems

HAPI MCP — Your APIs, AI-Ready. No Shadows.

How It Works

Pick your API spec

Run a single command

Use instantly

Visual Pipeline

Get the HAPI MCP Briefing

Request a Demo

Why Teams Choose HAPI MCP

Zero Shadow Code

Deploy in Seconds

Keep Governance

Scale Effortlessly

Predictable Workflows

Stay Portable

Who Wins With HAPI

Executives

Architects & PMs

Engineers & Ops

Your Stack, Already Wired

HAPI Server

runMCP

OrcA

QBot

chatMCP

Agents

What Teams Say

FAQs

Get the HAPI MCP Briefing

Request a Demo

Recent Posts