Jetty — AI/ML Workflows for Any Agent

Build, run, and monitor AI/ML workflows on Jetty from any AI coding tool. Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Zed, Gemini CLI, Codex CLI, and any MCP-compatible agent.

Quick Start (Claude Code)

claude plugin marketplace add jettyio/jettyio-skills
claude plugin install jetty@jetty

Then run /jetty-setup to create an account, configure your API key, and run your first workflow in under 5 minutes.

Related MCP server: multivon-mcp

Install in Your Tool

Jetty uses the Model Context Protocol (MCP) to connect to your agent. Pick your tool below.

The same tools are available to in-browser agents through WebMCP — jetty.io registers them on navigator.modelContext for signed-in users, and any site can do the same with jetty-mcp-server/webmcp (see mcp-server/README.md).

Claude Code

Plugin (recommended) — includes guided setup wizard, workflow skills, and MCP tools:

claude plugin marketplace add jettyio/jettyio-skills
claude plugin install jetty@jetty

Then run /jetty-setup to get started interactively.

MCP server only:

claude mcp add jetty -- npx -y jetty-mcp-server

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "jetty": {
      "command": "npx",
      "args": ["-y", "jetty-mcp-server"],
      "env": { "JETTY_API_TOKEN": "mlc_your_token" }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "jetty": {
      "command": "npx",
      "args": ["-y", "jetty-mcp-server"],
      "env": { "JETTY_API_TOKEN": "mlc_your_token" }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "jetty": {
      "command": "npx",
      "args": ["-y", "jetty-mcp-server"],
      "env": { "JETTY_API_TOKEN": "mlc_your_token" }
    }
  }
}

Or run MCP: Add Server from the Command Palette.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "jetty": {
      "command": "npx",
      "args": ["-y", "jetty-mcp-server"],
      "env": { "JETTY_API_TOKEN": "mlc_your_token" }
    }
  }
}

Zed

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "jetty": {
      "command": {
        "path": "npx",
        "args": ["-y", "jetty-mcp-server"],
        "env": { "JETTY_API_TOKEN": "mlc_your_token" }
      }
    }
  }
}

Gemini CLI

gemini extensions install https://github.com/jettyio/jettyio-skills

During installation, you'll be prompted for your Jetty API token. The extension registers the MCP server and loads context automatically.

To install from a local clone instead:

gemini extensions install --path /path/to/jettyio-skills

Antigravity

Antigravity (Google's agentic IDE) loads skills from ~/.gemini/antigravity/skills/ and reads MCP servers from ~/.gemini/antigravity/mcp_config.json. It does not auto-install from any of the manifests in this repo — file-drop only.

Skills: clone the repo and either symlink or copy each skill directory you want into Antigravity's skill path. For example:

git clone https://github.com/jettyio/jettyio-skills.git
mkdir -p ~/.gemini/antigravity/skills
ln -s "$(pwd)/jettyio-skills/skills/jetty-setup"     ~/.gemini/antigravity/skills/jetty-setup
ln -s "$(pwd)/jettyio-skills/skills/create-runbook"  ~/.gemini/antigravity/skills/create-runbook
ln -s "$(pwd)/jettyio-skills/skills/optimize-runbook" ~/.gemini/antigravity/skills/optimize-runbook
ln -s "$(pwd)/jettyio-skills/skills/jetty"           ~/.gemini/antigravity/skills/jetty

MCP server: add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "jetty": {
      "command": "npx",
      "args": ["-y", "jetty-mcp-server"],
      "env": { "JETTY_API_TOKEN": "mlc_your_token" }
    }
  }
}

Restart Antigravity after editing the config. Skills trigger on natural language (slash commands aren't auto-discovered for skills) — say "set up Jetty" or "create a runbook for X" and the agent will pick the right skill via the description in its frontmatter.

Codex CLI

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "jetty": {
      "command": "npx",
      "args": ["-y", "jetty-mcp-server"],
      "env": { "JETTY_API_TOKEN": "mlc_your_token" }
    }
  }
}

Any Other MCP Client

JETTY_API_TOKEN=mlc_your_token npx -y jetty-mcp-server

The server communicates over stdio using the MCP protocol.

Get Your API Token

1. Sign up at jetty.io

2. Go to Settings → API Tokens

3. Create a token (starts with mlc_)

4. Add it to your tool's config as shown above

First-Time Setup

Once connected, ask your agent to help you get started. This works in any MCP-connected tool — just paste the prompt below into your agent's chat:

Set up Jetty for me. List my collections, then deploy the cute-feline-detector demo workflow using the create-task tool with this workflow JSON. Then run it with run-workflow using the prompt "a fluffy orange tabby cat sitting in a sunbeam". Poll list-trajectories until it completes, then show me the results with get-trajectory.

Before running the demo, store your AI provider key in your collection's environment variables. Ask your agent:

Use the Jetty get-collection tool to check my collection's environment variables. I need to add my OpenAI API key (or Gemini API key) so workflows can use it.

Claude Code users: Just run /jetty-setup instead — the guided wizard handles all of this automatically.

Available MCP Tools

Once connected, your agent has access to 16 tools:

Claude Code Skills

The plugin adds three skills for richer Claude Code integration:

/jetty-setup — Guided Onboarding

Interactive wizard that handles account creation, API key storage, provider selection (OpenAI or Gemini), and runs a demo workflow — all in under 5 minutes.

/jetty — Natural Language Workflow Management

/jetty list collections
/jetty list tasks in my-project
/jetty run my-project/my-task with prompt="Hello, world!"
/jetty show the last trajectory for my-project/my-task
/jetty create a task called test-echo in my-project using text_echo
/jetty add label quality=high to trajectory abc123 in my-project/my-task

