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 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.

Can I turn an existing OpenAPI spec into an MCP server without writing code?

Yes. HAPI reads your OpenAPI (or Arazzo) document and generates MCP tools directly from it, one tool per operation, with names, descriptions, and parameters taken straight from the spec. There is no server code to write or maintain.

How do I preview the MCP tools an API will expose before deploying it?

Run `hapi serve --dry-run` against your OpenAPI or Arazzo document. It computes the exact tool list a live server would expose, no port bound, no server started, and can render it as a table, JSON, YAML, or a Markdown agent-prompt template.

How do I generate a system prompt for an AI agent from a production API?

Run `hapi serve --dry-run --output markdown` to get a system-prompt template with the Available Tools section already filled in from your API, then pipe it to a coding agent running the hapi-agent-prompt-generator skill to complete the Role, Objective, Tool-Use Policy, Operational Process, Error Handling, and Guardrails sections.

Can HAPI help prepare a ChatGPT App submission?

Yes. `hapi serve --dry-run --output json` produces a dump shaped like OpenAI's chatgpt-app-submission schema, with deterministic fields (tool names, descriptions, annotations) filled in and everything else left as clearly marked placeholders. The hapi-apps-dump skill then completes those placeholders.

Does my API need to be rewritten or redesigned to work with AI agents?

No. If your API already has a valid OpenAPI specification, it's already agent-ready. HAPI generates the MCP layer, the tool list, and the agent prompt from the spec you already have, your production API, security model, and documentation stay exactly as they are.

How does HAPI know which tools are safe versus destructive for an AI agent?

HAPI derives readOnlyHint and destructiveHint for every tool from the HTTP method (GET is read-only, POST/PUT/DELETE are destructive) or from explicit x-readOnlyHint/x-destructiveHint extensions in the OpenAPI document, and carries that into both the MCP tool annotations and the generated agent prompt's Guardrails section.

9 publicaciones etiquetados con "Guide"

Curated instructions or documentation designed to help users understand and implement specific use cases around MCP and related technologies.

Ver Todas las Etiquetas

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.

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.

From OpenAPI to MCP to AI Agent: The Zero-Code Playbook

Your API is already production-hardened. It has authentication, validation, rate limits, monitoring, and a battle-tested OpenAPI spec describing every operation. None of that changes when an AI agent becomes the caller instead of a browser or a mobile app.

How to Deploy MCP Servers

Setting up a Model Context Protocol (MCP) server is easier than you might think! It is a straightforward process that doesn't require extensive DevOps skills. Whether you're testing, packaging, or scaling globally, the HAPI MCP Stack equips you with everything you need to launch your server in just seconds.

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.

Integrate the OpenAI UI SDK for ChatGPT With MCP in 60 Seconds

You want your API to be instantly usable inside AI assistants like ChatGPT, and Web UIs. The OpenAI UI SDK plus the Model Context Protocol (MCP) lets you expose your API as structured tools that large language models can call directly.

Using OpenAI Response API for MCP Integration

This guide demonstrates how to use the OpenAI Response API to integrate with the Model Context Protocol (MCP) for seamless, AI-driven API interactions. You will learn how to generate a REST API specification with Postman's AI Agent, deploy it as an MCP server using HAPI Server, and connect it through OpenAI's Response API for testing.

OpenAI SDK Meets MCP (Model Context Protocol)

An evolution of tool calling with MCP, thanks to OpenAI's latest SDK updates.

Step-by-step, I'll guide you through setting up an MCP server, integrating it with the OpenAI SDK, and running a complete example that showcases dynamic tool calling. By the end of this post, you'll be equipped to leverage MCP in your own OpenAI-powered applications.