--- title: "Clarive Skill for AI Agents | Clarive" description: "An Agent Skill that teaches Claude Code, GitHub Copilot, Cursor and Codex to use Clarive's MCP server and the clarive command line, with install steps and a prompt to get started." url: "https://clarive.com/mcp-skill" --- # A Clarive skill for your AI agent Clarive 7.22.2 publishes every operation of its API as an MCP tool. This skill teaches Claude Code, GitHub Copilot, Cursor and Codex to use those tools well: to look an operation up before calling it, to follow a job instead of waiting on it and to ask before changing anything. [Download SKILL.md](https://clarive.com/files/skills/clarive/SKILL.md) [ZIP for Claude Desktop and claude.ai](https://clarive.com/files/skills/clarive.zip) One Markdown file of 10 KB, also as a ZIP for Claude. Needs Clarive 7.22.2 or later. ## Paste this prompt into your favorite agent It asks for your server's address and has you log in yourself. Then it connects the agent through the [clarive command line](https://clarive.com/install#cli), read-only, installs the skill and runs a first check that changes nothing. The prompt holds no secrets, and no token ends up in a configuration file. ``` Help me connect you to our Clarive server and learn to use it. Go one step at a time: 1. Ask me for our Clarive server's URL (for example https://clarive.example.com). Never ask me for a password or a token, and never print one. 2. Run `clarive version` to check that the clarive command line is installed. If it isn't, send me to https://clarive.com/install#cli and wait until I say it's done. 3. Ask me to log in myself, in my own terminal, read-only for this first look: `clarive login --url --read-only`. When I say it worked, run `clarive whoami` and tell me which user you see. 4. Add Clarive to your MCP configuration as a server named "clarive" that runs the command `clarive mcp --read-only --namespaces api,auth,job,topic`. That bridge reads my login, so no token goes into any file, read-only is enough for now and the short list of tools fits every client. The setup for each client is at https://clarive.com/mcp-skill.md. If you can't edit your own configuration, tell me exactly what to add and where. 5. Install the Clarive skill: save https://clarive.com/files/skills/clarive/SKILL.md as clarive/SKILL.md in your skills folder (~/.claude/skills in Claude Code, ~/.copilot/skills in GitHub Copilot, ~/.cursor/skills in Cursor, ~/.agents/skills in Codex). If you don't support skills, show me how you would add its instructions to this project's AGENTS.md, and wait for my yes. 6. Tell me if I have to restart or reload you to pick up the server and the skill. 7. Then, as a first read-only check, call the Clarive tools auth_whoami and topic_search (assigned_to_me and only_open), and show my open topics as a short table of mid, title and status. ``` ## Clarive's tools, used the way they were built An agent connected to Clarive works as the person whose token it holds, with that person's roles. The skill is about using that access carefully. - **Look it up before guessing** `api_search` finds the operation for a task and `api_describe` gives its parameters, so the agent never invents one. - **Mids, pages and totals** Topics, jobs and resources go by their mid. Lists come a page at a time, and a count is the `total` of a one-item page. - **Jobs return at once** `job_create` comes straight back. The agent follows the job with `job_get` and reads new log entries with `job_logs` and its cursor. - **Rules as HCL, never overwritten** Read with `hcl_get_rule`, check with `hcl_check`, save with the version it read, so a colleague's newer change comes back as a conflict. - **Read first, ask before changing** The agent shows what will change and asks before anything destructive, and before any command that runs on a real server. - **No secrets in the chat** It never repeats a token or asks for one. People run `clarive login` themselves, and masked values stay masked. ## One file, in each agent's skills folder The skill follows the open Agent Skills format: a folder named `clarive` that holds `SKILL.md`. Restart the agent afterward so it finds it. ### Claude Code For every project, in your home directory. For one repository, commit it to .claude/skills/clarive/ instead. ``` mkdir -p ~/.claude/skills/clarive curl -fsSL -o ~/.claude/skills/clarive/SKILL.md \ https://clarive.com/files/skills/clarive/SKILL.md ``` ### GitHub Copilot in VS Code For one repository in .github/skills/clarive/, or for you in \~/.copilot/skills/clarive/. ``` mkdir -p .github/skills/clarive curl -fsSL -o .github/skills/clarive/SKILL.md \ https://clarive.com/files/skills/clarive/SKILL.md ``` ### Cursor For one project in .cursor/skills/clarive/, or for you in \~/.cursor/skills/clarive/. ``` mkdir -p ~/.cursor/skills/clarive curl -fsSL -o ~/.cursor/skills/clarive/SKILL.md \ https://clarive.com/files/skills/clarive/SKILL.md ``` ### Codex For you in \~/.agents/skills/clarive/, or for one repository in .agents/skills/clarive/. ``` mkdir -p ~/.agents/skills/clarive curl -fsSL -o ~/.agents/skills/clarive/SKILL.md \ https://clarive.com/files/skills/clarive/SKILL.md ``` ### Claude Desktop and claude.ai Download the [ZIP](https://clarive.com/files/skills/clarive.zip). In Claude, open Customize, then Skills, press +, choose Create skill and then Upload a skill. On Enterprise plans an owner has to turn on Skills and code execution for the organization first. ### Agents without skills Copy everything below the frontmatter (the block between the two `---` lines) into the instructions file the agent reads, such as `AGENTS.md` or `.github/copilot-instructions.md`. ## The bridge, or straight over HTTP `clarive mcp` runs as a local MCP server and forwards each call to Clarive with the token of your `clarive login`, so no token sits in a configuration file. Clients that speak Streamable HTTP can also connect to `/mcp` directly with a bearer token. `--compact` and `--namespaces api,auth,job,topic` narrow what the agent gets, and `--read-only` after `mcp`makes a first connection that can't change anything, as the prompt does. ### Claude Code Through the CLI bridge ``` clarive login --url https://clarive.example.com claude mcp add clarive -- clarive mcp ``` ### GitHub Copilot in VS Code and Copilot CLI \~/.copilot/mcp-config.json for you, or .mcp.json at the root of a repository. VS Code takes at most 128 tools in a request, hence --namespaces. Over HTTP, the header is "Authorization": "Bearer ${CLARIVE\_TOKEN}", with the token in an environment variable. ``` { "mcpServers": { "clarive": { "type": "stdio", "command": "clarive", "args": ["mcp", "--namespaces", "api,auth,job,topic"], "tools": ["*"] } } } ``` ### Cursor \~/.cursor/mcp.json, or .cursor/mcp.json for one project ``` { "mcpServers": { "clarive": { "command": "clarive", "args": ["mcp"] } } } ``` ### Codex \~/.codex/config.toml ``` [mcp_servers.clarive] command = "clarive" args = ["mcp"] ``` ### Claude Desktop claude\_desktop\_config.json (Settings, Developer, Edit Config), with the full path of clarive ``` { "mcpServers": { "clarive": { "command": "/usr/local/bin/clarive", "args": ["mcp"] } } } ``` ### Any Streamable HTTP client The endpoint and the one header Clarive accepts ``` https://clarive.example.com/mcp Authorization: Bearer ``` Clarive accepts personal access tokens only, as `Authorization: Bearer`. A client that can only use OAuth for remote servers needs the bridge. The [connection guide](https://docs.clarive.com/en/mcp/connect/) covers tokens, profiles and the options in full. ## Read it before you install it A skill is instructions your agent will follow, so it is worth reading first. This is the whole of it. SKILL.md ``` --- name: clarive description: Work with a Clarive DevOps server through its MCP tools or the clarive CLI. Covers topics and changesets, deployment jobs and their logs, pipeline rules as HCL, resources (servers, CIs), approvals, environments, users and roles. Use when the user mentions Clarive, a topic or changeset mid, a job such as JOB-00012, a Clarive rule, an environment such as QA or PROD, or asks to deploy, promote, approve, roll back or explain a failure in Clarive. compatibility: Needs Clarive 7.22.2 or later, reached through its MCP server (https:///mcp, or the local bridge `clarive mcp`) or the `clarive` CLI. metadata: publisher: clarive.com version: "1.0" --- # Clarive Clarive publishes one set of operations, the Clarive API, three ways: REST at `/api/v2`, an MCP server at `/mcp` and the `clarive` CLI. They share names, parameters, permissions and errors. The operation `job.logs` is the MCP tool `job_logs` and the command `clarive job logs`. Everything runs as the user who owns the token, with that user's roles, exactly as in the web interface. ## Which door you have - **MCP tools** are named `_`: `topic_search`, `job_get`, `hcl_get_rule`. The list only holds what this user may call. A read token, or the server's `read_only` option, leaves only tools that change nothing. - **Compact mode** leaves four tools: `api_namespaces`, `api_search`, `api_describe` and `clarive_call`. Call any operation through `clarive_call` with `op` (the dotted name, `job.list`) and `params` (an object). - **Namespaces.** A server connected with the `namespaces` option lists only those namespaces. `api_search` and `api_describe` stay only when `api` is one of them. If a tool you need is missing, tell the user which namespace holds it. - **The CLI** is `clarive [positional args] [--flags]`, with underscores turned into dashes (`clarive job list-transitions`). Piped output is JSON. Add `-o json` in scripts anyway. `clarive api call job.list limit=5` calls any operation by name. If several Clarive servers are connected (for example `clarive-test` and `clarive-prod`), say which one you are reading from every time, and never copy a change from one to the other without the user asking. ## Find the operation before you guess 1. `api_search` with a few words ("job log", "topic status"). It can filter by `namespace` and by `kind` (`read`, `write`, `destructive`). CLI: `clarive api search job log`. 2. `api_describe` with the dotted name (`job.logs`) before the first call of an operation you have not used in this session. It gives the parameters, their schema, the kind and the permission. CLI: `clarive api describe job.logs`. 3. Call it with the parameter names from the schema. Never invent one. An `invalid_params` error lists every wrong parameter. Read it, fix them all and try once more. A `not_found` for an operation name in `clarive_call` suggests operations from the same namespace or with a similar name. ## Identifiers and lists - Topics (changesets, releases, issues), jobs and resources go by their `mid`. Jobs also go by name (`JOB-00012`). Statuses, categories, projects and labels go by name or id. Environments are `bl` names: `QA`, `PROD`. - `ci_get_many` reads several mids of any classes in one call. - `topic_search` takes `assigned_to_me`, `assigned_to`, `created_by`, `only_open`, `categories`, `statuses`, `projects` and a text `query`. - Lists answer `{items, total, skip, limit}`. The default page is 50 and the most is 1000. For a count, ask for `limit: 1` and read `total`. Page with `skip`. - Answers over 256 KB are cut with a note. Ask for less: a smaller `limit`, a filter, one page at a time, `levels: ["error"]` on a log. ## Jobs return at once, then you poll - Before deploying: `job_list_transitions` (where a changeset may go), `calendar_check_window` with the changesets (when the environment is open for them; without changesets it reads only the global calendars) and `job_estimate`. - `job_create` with `bl` and `changesets` runs the CHECK and INIT steps and returns. It does not wait for the deployment. - Follow a job with `job_get` for its status. Read its log with `job_logs`, passing back the `next_since_id` of the previous answer as `since_id`. Stop when `finished` is true and `has_more` is false. Leave a few seconds between polls and report progress in a line or two, not the whole log. - With the CLI, `clarive job create QA 101 --wait --logs` and `clarive job wait JOB-00012` exit 0 when the job finished OK and 9 when it ended any other way. `clarive job logs JOB-00012 --follow` prints the log until the job ends. - `server_execute`, `ci_run_service` and `rule_run` do wait for the command, within their own timeout. - A job scheduled outside every deployment window of its environment is refused with `forbidden`. Pick a time inside a window. `no_cal: true` skips the calendar, needs its own permission and a reason in `comments`. Never pass it unless the user asks for an out-of-window job and gives the reason. An environment with no calendar at all counts as outside, and so does a window of the other `window_type` (N normal, U urgent). The error says which. ## Why a job failed 1. `job_get` for its status, step and environment. 2. `job_get_root_cause`. It returns what Clarive's Root Cause resources matched in the log after the job ended. It can be empty when none match or the analysis daemon is off. Empty is not the same as "no problem". 3. `job_logs` with `levels: ["error"]` (then `["warn", "error"]`), and `job_get_summary` for each service's result by step. 4. `job_runner_log` for the raw output of the process, when the user has the permission for it. Recovery changes things, so propose it and wait for a yes: `job_trap_action` (`retry`, `skip`, `pause` or `error`) for a job that is TRAPPED, and `job_restart` with a `step` for a job that has ended. ## Topics and their statuses - `topic_list_next_statuses` shows where a topic may go. Then `topic_change_status` with `mid` and `status`. If the status asked for is not in that list, call `topic_explain_status_change` instead of trying. - If a change is refused, call `topic_explain_status_change`. It returns the reasons with codes (`no_transition`, `missing_role`, `deploy_only`, `required_field` and others) and changes nothing. Report them. Do not try other statuses or fields to get around a refusal. ## Rules are HCL text: read, check, save with base_version 1. `hcl_get_rule` with the rule's id or name. Keep its `version_id`. 2. Edit the text. Write HCL, never rulebook YAML. `rule_describe_operation` gives one operation's fields, defaults and HCL spelling. `rule_list_operations` lists the operations. 3. `hcl_check` with the text and `rule` for syntax, meaning, compile and the rule critic. Fix every error it reports by line and column. Read `ok` and `compiled` in the answer: with a read token, or without the right to modify that rule, nothing is compiled, so say so instead of reporting a clean check. 4. Show the user the change as a diff and wait for a yes. 5. `hcl_save_rule` with `hcl`, `rule` and `base_version` set to the `version_id` you read. A `conflict` means someone saved in between. Read the rule again, redo the change on the new text and show it again. Never pass `overwrite: true` unless the user says so after seeing the conflict. Every save is a new version. `rule_list_versions`, `rule_diff_versions` and `rule_restore_version` show and undo changes. CLI: `clarive rule edit 42` does the whole round trip, and `clarive rule get 42 --hcl` prints the text. Never put a password, token or key in an `sh` step or any command line. The job log keeps the command line with its variables expanded. ## Read first, ask before you change anything - Read the current state before any write and tell the user what will change. - Each tool says whether it is read-only or destructive (`api_describe` shows the `kind`). Call write tools only for what the user asked. Ask before every destructive tool, which deletes or overwrites, even when you were told to "clean up". - Ask first, every time, before tools that act on real machines or bypass review, whatever their kind: `server_execute`, `worker_execute`, `file_put`, `file_write`, `file_sync`, `file_delete`, `rule_run`, `ci_run_service`, `job_create` to PROD, `job_rollback`, `job_cancel`, `job_approve`, `job_reject` and `repl_eval`. - With the CLI, ask the user in the chat before every destructive command, and add `--yes` (`-y`) only after they said yes. Don't count on the CLI to ask for you: your shell is usually not a terminal. - `forbidden` means the user lacks a permission. Report it with the permission `api_describe` names. Never look for another tool that does the same thing. - `forbidden: ... event.mcp.call stopped it: ...` means a rule at this site refused the call. Report the rule's message as it is and stop. - Every MCP tool call is recorded in the `event.mcp.call` audit event, with the user, the tool, the arguments (secrets masked) and the answer. ## Secrets - Never print, repeat, store or log a token (`clapat_...`), password or key. Never ask the user to paste one into the chat. They run `clarive login` themselves, or put the token in their client's secret storage or an environment variable. - Secrets come back masked. Sending the masked value back in an update keeps the stored one, so leave masked values alone. - Do not use `variable_get` with `reveal` unless the user asks for it. ## When something does not work - First check: `auth_whoami` (CLI: `clarive whoami`) shows the user, the token and its roles. - `401` or `unauthorized`: the token expired or was revoked. The user runs `clarive login` again, or makes a new token. - A tool you expected is missing: the user lacks its permission, the token is read-only, or the server was connected with `namespaces` or `read_only`. `clarive api describe ` shows the permission needed. - `unavailable: Clarive is in maintenance mode`: only administrators get through until it ends. - CLI exit codes: 0 ok, 1 failed or aborted, 2 usage or `invalid_params`, 3 unauthorized, 4 forbidden, 5 not found, 6 conflict, 7 server error, 8 network, 9 the job did not finish OK. ## Documentation - MCP server: https://docs.clarive.com/en/mcp/overview/ - The clarive CLI: https://docs.clarive.com/en/cli/overview/ - Rules in HCL: https://docs.clarive.com/en/hcl/rules/ ``` [Read the MCP docs](https://docs.clarive.com/en/mcp/overview/) [Talk to us](https://clarive.com/contact)