An automation framework for MCP servers. Write a YAML script, replay it deterministically, no LLM in the loop.

_{A rondo driving blender-mcp: lay down a plane, drop a cube, stack a sphere, add a cone, then verify the scene. Same YAML, same result, every run. No model involved. Clone blender-mcp-ocarina to run it yourself.}

The MCP ecosystem is already enormous: thousands of servers exposing real services through typed tools, readable resources, and schema-checked contracts, deployed and ready to call. Ocarina is an automation framework for all of it. Write a YAML script that drives tools across one or more servers, pipes values between steps, branches, loops, and retries, and runs the same way every time. No LLM in the loop, so every run is reproducible and costs nothing.

These tools were built to be read by language models, and language models are trained on human language, so the tools read cleanly to people too. A server exposes named contracts like get_issues or query_database, not endpoints you wire up in code. Every server someone built for an AI assistant is one you can drive.

What you write is a playbook: a portable artifact that captures an automation workflow over those servers, with MCP as the wire protocol. You can read it, review it in a pull request, version it, and run it anywhere the servers are reachable. Write it by hand or have an agent generate it. Either way it runs the same on every execution, with no sampling, no tokens, and nothing inferring between the file and the result.

Install

go install github.com/msradam/ocarina@latest

Binaries are available on the releases page. Building from source requires Go 1.26+.

Use

Generate markdown docs for a server:

ocarina docs uvx mcp-server-sqlite --db-path mydb.sqlite
ocarina docs npx -y @modelcontextprotocol/server-github > docs/github.md

Run a rondo:

ocarina play db-audit.yaml
ocarina play db-audit.yaml --dry-run
ocarina play db-audit.yaml -e db=/tmp/other.sqlite  # override a key at runtime

Validate a rondo against the live server without running any tools:

ocarina validate db-audit.yaml

Design principles

• Deterministic. The same rondo produces the same result on every run. No sampling, no randomness.
• Protocol-native. Talks MCP directly via tools/call, resources/read, and resources/list. Works with any compliant server.
• Assertions are first-class. play exits non-zero if any expect: check fails. Rondos work as CI health checks out of the box.
• No credentials in scripts. Server connection and environment variables stay outside the rondo file.
• One rondo, any machine. If the MCP server is available, the rondo runs.

Rondo format

A rondo is a YAML file with three sections.

keys:
  owner: acme
  repo: api

server:
  command: npx
  args: [-y, "@modelcontextprotocol/server-github"]

rondo:
  - name: recent commits
    tool: list_commits
    args:
      owner: "{{owner}}"
      repo: "{{repo}}"
    grab: ".0.sha"
    echo: latest_sha

  - name: commit detail
    tool: get_commit
    args:
      owner: "{{owner}}"
      repo: "{{repo}}"
      sha: "{{latest_sha}}"
    expect:
      contains: "feat"

Step fields

{{env.NAME}} resolves from the process environment and works anywhere {{key}} does.

Coming from Ansible? tasks: is accepted as an alias for rondo:, and register: as an alias for echo:.

Multiple servers

A single rondo can talk to more than one server. Declare them under servers: and set server: on each step. Steps that omit server: use the first entry.

servers:
  time: {command: uvx, args: [mcp-server-time]}
  fetch: {command: uvx, args: [-y, "@modelcontextprotocol/server-fetch"]}

rondo:
  - name: get time
    server: time
    tool: get_current_time
    args: {timezone: UTC}

  - name: fetch page
    server: fetch
    tool: fetch
    args: {url: "https://example.com"}

Output and diff namespace tool names by server (time.get_current_time). The single server: block still works for one-server rondos.

Commands

ocarina docs <command> [args...]: generate markdown documentation for every tool, resource, and resource template a server exposes.

ocarina play <rondo.yaml>: execute each step against the live server.

ocarina validate <rondo.yaml>: check tool names, required args, schema types, and {{key}} data flow without making any calls.

ocarina hum <command> [args...] -- <tool> [key=value ...]: call a single tool and print the result.

ocarina record <output.yaml> <command> [args...]: proxy mode; records every tool call from a live MCP client session into a rondo file.

Server names

Create a .mcp.json (or ~/.mcp.json for credentials) and reference servers by name in rondos and on the command line:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

ocarina hum github -- list_commits owner=pytorch repo=pytorch per_page=1

See mcp.json.example for a starter template. Ocarina also discovers servers from the Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json).

Examples

Working rondos for 50+ MCP servers are in examples/. A selection:

See docs/tested-servers.md for the full list.

Showcases

Standalone repositories you can clone and run, each a real working environment for a different MCP server:

• duckdb-mcp-ocarina: data integrity, migration, and regression tests against a DuckDB database. Clone and run, no credentials.
• chrome-devtools-mcp-ocarina: synthetic web health checks through Google's Chrome DevTools MCP. Fail on a console error or a failed request.
• github-mcp-ocarina: repo governance as tests through the GitHub MCP server. Assert a repo ships a license, is documented, and has history.
• blender-mcp-ocarina: automate and snapshot-test a 3D scene in Blender, an app with no external API at all.

Use in CI

play exits 0 if all expect: assertions pass, non-zero otherwise. Drop a rondo into any CI pipeline:

- name: Database health check
  run: ocarina play rondos/db-audit.yaml

A composite GitHub Action installs Ocarina and replays a rondo:

- uses: msradam/ocarina@v1
  with:
    rondo: tests/mcp-smoke.yaml

See action.yml and .github/workflows/example.yml.

License

MIT. Whistle icon by Alessio Capponi from Noun Project (CC BY 3.0).