> ## Documentation Index
> Fetch the complete documentation index at: https://yukta.infenia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI assistant

> Connect Claude Code, Codex, Antigravity, Cursor, VS Code, Windsurf, OpenCode or any MCP client to Yukta's /mcp endpoint with the right API key and role, and install the skill that teaches it the tools.

<dl />

**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](https://yukta.infenia.com/api/overview.md) and [CLI](https://yukta.infenia.com/reference/cli.md) 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:

```bash theme={"system"}
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

**1. 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:

```bash theme={"system"}
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`.

**2. Connect your client**

> [tab] Claude Code
>
> ```bash theme={"system"}
> claude mcp add --transport http yukta http://localhost:9858/mcp \
>   --header "Authorization: Bearer change-me"
> ```
>
> Leave out `--header` when the server has no keys.

> [tab] Codex
>
> ```bash theme={"system"}
> 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.

> [tab] Antigravity
>
> In `~/.gemini/config/mcp_config.json` (Antigravity wants `serverUrl`, not `url`):
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "yukta": {
>       "serverUrl": "http://localhost:9858/mcp",
>       "headers": { "Authorization": "Bearer change-me" }
>     }
>   }
> }
> ```

> [tab] Any MCP client
>
> Any client needs the same two values, a URL and optional headers. A typical configuration file:
>
> ```json theme={"system"}
> {
>   "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.

**3. 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](https://github.com/infenia/yukta/tree/main/skills/yukta-workflows) (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 |

```bash theme={"system"}
mkdir -p .claude/skills && cp -r skills/yukta-workflows .claude/skills/
```

**4. 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:

```json theme={"system"}
{ "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](https://yukta.infenia.com/guides/supervise/route-input-requests.md).
* **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.

> [!WARNING]
>
> 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.

## Related

* [MCP tools reference](https://yukta.infenia.com/reference/mcp-tools.md) for every tool, role and argument.
* [AI-assisted configuration](https://yukta.infenia.com/concepts/ai-assisted-configuration.md) for what an assistant can and cannot do.
* [Secure the server](https://yukta.infenia.com/guides/operate/secure-the-server.md) and [Security reference](https://yukta.infenia.com/reference/security.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.