Connect an AI assistant

Use this when you want an assistant to build or run workflows for you (“run the release checks and tell me what failed”). For a person or a script, the REST API and CLI cover the same operations. Prerequisites: a server on http://localhost:9858. The MCP server is at /mcp on the same address and port, over streamable HTTP in stateless mode (no MCP session to keep, no standard-input transport).

The fast way: one command

yukta-cli agents install finds the AI agents on your machine and, for each, registers the Yukta MCP server in the agent’s own configuration and installs the Yukta skills. The installer script offers it at the end of an install; run it yourself any time:

yukta-cli agents list                 # the agents found, and which are connected
yukta-cli agents install              # connect every agent found
yukta-cli agents install --agent codex,cursor --dry-run   # see what would change first
yukta-cli agents uninstall --all      # remove exactly what install added

Agent (`--agent`)	MCP server goes to	Skills go to
Claude Code (`claude`)	the `yukta` plugin (MCP, skills and a live pane); `claude mcp add --scope user` for another server or a key	plugin; `~/.claude/skills`
Codex (`codex`)	`codex mcp add`, else `~/.codex/config.toml`	`~/.codex/skills`
Antigravity (`antigravity`)	`~/.gemini/config/mcp_config.json`	`~/.gemini/antigravity/skills`, `~/.gemini/skills`
Cursor (`cursor`)	`~/.cursor/mcp.json`	`~/.cursor/skills`
VS Code Copilot (`vscode`)	the user `mcp.json` of VS Code	`~/.copilot/skills`
Windsurf (`windsurf`)	`~/.codeium/windsurf/mcp_config.json`	`~/.codeium/windsurf/skills`
OpenCode (`opencode`)	`~/.config/opencode/opencode.json`	`~/.config/opencode/skills`
Any agent that reads `~/.agents/skills` (`generic`)	not applicable	`~/.agents/skills`

