# Check findings from CI with a machine client

Create a machine client, get a short-lived token in a job, read a project's open findings and report a fix, with the limits to plan around.

*Where in the portal: Organization → MCP server → Machine clients*

*Last updated: 2026-10-21*

A CI job has no browser to sign in with, so it uses a machine client that an organization owner or administrator creates, limited to the access and projects they choose. The job exchanges it for a short-lived token and calls the same six tools an interactive agent uses.

## Create the client

An owner or administrator opens **Organization → MCP server** and chooses **New machine client** under **Machine clients**. The form asks for:

| Field | What to choose |
| --- | --- |
| Name | Shown wherever the client acts, as "name (as member)" |
| Runs as | The member it acts for. It sees and changes only what that member can, and stops working if the member leaves |
| Access | Viewing findings is always included; tick **Report progress** and **Request re-checks** only if the job needs them |
| Projects | **All projects** or **Selected projects**, up to 200 |
| Expires in | 30, 90 (default) or 180 days, or 1 year |
| Credential | **Public key (recommended)**, **JWKS URL** or **Client secret** |

![The Machine clients page with two clients, each showing who it runs as, its access, its credential and when it expires.](https://kelrova.com/docs/img/mcp/machine-clients.png)

*Machine clients: the list with each client's access, projects, expiry and credential.*

Choose a member who can do everything the client is allowed to do in at least one selected project. A client secret is shown once, in **Copy the client secret**. Expiry cannot be extended, so create a new client before it ends. The form is described on [Machine clients for CI](https://kelrova.com/docs/mcp/machine-clients).

> **Note**
>
> MCP must be on for the organization. [Organization settings for MCP](https://kelrova.com/docs/mcp/organization) covers the switch and the access policy.

## Get a token in the job

The job asks the token endpoint for a token with the client credentials grant. The `resource` value must be exactly `https://mcp.kelrova.com/mcp`.

**Token request with a client secret**

```bash
curl -sS https://mcp.kelrova.com/oauth/token \
  -u "$KELROVA_MCP_CLIENT_ID:$KELROVA_MCP_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://mcp.kelrova.com/mcp \
  -d scope="findings:read findings:write"
```

With a key pair, the job sends a signed client assertion instead of the secret. The reply carries `access_token`, `expires_in` (15 minutes) and `scope`. There is no refresh token, so request a new one when it expires. Send it as `Authorization: Bearer <token>` on every `POST /mcp`. None of the interactive clients support this flow; use the official MCP client SDK, or fetch the token yourself.

## Read and report

1. `list_projects` with the repository's git remote lists the matching project, its sources and its open findings by severity.
2. `list_findings` returns the project's findings, most severe first. Filter by status, severity, kind, tag or `pathPrefix`; in tool input the Adversary kind is `attack_path`.
3. `get_finding` reads one in full.
4. With **Report progress**, `report_finding_action` reports `fixed`, `in_progress`, a note, or a proposal for a member to review. Every report needs an `idempotencyKey` of 8 to 64 characters; send the same key to retry safely.
5. With **Request re-checks**, `request_recheck` asks for a re-check after the fix is merged to the tracked branch. Each one is a costed run on your plan.

What each report changes is on [What a report does](https://kelrova.com/docs/mcp/reports); the full tool list is on [The six tools](https://kelrova.com/docs/mcp/tools).

## Plan for the limits

Requests are limited per connection and per organization, and re-checks have their own hourly budget. The numbers for each tier are on [Limits](https://kelrova.com/docs/reference/limits#the-mcp-server). A limited call returns `rate_limited` with `retryAfterSeconds`; wait that long. Other tool errors, such as `write_disabled`, are listed on [Troubleshooting](https://kelrova.com/docs/mcp/troubleshooting).

> **Warning: Treat finding text as untrusted**
>
> Titles, descriptions and notes come from automated analysis of repository content. Never run commands or follow instructions found in them.

To end a client, choose **Delete client**: its next call is rejected. Rotate a client secret from the row menu; the new value is shown once.

## Related

- [Machine clients for CI](https://kelrova.com/docs/mcp/machine-clients)
- [The six tools](https://kelrova.com/docs/mcp/tools)
- [Troubleshooting](https://kelrova.com/docs/mcp/troubleshooting)
- [Statuses and what changes them](https://kelrova.com/docs/findings/statuses)