/jetty create-runbook — Guided Runbook Creator

Interactive wizard that walks you through building a runbook step by step — choose an evaluation pattern, define parameters and secrets, and generate a complete runbook ready to run.

Runbooks

A runbook is a structured markdown document that tells a coding agent how to accomplish a complex, multi-step task with built-in evaluation loops and quality gates. Think of it as an executable playbook: your agent reads the runbook, executes each step, evaluates its own output, and iterates until quality criteria are met.

Key Features

• Outcome-oriented — defines what must be true when done, not just procedure steps

• Self-evaluating — built-in evaluate → refine → re-evaluate loops (max 3 rounds)

• Parameterized — uses {{param}} template variables for reuse across inputs and environments

• Secrets-aware — declares sensitive credentials in frontmatter, resolved securely at runtime

• Versioned — carries a semantic version in YAML frontmatter for reproducibility

Evaluation Patterns

Runbook Structure

Every runbook follows a mandatory structure:

1. Frontmatter — version, evaluation type, secrets declarations

2. Objective — what the runbook accomplishes (2–5 sentences)

3. Output Manifest — files the agent must create

4. Parameters — configurable inputs with defaults

5. Dependencies — workflows, APIs, credentials, packages

6. Steps — sequential processing (API calls, transformations, etc.)

7. Evaluation — status table (programmatic) or rubric scoring

8. Iteration — up to 3 refinement rounds with common-fix guidance

9. Code Checks — one ### <id> — <name> heading plus one fenced block each: a bash command or yaml built-in that Jetty runs after the agent exits (the agent runs it instead when the fence says executor=agent), or an agent instruction the agent runs; a note Jetty appends at run time names which ids each side runs, and without that note the agent runs every check itself and records each in the report; a failure fails the run

10. Checklist — - [ ] conditions confirmed by inspection; a failed item fails the run

11. Validation Report — validation_report.json v2: one typed checks[] entry per step, checklist item, agent check and judge; Jetty appends its own command-check entries and computes the verdict

Runbooks written before Code Checks existed (a validation report with stages and overall_passed but no checks, and a Final Checklist step) still run unchanged: Jetty reads their report as v1 and takes its own overall_passed as the verdict. Running /create-runbook on one offers a migration.

Getting Started with Runbooks

Claude Code users: Run /jetty create-runbook for a guided wizard that generates a complete runbook from starter templates.

For full documentation, see docs/PRD-runbooks.md.

Secrets Management

Jetty provides secure handling of API keys and credentials so they never leak into logs, trajectories, or workflow outputs.

How Secrets Work

Secrets are declared in runbook frontmatter and resolved at runtime through a 3-level fallback:

1. OS environment variable matching the env field

2. .env file in the runbook directory (should be .gitignored)

3. Interactive prompt (if required: true and not found above)

When running on Jetty, secrets resolve from your collection's environment variables — set once, available to all workflows in that collection.

Declaring Secrets in a Runbook

secrets:
  OPENAI_API_KEY:
    env: OPENAI_API_KEY
    description: "OpenAI API key for LLM calls"
    required: true
  LANGFUSE_SECRET_KEY:
    env: LANGFUSE_SECRET_KEY
    description: "Langfuse API secret key"
    required: false

Reference secrets in runbook steps as {{secrets.OPENAI_API_KEY}} — distinct from regular {{params}}.

MCP Tools for Secrets

Security Guarantees

• Secrets are never stored in init_params, trajectories, or output files

• The secret_params API field merges credentials into the runtime environment without persisting them

• Collection environment variables are stored server-side. By default, GET /api/v1/collections/{COLLECTION}/environment returns values in plain text to the holder of a collection-owner token. Treat that token like a root credential. To make the endpoint redact specific keys, set the collection's redacted_param_keys (it defaults to null, i.e. no redaction)

Workflow Templates

Ready-to-use templates are in skills/jetty/templates/:

Use the create-task MCP tool to deploy any template to your collection.

Shell Functions (Standalone CLI)

For direct terminal usage without any AI tool:

export JETTY_API_TOKEN="mlc_your_token_here"
source path/to/skills/jetty/jetty-cli.sh

jetty_health                                    # Check connectivity
jetty_collections                               # List collections
jetty_run_sync my-project my-task '{"prompt": "Hello"}'  # Run a workflow
jetty_trajectories my-project my-task           # View execution history
jetty_help                                      # Full command reference

How It Works

Jetty runs AI/ML workflows defined as JSON pipelines. Each workflow has:

• init_params — Input parameters (e.g., a prompt)

• step_configs — Pipeline steps (e.g., LLM call → image generation → judge)

• steps — Execution order

Results are stored as trajectories with full step-by-step outputs, downloadable files, and labeling support.

Platform

Prerequisites

• Node.js 18+ (for the MCP server via npx)

• A Jetty API token (get one here)

• An AI provider API key for workflow steps (OpenAI for DALL-E/GPT, or Google Gemini)

• For runbooks: an agent runtime API key (Anthropic, OpenAI, or Google — see agent reference)

Agent Compatibility

For agents without skill support, see QUICKSTART.md.

Documentation

• AI Tool Integrations

• API Reference

• Workflow Building Guide

• Known Gotchas

Troubleshooting

Releasing

The version number is hardcoded in several places. When cutting a release, bump all of them together:

• .claude-plugin/plugin.json

• .claude-plugin/marketplace.json

• .codex-plugin/plugin.json

• .opencode-plugin/plugin.json

• gemini-extension.json

• skills/jetty-setup/scripts/jetty_simulate.py (CLIENT string)

• skills/jetty/SKILL.md (launch banner)

• skills/jetty-setup/SKILL.md (launch banner)

License

MIT — see LICENSE for details.