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

# Automate configuration with the API, MCP and CLI

> Read and change organization and repository configuration from scripts and agents, and draft file changes with the CLI's agent mode.

The CodeRabbit API and the hosted MCP server expose 11 configuration operations. Use them to read the effective configuration of a repository, preview a change without saving it, and update settings from your own tooling. The CLI's agent mode drafts changes to the configuration file for you to review.

## Before you start

* The configuration operations are product operations for GitHub Cloud organizations. Other Git platforms and self-hosted CodeRabbit instances don't offer them.
* Create an API key, or connect an MCP client. See [Authentication](https://docs.coderabbit.ai/api/authentication.md) and [MCP](https://docs.coderabbit.ai/api/mcp.md).
* The settings in every request and response use the V2 shape, including for repositories that use V3.

## Choose a client

| Client | Good for | Auth |
| - | - | - |
| REST API | Scripts, CI and internal tools | API key in the `x-coderabbitai-api-key` header |
| MCP tools | Agents that read and change configuration while they work | OAuth sign-in with the `account:read`, `configuration:read` and `configuration:write` scopes |
| `coderabbit api request` | One-off calls from a terminal | API key file; see [CLI](https://docs.coderabbit.ai/api/cli.md) |
| `cr config --agent` | Drafting changes to the file in a repository | CLI sign-in |

## Automate with the API and MCP

Automate this with the [CodeRabbit API and MCP server](https://docs.coderabbit.ai/api.md).

> [accordion] 11 operations
>
> | Operation | Method and path | MCP tool |
> | - | - | - |
> | [Get organization configuration](https://docs.coderabbit.ai/api/reference/get-organization-configuration.md) | `GET /v1/configuration/organization` | `get_organization_configuration` |
> | [Set organization configuration](https://docs.coderabbit.ai/api/reference/set-organization-configuration.md) | `PUT /v1/configuration/organization` | `set_organization_configuration` |
> | [Get workspace configuration](https://docs.coderabbit.ai/api/reference/get-workspace-configuration.md) | `GET /v1/configuration/workspace` | `get_workspace_configuration` |
> | [Get workspace configuration defaults](https://docs.coderabbit.ai/api/reference/get-workspace-configuration-defaults.md) | `GET /v1/configuration/workspace-defaults` | `get_workspace_configuration_defaults` |
> | [Set workspace configuration defaults](https://docs.coderabbit.ai/api/reference/set-workspace-configuration-defaults.md) | `PUT /v1/configuration/workspace-defaults` | `set_workspace_configuration_defaults` |
> | [Get repository configuration](https://docs.coderabbit.ai/api/reference/get-repository-configuration.md) | `GET /v1/repositories/{repository_id}/configuration` | `get_repository_configuration` |
> | [Set repository configuration](https://docs.coderabbit.ai/api/reference/set-repository-configuration.md) | `PUT /v1/repositories/{repository_id}/configuration` | `set_repository_configuration` |
> | [Get effective repository configuration](https://docs.coderabbit.ai/api/reference/get-effective-repository-configuration.md) | `GET /v1/repositories/{repository_id}/configuration/effective` | `get_effective_repository_configuration` |
> | [Preview repository configuration](https://docs.coderabbit.ai/api/reference/preview-repository-configuration.md) | `POST /v1/repositories/{repository_id}/configuration/preview` | `preview_repository_configuration` |
> | [Get repository configuration source](https://docs.coderabbit.ai/api/reference/get-repository-configuration-source.md) | `GET /v1/repositories/{repository_id}/configuration/source` | `get_repository_configuration_source` |
> | [Set repository configuration source](https://docs.coderabbit.ai/api/reference/set-repository-configuration-source.md) | `PUT /v1/repositories/{repository_id}/configuration/source` | `set_repository_configuration_source` |

Each operation is also an MCP tool with the same `snake_case` name. The get operations need the `configuration:read` scope. The set operations and **Preview repository configuration** need `configuration:write`.

## Read the effective configuration and preview changes

The effective configuration is the resolved YAML plus the YAML of each layer. If CodeRabbit can't resolve it, the response says `complete: false` with a reason.

```bash curl theme={null}
curl "https://api.coderabbit.ai/v1/repositories/$REPOSITORY_ID/configuration/effective" \
  --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY"
```

```bash CLI theme={null}
coderabbit api --api-key-file ~/.config/coderabbit/api-key \
  request "/repositories/$REPOSITORY_ID/configuration/effective"
```

```text MCP theme={null}
Call get_effective_repository_configuration with the repository ID.
```

A preview resolves the YAML that would apply if you saved the settings you send. It saves nothing, but it takes the same request body as a write. It needs the `configuration:write` scope, so agentic API keys can't call it. The caller's role needs permission to read and change repository settings and to read organization settings, and the caller needs read access on GitHub to the repository and to any central `coderabbit` repository.

## Write configuration safely

**1. Read the current settings**

Call the repository or organization get operation. Keep `settings_updated_at` from the response.

**2. Change the settings**

Send `settings`, or `settings_yaml` up to 131,072 characters, together with `expected_settings_updated_at` set to the value you read.

**3. Handle a conflict**

If someone saved in between, CodeRabbit rejects the write. Read again, merge your change, and retry.

The source write works the same way, with `expectedUpdatedAt` set to the `updatedAt` from your last read, or `null` when no policy exists.

## Permissions and limits

| Rule | Detail |
| - | - |
| Key scope | `configuration:read` to read, `configuration:write` to change. MCP tools also need `account:read` |
| Role permission | Organization operations also need read or write access to **Organization settings** in the caller's role. Reading workspace configuration needs read access. See [Role-based access](https://docs.coderabbit.ai/management/roles.md) |
| Agentic keys | Can't change configuration; the API returns `403` |
| Self-hosted instance keys | The API returns `404` |
| Workspace API tokens | Need a selected organization; see [Select an organization](https://docs.coderabbit.ai/api/authentication.md#select-an-organization) |
| Repository configuration source | Only GitHub Cloud organization admins can set it |
| Workspace defaults | Only an Enterprise SSO workspace admin can change them. Write access to **Organization settings** alone isn't enough |

## What organization and workspace reads return

* **Organization:** review settings, the authored and stored YAML, inherited settings, global overrides and the data opt-out state.
* **Workspace:** review settings, YAML, global overrides and the data opt-out state. There is no operation that changes them.
* **Workspace configuration defaults:** one setting, the **Use workspace settings as defaults** toggle.
* **Global overrides:** read-only through the API.

## Draft changes with the CLI agent mode

`cr config --agent` returns structured state without prompts: the active configuration, whether it can be edited, and its content hash as `baseHash`. Add `--generate` to get a validated before-and-after YAML proposal, and `--profile` to shape it.

```bash theme={null}
cr config --agent
cr config --agent --generate --profile assertive
```

Neither command saves the proposal. Review it, write the file, and open a pull request. See [Agent mode](https://docs.coderabbit.ai/cli/agent-mode.md).

## What's next

> [card] [API overview](https://docs.coderabbit.ai/api.md)
>
> Keys, regions and conventions.

> [card] [MCP tools](https://docs.coderabbit.ai/api/mcp/tools.md)
>
> Every tool with its scopes.

> [card] [Check the configuration used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md)
>
> Compare an API read with a review.


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