# MCP tools

Each instance serves Streamable HTTP MCP at `<instance>/mcp`, authorized with OAuth. On connect, the server's instructions point the agent at the [product skill](/skill.md). Clients should discover tools each session rather than trusting a cached list.

Every tool is also a REST endpoint under `<instance>/acahti/v1`, which the [CLI](/docs/cli/) reaches with `acahti api`. Path segments fill the matching arguments; the rest go in the query string or a JSON body. Required arguments are in bold.

## Tools

<!-- tools:start -->
### repo_list

List repositories the token can see.

- Arguments: `page` `page_size`
- REST: `GET /repos`

### repo_get

Get one repository.

- Arguments: **`name`** **`owner`**
- REST: `GET /repos/{owner}/{name}`

### repo_create

Create a private org repo. Optional team attaches access. Does not set branch protection.

- Arguments: **`name`** `team`
- REST: `POST /repos`

### branch_list

List branches with default and protected flags from repo settings.

- Arguments: **`name`** **`owner`** `page` `page_size`
- REST: `GET /repos/{owner}/{name}/branches`

### ref_delete

Delete a git ref. ref is dev, heads/dev, or refs/heads/dev.

- Arguments: **`name`** **`owner`** **`ref`**
- REST: `DELETE /repos/{owner}/{name}/refs/{ref...}`

### pr_create

Open a pull request. base defaults to the repo default_branch.

- Arguments: **`head`** **`name`** **`owner`** **`title`** `base` `body`
- REST: `POST /repos/{owner}/{name}/pulls`

### pr_list

List pull requests.

- Arguments: **`name`** **`owner`** `page` `page_size` `state`
- REST: `GET /repos/{owner}/{name}/pulls`

### pr_get

Get a pull request with latest commit checks per context.

- Arguments: **`name`** **`number`** **`owner`**
- REST: `GET /repos/{owner}/{name}/pulls/{pr}`

### pr_comment

Comment on a pull request.

- Arguments: **`body`** **`name`** **`number`** **`owner`**
- REST: `POST /repos/{owner}/{name}/pulls/{pr}/comments`

### pr_comments

List pull request comments.

- Arguments: **`name`** **`number`** **`owner`** `page` `page_size`
- REST: `GET /repos/{owner}/{name}/pulls/{pr}/comments`

### pr_merge

Merge a PR when the latest pipeline round on the head SHA is green.

- Arguments: **`name`** **`number`** **`owner`**
- REST: `POST /repos/{owner}/{name}/pulls/{pr}/merge`

### pr_close

Close a pull request.

- Arguments: **`name`** **`number`** **`owner`**
- REST: `DELETE /repos/{owner}/{name}/pulls/{pr}`

### checks_wait

Snapshot of indexed pipelines for a commit. Poll this tool; it does not block.

- Arguments: **`name`** **`owner`** **`sha`**
- REST: `GET /repos/{owner}/{name}/checks/{sha}`

### pipeline_list

List pipelines for a repo with wait (queue, deps, concurrency) on in-flight runs. sha is a commit prefix.

- Arguments: **`repo`** `branch` `page` `page_size` `sha` `status`
- REST: `GET /repos/{owner}/{name}/pipelines`

### pipeline_get

Get one pipeline with jobs, steps, and wait (queue, deps, concurrency).

- Arguments: **`number`** **`repo`**
- REST: `GET /repos/{owner}/{name}/pipelines/{run}`

### pipeline_log

Fetch pipeline logs. Omit step for failed steps only.

- Arguments: **`number`** **`repo`** `step` `tail_lines`
- REST: `GET /repos/{owner}/{name}/pipelines/{run}/log`

### pipeline_rerun

Rerun a pipeline.

- Arguments: **`number`** **`repo`**
- REST: `POST /repos/{owner}/{name}/pipelines/{run}/rerun`

### pipeline_trigger

Manual run on a ref. Official release is still git push.

- Arguments: **`repo`** `ref`
- REST: `POST /repos/{owner}/{name}/pipelines`

### pipeline_cancel

Cancel a running or queued pipeline.

- Arguments: **`number`** **`repo`**
- REST: `POST /repos/{owner}/{name}/pipelines/{run}/cancel`

### pipeline_delete

Delete a finished pipeline run.

- Arguments: **`number`** **`repo`**
- REST: `DELETE /repos/{owner}/{name}/pipelines/{run}`

### inbox

Inbox across repositories. pipes: latest failed or blocked run per repo. prs: open PRs whose head SHA latest pipeline is success (ready to merge).

- Arguments: `page` `page_size` `section`
- REST: `GET /inbox`

### pkg_publish

Publish a language package (pypi wheel URL or npm tarball URL).

- Arguments: **`kind`** **`url`** `filename`
- REST: `POST /packages`

### pkg_list

List language packages.

- Arguments: `kind` `owner` `page` `page_size`
- REST: `GET /packages`

### pkg_delete

Delete a language package version. Org admin. Omit version to delete every version of that name.

- Arguments: **`kind`** **`name`** `owner` `version`
- REST: `DELETE /packages`

### whoami

Acahti git identity: git_name, git_email, clone_url_template, skill_url, apply_when_remote_host, setup_local, org_admin, modules (work/argos/chat).

- REST: `GET /me`

### agent_status

Host runners plus queue stats counted per pipeline (running / queued).

- Arguments: `page` `page_size`
- REST: `GET /agents`

### deploy_approve

Approve a gated deploy pipeline.

- Arguments: **`number`** **`repo`**
- REST: `POST /repos/{owner}/{name}/pipelines/{run}/approve`

### secret_list

List pipeline secret names (never values). scope org is org admins. scope repo is the effective set (org inherited plus repo) for repo admins. repo or owner+name for repo scope.

- Arguments: `name` `owner` `page` `page_size` `repo` `scope`
- REST: `GET /repos/{owner}/{name}/secrets`, `GET /secrets`

### secret_put

Create or replace a pipeline secret. Does not echo value. org scope needs org admin. repo scope needs repo admin. name is the secret.

- Arguments: **`value`** `name` `owner` `repo` `scope` `secret`
- REST: `PUT /repos/{owner}/{name}/secrets/{secret}`, `PUT /secrets/{secret}`

### secret_delete

Delete a pipeline secret. org scope needs org admin. repo scope needs repo admin and only deletes the repo override.

- Arguments: `name` `owner` `repo` `scope` `secret`
- REST: `DELETE /repos/{owner}/{name}/secrets/{secret}`, `DELETE /secrets/{secret}`

### user_list

List people by login and display name. q matches either. Does not return email.

- Arguments: `page` `page_size` `q`
- REST: `GET /users`

### team_list

List teams the caller can see, with repo counts.

- Arguments: `page` `page_size`
- REST: `GET /teams`

### team_get

Team members and repositories. A member's permission applies to every repo in the team.

- Arguments: **`team`**
- REST: `GET /teams/{team}`

### team_member_set

Add or update a team member. Org admin. permission is read, write, or admin; omit for write. The grant covers every repository in the team.

- Arguments: **`login`** **`team`** `permission`
- REST: `PUT /teams/{team}/members/{login}`

### team_member_remove

Remove a person from a team. Org admin.

- Arguments: **`login`** **`team`**
- REST: `DELETE /teams/{team}/members/{login}`

<!-- tools:end -->