version: "1.0.0" name: ballet description: Author and operate Ballet workspaces — playbooks, agents, skills, HTTP tools, connectors, secrets, and persistent data tables — over the Ballet MCP server. Use when the user mentions Ballet, a Ballet playbook, or app.ballet.dev.

Ballet

Ballet is an agent operations platform. This plugin connects Grok Build to a Ballet workspace through the ballet MCP server at https://api.ballet.dev/mcp.

The server ships its own authoring guides. Do not guess at Ballet's data model or SDK surface — read the guide for the artifact you are about to create.

First call in any Ballet task

get_builder_guide({ topics: ["overview"] })

Then read the guide for the specific artifact: playbook, agent, tool, skill, connector, or sdk. list_builder_guides returns the full catalog.

Authoring order

1. Read the guide for the artifact type.
2. Discover before creating. list_integrations({ query }) before writing an HTTP

tool — native vendors are already registered and should be used through metaphor.integration rather than a hand-rolled tool. list_models before create_agent. list_secrets for credential names. list_playbooks, list_agents, list_tools, list_skills to avoid duplicating existing work.

1. Create dependencies first — secrets, tools, skills, agents, and MCP servers must

exist before a step references them.

1. Create or update the playbook with a complete steps array.
2. Verify, publish, then run. verify_playbook until clean, publish_playbook so

webhooks and runs pin to the live version, then run_playbook. Diagnose failures with get_run and get_run_steps.

Rules

• Never inline a credential in step code, a tool definition, or a playbook. Store it

with create_secret / update_secret and reference it by name. list_secrets returns names only, never values.

• Call verify_playbook before run_playbook.
• Do not invent metaphor.* SDK methods — load the sdk guide.
• Treat delete_playbook, delete_agent, delete_tool, delete_skill,

delete_mcp_server, delete_data_table, and delete_data_table_record as destructive. Confirm with the user before calling them.

• run_playbook executes real work against connected systems. Confirm before the first

run of a playbook the user has not run before.

Product documentation

For questions the MCP guides do not answer — connectors, webhooks, run history, suspend/resume, REST equivalents — read <https://docs.ballet.dev>.

Every article is available as agent-readable markdown: append .md to any article URL, or send Accept: text/markdown. The index of all articles is at <https://docs.ballet.dev/llms.txt>.

Authentication

The server advertises OAuth 2.1 metadata at /.well-known/oauth-protected-resource. On the first tool call the MCP client performs dynamic client registration and opens a browser consent page. There is no API key to paste. If a call returns 401, the token expired or was revoked — re-run the OAuth flow rather than retrying.