Skip to main content

VS Code extension: OrcA

The OrcA extension brings the HAPI MCP Stack into VS Code. You open an OpenAPI or Arazzo contract, see the MCP tools it produces, run it as a local MCP server, and connect it to your AI assistant, without leaving the editor.

What is OrcA?

This page is the practical guide. For what OrcA is, why it exists and where it fits in the stack, see OrcA component and How OrcA works.

Why use the extension?​

  • No context switching. The contract, its MCP tools, the running server and your AI assistant are all in one window.
  • See before you ship. Dry Run shows the exact tool list an agent will get.
  • Safe local runs. OrcA picks a free port, tracks the server, and tells you when it stops.
  • One click to your assistant. Add to VS Code registers the server in .vscode/mcp.json for Copilot, Claude and other MCP clients.

Install​

  1. In VS Code, open Extensions and search for OrcA. You can also install from the Marketplace or run: 
    code --install-extension la-rebelion-labs.orca-mcp
  2. Requirements:
    • VS Code 1.138 or newer (Windows, macOS, Linux, WSL, SSH, Dev Containers).
    • The HAPI CLI v1 for Run and Dry Run. If it is missing, OrcA offers to install it (OrcA: Install HAPI CLI). To install it yourself: 
      # Linux, macOS, WSL
      curl -fsSL https://get.mcp.com.ai/hapi.sh | bash -s -- --version v1
      # Windows (PowerShell)
      $s = irm https://get.mcp.com.ai/hapi.ps1; & ([scriptblock]::Create($s)) --version v1
  3. Open the OrcA icon in the activity bar. New to OrcA? Run OrcA: Open Guide for an animated tour, or open Help → Welcome → Get started with OrcA.

Quickstart: OpenAPI to MCP in 60 seconds​

  1. Open an OpenAPI 3.x file, or create one with OrcA: New Contract… → OpenAPI.
  2. Click Dry Run (beaker icon) in the editor title bar and choose Table to see the MCP tools.
  3. Click Run with HAPI (play icon). The server appears in MCP Servers and turns running when it is ready, for example at http://localhost:3000/mcp.
  4. Accept Add to VS Code (or right-click the server → Add to VS Code MCP Servers). Your AI assistant can now call the API's tools.

The OrcA sidebar​

ViewWhat you do there
ContractsFind OpenAPI and Arazzo files (Workspace and HAPI Home). Use New Contract… and Validate All Arazzo
OutlineNavigate the active contract. Arazzo: add or remove sources, workflows, steps
MCP ServersDeploy, start, stop, restart, view logs, open in browser, add to VS Code, delete
HAPI HomeBrowse ~/.hapi (specs, config, plugins, logs, certs); run the specs stored there
Activity (Secondary Sidebar)Timeline of server events

The status bar shows your HAPI session and mode, for example HAPI: anonymous · local.

How-tos​

Generate an AI-agent system prompt from an API​

Run Dry Run → Markdown. The template already lists every tool. Complete the role and policies with your coding agent and the hapi-agent-prompt-generator skill.

Prepare a ChatGPT App submission​

Run Dry Run → JSON. The tool names, descriptions and read-only/destructive hints are filled in from your contract. Complete the placeholders with the hapi-apps-dump skill.

Run on a specific port or headless​

Use Run with HAPI (Options)…: choose --mcp, --headless (MCP only) or --dev (hot reload), and a port. If the port is taken, OrcA offers the next free one.

Orchestrate several API calls deterministically​

Create an Arazzo workflow (New Contract… → Arazzo Workflow), point its sourceDescriptions at your OpenAPI files, validate it, then Run with HAPI. Each workflow is exposed as one MCP tool. See HAPI Workflows.

Deploy an MCP server​

Right-click an OpenAPI contract → Deploy MCP Server and name it. In remote mode (orca.hapi.apiMode), sign in first. Your HAPI profile decides the region and plan.

Settings​

SettingDefaultPurpose
orca.contracts.include / exclude**/*.{json,yaml,yml} / node_modules, dist, .gitWorkspace contract scan
orca.hapi.home(empty)HAPI Home override (else $HAPI_HOME, else ~/.hapi)
orca.hapi.cliPathhapiHAPI CLI executable
orca.hapi.serve.defaultArgs["--mcp"]Arguments for Run with HAPI
orca.hapi.apiModelocallocal (no network calls) or remote
orca.hapi.apiBaseUrl / wsBaseUrlhttps://api.mcp.com.ai / wss://api.mcp.com.ai/wsHAPI API for remote mode
orca.activity.enabled / retentiontrue / 50Activity view

Troubleshooting​

SymptomFix
"Running MCP servers locally needs the HAPI CLI"Choose Install HAPI, or set orca.hapi.cliPath. Check with OrcA: Check HAPI CLI
Server stays provisioning, then errorOpen its terminal (View Logs) to see HAPI's error, for example a bad $ref or an unsupported Arazzo version
"Only Arazzo 1.1.x is supported"Set arazzo: 1.1.0 in the workflow; the Outline shows this hint for 1.0 documents
Server started on 3001 instead of 3000Port 3000 was in use; OrcA picked the next free port (see Activity)
A contract is not listedCheck that it declares openapi: 3.x or arazzo: 1.x at the root, and that it is not excluded by orca.contracts.exclude