# Invokta
**Build software for the agents your users already use.**
Your customers and teams should not have to adopt another AI agent to use a
valuable product capability. They should be able to invoke it from an
MCP-compatible agent, application, CLI, or automation already in their workflow.
Invokta is the TypeScript framework for building **Action Engines**: versioned,
headless capabilities that remain independent of one agent harness. Headless
means the capability can be called without forcing the user through your UI or
into a proprietary agent.
Define the domain contract, access rule, tools, and validation once. Publish the
same implementation through application code, the CLI, MCP stdio, or stateless
MCP Streamable HTTP. Your product continues to own the action while users keep
the agent and interface they prefer.
For example, a calendar API can create an event. An Appointment Scheduling
Engine can expose `appointments.schedule`, check authorization and clinic rules,
revalidate the selected slot, write through the authorized calendar connector,
and return either a confirmation or a stable conflict.
The same boundary makes an internal software factory harness-agnostic. A team can
move between agent clients without copying prompts, integrations, permissions,
validation, and error handling into every harness.
## Run your first Action Engine
Standalone engines require Node.js 22.20.0 or later. The creator supports npm,
pnpm, and Yarn; this example uses npm.
```sh
npm create invokta-engine@latest my-engine -- --profile complete --yes
cd my-engine
npm run check
npm run direct -- Ada
```
The final command invokes the generated capability through `engine.invoke` and
prints:
```json
{"message":"Welcome, Ada!"}
```
Open the generated project and you will find the capability contract, its test,
the shared engine, and the selected entry points. Start the interactive
inspector in a separate terminal:
```sh
npm run devtools
# Open the URL printed by the command. Press Ctrl+C to stop.
```
If the profile includes MCP stdio, installation in detected agent clients is
optional:
```sh
npm run mcp:install
# Later:
npm run mcp:uninstall
```
Continue with the [getting-started guide](./docs/getting-started.md), inspect the
[`hello-engine`](./examples/hello-engine/), or browse
[use cases by company area](./apps/docs/src/content/docs/use-cases/index.mdx).
## One capability, every published entry point
Invokta starts with a domain action such as
`engineering.prepare-implementation`, not with a transport or provider API.
```text
Cursor ───────┐
Claude Code ──┤
Codex ────────┤
CLI ──────────┼──> engineering.prepare-implementation
Application ──┘ |
├── ticket intent
├── repository context
├── architecture decisions
├── design
├── engineering rules
└── implementation-ready brief
```
The consumers choose when to invoke the capability. The Action Engine owns how
the brief is prepared and validates the request and result through the same
execution pipeline every time.
This boundary gives the action:
- runtime-validated input and output contracts;
- one access rule and one structured failure model;
- one implementation reused by every published adapter;
- tests that do not require a complete agent session; and
- independent ownership and versioning as its internals evolve.
CLI and MCP adapters always reach capability execution through `engine.invoke`.
Business rules do not move into transport handlers.
## From MCP access to an owned product capability
MCP gives compatible agents a standard way to discover and call tools. Invokta
publishes each capability as an MCP tool while keeping the domain behavior in an
Action Engine that can also serve application code and the CLI.
| Building block | What it owns |
| --- | --- |
| Prompt or rule | Instructions and constraints for a model or agent |
| Skill | Guidance that teaches an agent when and how to perform work or invoke an action |
| MCP | A protocol for connecting AI applications to tools and data |
| Loop or graph | The order of steps, branches, retries, and stopping decisions |
| Action Engine | The versioned implementation and runtime contract of one domain outcome |
A skill may teach an agent when to call `support.classify-ticket`. MCP carries
the call, and a loop may decide what happens next. The Action Engine validates
the ticket, enforces access, invokes the classifier, validates the result, and
returns the same public shape to every consumer.
The full [Action Engines community definition](./docs/action-engines.md) is
framework-neutral and explains the category independently of Invokta.
## What an Action Engine can own
An engine can combine prompts, models, provider APIs, local scripts, templates,
data, permissions, and domain rules behind a small set of capabilities.
| Example engine | Example capabilities | What the caller receives |
| --- | --- | --- |
| Product Analytics Engine | `analytics.explain-funnel-change`, `analytics.prepare-account-summary` | A tenant-scoped explanation or account summary with supporting evidence |
| Video Production Engine | `video.transcribe-source`, `video.plan-edit`, `video.apply-edit` | A transcript, edit plan, and rendered video with evidence |
| Social Carousel Engine | `carousel.prepare-series`, `carousel.render-series`, `carousel.assess-readiness` | An ordered carousel that is ready to publish or has explicit blockers |
| Commercial Proposal Engine | `sales.prepare-proposal`, `sales.render-proposal`, `sales.assess-proposal-readiness` | A customer-specific proposal and a readiness decision |
| Appointment Scheduling Engine | `appointments.list-valid-slots`, `appointments.schedule`, `appointments.reschedule` | Valid options and a confirmed calendar write or stable conflict |
| Recruiting and Selection Engine | `recruiting.screen-candidate`, `recruiting.record-screening`, `recruiting.notify-review` | An evidence-backed screening record and a human-review notification |
These are illustrative domain boundaries, not provider integrations bundled
into the framework. Your engine owns its providers and outcome quality. See the
[complete use-case catalog](./apps/docs/src/content/docs/use-cases/index.mdx) for
examples across software products, engineering, content, product, marketing,
sales, healthcare, recruiting, support, and operations.
## What Invokta owns and what your engine owns
| Invokta provides | Your Action Engine provides |
| --- | --- |
| Capability and engine contracts | Domain-oriented capability IDs and schemas |
| Runtime input and output validation | Prompts, models, tools, scripts, and templates |
| Access enforcement and structured errors | Authentication and domain authorization integrations |
| Cancellation and minimal invocation events | Provider clients, data stores, and outbound connectors |
| Direct, CLI, MCP stdio, and stateless MCP HTTP entry points | Evaluations, metrics, and outcome-quality rules |
| Composition checks, devtools, installation, and deployment helpers | Deployment configuration and dependency lifecycle |
Invokta is deliberately not an identity provider, model router, agent harness,
workflow engine, provider catalog, or production observability platform. Those
boundaries remain explicit so an engine can change its implementation without
turning the framework into a service container.
<details>
<summary><strong>Packages and development tools</strong></summary>
- `@invokta/core` defines capabilities, typed connector factories, engines,
validation, access, cancellation, errors, and events.
- `@invokta/cli` provides `list`, `describe`, and `run` through
`engine.invoke`.
- `@invokta/mcp` publishes capabilities as tools over stdio and secure,
stateless Streamable HTTP.
- `@invokta/tooling` validates composed capabilities and final MCP tool names.
- `@invokta/devtools` provides an engine inspector plus MCP and CLI
workbenches.
- `@invokta/installer` installs and manages local or remote Action Engines in
supported MCP clients.
- `@invokta/deploy` scaffolds and packages HTTP engines and probes deployed
endpoints.
- `create-invokta-engine`, `create-invokta-capability`, and
`create-invokta-capability-library` generate standalone, project-owned
starters.
</details>
## Choose the smallest starter profile
| Profile | Generated execution channels | Choose it when |
| --- | --- | --- |
| `complete` | Direct, CLI, MCP stdio, MCP HTTP | You want the reference project or expect to publish every channel |
| `cli` | Direct and CLI | People or local automation will run commands |
| `mcp-stdio` | Direct and MCP stdio | Local agent clients will start the engine as a child process |
| `mcp-http` | Direct and MCP HTTP | Remote consumers need a shared, authenticated endpoint |
The generated README maps the project and provides a test-first checklist for
replacing the welcome capability. Generated projects also include `AGENTS.md`
and a development skill for compatible coding agents.
Use an official or public GitHub example as the starter:
```sh
npm create invokta-engine@latest my-engine -- --example hello-engine --yes
```
Generate selected capabilities from a bounded local OpenAPI 3.1.x contract:
```sh
npm create invokta-engine@latest my-engine -- --openapi ./openapi.yaml --yes
```
Read the complete
[`create-invokta-engine` reference](./packages/create-invokta-engine/README.md)
for profile contents, automation flags, GitHub imports, and OpenAPI limits.
## Learn from working examples
- [`hello-engine`](./examples/hello-engine/) is the shortest complete path.
- [`support-engine`](./examples/support-engine/) demonstrates dependency
injection, authorization, safe errors, and all four execution channels.
- [`crawl-engine`](./examples/crawl-engine/) puts Firecrawl behind an
engine-owned `WebCrawler` port.
- [`composed-engine`](./examples/composed-engine/) combines local, atomic, and
library capabilities under deliberate effective IDs.
- [`spec-engine`](./examples/spec-engine/) keeps a spec-driven process and its
stage rules inside the domain.
- [`review-engine`](./examples/review-engine/) provides a fail-closed completion
review and adversarial gate.
- [`agent-session-engine`](./examples/agent-session-engine/) stores portable
checkpoints across Cursor, Antigravity, Claude Code, and Codex.
- [`auth-self-hosted-oauth-engine`](./examples/auth-self-hosted-oauth-engine/)
demonstrates a production-oriented OAuth boundary outside the framework
runtime.
The [examples catalog](./apps/docs/src/content/docs/examples/index.mdx) covers
authentication, observability, image generation, Obsidian context, agent
routing, community capability packages, and MCP consumers.
## Create reusable capability packages
When an Action Engine is not the owning project, generate a standalone atomic
capability or a related capability library:
```sh
npm create invokta-capability@latest my-capability
npm create invokta-capability-library@latest my-library
```
## Contribute to Invokta
This repository uses Node.js 24.20.0 and Yarn 1.22.22.
```sh
corepack enable
yarn install --frozen-lockfile --non-interactive
yarn run check
```
Read [CONTRIBUTING.md](./CONTRIBUTING.md) before editing. It covers repository
layout, branch preparation, RED/GREEN/REFACTOR, contract and ADR review,
validation, agent-team coordination, commits, and pull-request evidence.
## Documentation
- [Getting started](./docs/getting-started.md)
- [Documentation index](./docs/README.md)
- [Architecture and contracts](./docs/architecture.md)
- [Scope and limits](./docs/scope-and-limits.md)
- [Architecture decisions](./docs/adr/README.md)
- [Changelog](./CHANGELOG.md)
Invokta is available under the [MIT License](./LICENSE).