It talks to the server at --url (default http://localhost:9858). For a server with API keys, add --token-file <file>, or --token-env VAR so that agents which support it read the key from an environment variable instead of a file. Without either, a key is written into the agent’s configuration file, which then is private to you (mode 0600). What it never does: it changes only a yukta entry in each agent’s configuration and the skill folders yukta-workflows and yukta-supervisor; it keeps the first original of each file as <file>.yukta-bak; and it leaves a file it cannot parse as plain JSON (one with comments, say) alone and prints the entry to add by hand. Everything it did is recorded in agents.json in your user config folder, which agents uninstall reads. After upgrading yukta-cli, yukta-cli agents install --refresh updates the skills. The steps below do the same by hand, for an agent that is not in the list or a setup of your own.

Steps

Pick a key and a role

/mcp uses the same yukta.api-keys as REST. Send the key as Authorization: Bearer <key> or X-API-Key: <key>. With no key configured, the server accepts loopback only, which means any process on the machine, including one that can call create_session and so install workflows that run code. Set a key whenever the machine is shared.Give the assistant the lowest role that does its job:

Role	The assistant can
`VIEWER`	Look and debug: list and read sessions, workflows, runs, logs, results, supervisors, pending inputs
`OPERATOR`	Everything `VIEWER` can, plus start and steer runs, answer and escalate input requests, roll back versions
`ADMIN`	Everything, including `create_session`, `delete_session`, supervisors and credentials

Add a key when you start the server, optionally limited to some sessions:

YUKTA_API_KEYS_1_NAME=assistant \
YUKTA_API_KEYS_1_KEY=change-me \
YUKTA_API_KEYS_1_ROLE=OPERATOR \
YUKTA_API_KEYS_1_SESSIONS=team-a,team-b \
yukta

A key limited to sessions can call a tool only with a sessionId that names one of its sessions. Commands it sends are audited as key:assistant.

Connect your client

Claude Code
Codex
Antigravity
Any MCP client

claude mcp add --transport http yukta http://localhost:9858/mcp \
  --header "Authorization: Bearer change-me"

Leave out --header when the server has no keys.

export YUKTA_TOKEN=change-me
codex mcp add yukta --url http://localhost:9858/mcp --bearer-token-env-var YUKTA_TOKEN

Leave out --bearer-token-env-var when the server has no keys.

In ~/.gemini/config/mcp_config.json (Antigravity wants serverUrl, not url):

{
  "mcpServers": {
    "yukta": {
      "serverUrl": "http://localhost:9858/mcp",
      "headers": { "Authorization": "Bearer change-me" }
    }
  }
}

Any client needs the same two values, a URL and optional headers. A typical configuration file:

{
  "mcpServers": {
    "yukta": {
      "type": "http",
      "url": "http://localhost:9858/mcp",
      "headers": { "Authorization": "Bearer change-me" }
    }
  }
}

The exact key names (type, url, httpUrl) differ between clients; use the one your client documents for a streamable HTTP server.

Install the skill

The tools are enough for an agent that already knows Yukta. The yukta-workflows skill gives any agent the working knowledge: call whoami first, which role each tool needs, which actions to ask you about first (replacing or deleting a session, force-stopping runs, rolling back, changing scheduler limits, answering an approval) and recipes to create, run, watch, debug and steer. Copy the folder (one SKILL.md) to where your agent reads skills:

Agent	Folder
Claude Code	`.claude/skills/yukta-workflows/` in a project, or `~/.claude/skills/yukta-workflows/` for every project
Codex	`~/.codex/skills/yukta-workflows/`
Antigravity	`~/.gemini/antigravity/skills/yukta-workflows/` (or `~/.gemini/skills/`)
Cursor	`~/.cursor/skills/yukta-workflows/`
VS Code Copilot	`~/.copilot/skills/yukta-workflows/`
Other agents that read `.agents/skills/`	`.agents/skills/yukta-workflows/` or `~/.agents/skills/yukta-workflows/`
An agent without skills	Paste the body of `SKILL.md` into its instructions or rules file

mkdir -p .claude/skills && cp -r skills/yukta-workflows .claude/skills/

Try it

Ask the assistant: “Call whoami, then list the sessions on Yukta.”

Verify it worked

claude mcp list (or codex mcp list) shows yukta as connected, and the assistant’s first call returns something like:

{ "authenticated": true, "keyName": "assistant", "role": "OPERATOR", "sessions": ["team-a", "team-b"],
  "authEnabled": true,
  "permissions": { "startRuns": true, "controlRuns": true, "editSessions": false,
                   "deleteSessions": false, "changeLimits": false, "sendCommands": true } }

list_sessions then answers with your sessions. A tool the role does not allow is refused with HTTP 403 (a body above 1 MB with 413). When keys are configured, a missing or wrong key is refused with 401. To exercise a full loop, ask: “Create a session with a workflow that greets a name, start it for Ada and show me the result.” The assistant reads get_session_creation_instructions and list_plugins, calls create_session (an ADMIN tool: with an OPERATOR key it should tell you it needs a higher role), start_workflow, then get_workflow_status and get_execution_result.

Variations

start_workflow takes no payload. It starts with an empty trigger payload. To start with input, use REST or the CLI, or a workflow that starts from a CONSTANT_SOURCE.
Let it read logs and outputs. get_execution_logs (with afterCursor to read only new lines) and get_node_output (tail, head, grep) keep the answers small.
Run supervisors and answer questions. An assistant with ADMIN can manage supervisors (save_supervisor, set_assignments, replay_supervisor); one with OPERATOR can answer_input. The risk rule still applies: an OPERATOR key counts as a person. See Route input requests.
Prompts and resources. The server offers prompts debug-workflow and create-session-config and resources yukta://overview and yukta://architecture; clients that support them list them.

Never hand an assistant an ADMIN key you would not hand a colleague. create_session defines workflows that can run processes and reach external systems.

MCP tools reference for every tool, role and argument.
AI-assisted configuration for what an assistant can and cannot do.
Secure the server and Security reference.

Build workflows

Work with AI

Supervise runs

Run and operate

Extend

Connect an AI assistant

The fast way: one command

Steps

Verify it worked

Variations

The fast way: one command

Steps

Verify it worked

Variations

Related