# Agents and permissions

> Connect Claude, Cursor, ChatGPT or your own agent to a project's MCP server, and control what each person, agent and token may do with roles, scopes and agent rules.

Each project runs an MCP server at:

```text
https://api.galerne.cloud/p/<project>/mcp
```

It speaks MCP over streamable HTTP and serves the same tools as the HTTP API, filtered to what the caller may do. The [MCP tools](/docs/tools.md) page lists them. When an agent connects, the server tells it to read the schema and the guidelines first, work on a branch, run `check`, and finish with `request_review`.

## Connect an MCP client

Clients that support OAuth open a Galerne sign-in page. You sign in with your email, pick the project, and choose the agent member the client will act as, or create one. The client never sees your own session. Access tokens last one hour and the client refreshes them; a refresh token expires after 60 days without use.

The steps below match each client in October 2026; their menus change from time to time.

### Claude (claude.ai and the desktop app)

1. Open **Settings**, then **Connectors**.
2. Choose **Add custom connector**, name it (for example `acme content`) and paste `https://api.galerne.cloud/p/acme/mcp`.
3. Choose **Connect** and sign in to Galerne. Pick the agent member.
4. In a conversation, enable the connector from the tools menu. The prompts `translate_doc`, `alt_text` and `seo_pass` appear in the same menu.

On Team and Enterprise plans, an owner may need to add the connector for the organisation first.

### Claude Code

```bash
claude mcp add --transport http acme https://api.galerne.cloud/p/acme/mcp
```

Then run `/mcp` in Claude Code, select `acme` and authenticate in the browser.

### Cursor

Add the server to `.cursor/mcp.json` in your repository, or to `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "acme": { "url": "https://api.galerne.cloud/p/acme/mcp" }
  }
}
```

Open **Cursor Settings**, then **MCP**, and choose **Login** next to `acme`.

### ChatGPT

1. Open **Settings**, then **Apps & Connectors**, then **Advanced settings**, and turn on **Developer mode**.
2. Back in **Apps & Connectors**, choose **Create**, name the connector and paste the MCP URL. Keep OAuth as the authentication.
3. Sign in to Galerne and pick the agent member.

Developer mode is available on the plans OpenAI lists in its help pages.

### Clients without OAuth, and your own agents

Create an agent in the project settings, then a token for it, and send it as a header:

```bash
claude mcp add --transport http acme https://api.galerne.cloud/p/acme/mcp \
  --header "Authorization: Bearer gal_…"
```

```json
{ "mcpServers": { "acme": { "url": "https://api.galerne.cloud/p/acme/mcp", "headers": { "Authorization": "Bearer gal_…" } } } }
```

Agents you write yourself can also skip MCP and call the same tools over HTTP: `POST /p/<project>/v1/tools/<name>`. See the [HTTP API](/docs/api.md).

### Local stdio

For clients that only run local servers, the CLI runs one over stdio and forwards it to the project:

```json
{
  "mcpServers": {
    "acme": {
      "command": "galerne",
      "args": ["mcp", "--project", "acme"],
      "env": { "GALERNE_API_URL": "https://api.galerne.cloud", "GALERNE_TOKEN": "gal_…" }
    }
  }
}
```

## Roles

Every member, person or agent, has one role per project.

| Can | viewer | contributor | editor | admin |
|---|---|---|---|---|
| Read published content and drafts, export | yes | yes | yes | yes |
| Comment | yes | yes | yes | yes |
| Write on branches, create branches, upload media, ask for review | | yes | yes | yes |
| Publish, delete, promote, approve, import | | | yes | yes |
| Deploy the schema, manage members, tokens, webhooks, settings, billing, read the audit log | | | | yes |

Agents get the contributor role by default. An admin agent that changes a site's content model deploys it on its branch with `deploy_schema` and `branch`; it reaches `main` when a person promotes the branch.

## Limits per member

On the Business plan, you can narrow what a person may change, on top of their role, in **Settings**, **Members**:

| Limit | Example | What it does |
|---|---|---|
| Languages | `de` | Writes only in these languages: localized values and documents of those languages |
| Types | `post`, `page` | Writes only documents of these types |
| Branches | `agent/*`, `release/spring` | Writes only on these branches; a pattern ending in `*` matches by prefix |

A German editor limited to `de` can translate every page and change nothing else. Limits apply to writes: reading, commenting and asking for review stay open. Agents have their own branch and type rules, below, on every plan.

## Agent rules

On top of its role, each agent has rules, set in the project settings:

| Rule | Default | What it does |
|---|---|---|
| Owner | the person who created it | Who answers for the agent |
| Allowed branches | any | Patterns of branches it may write on, such as `agent/*` or `release/spring` |
| Allowed types | any | Document types it may write |
| Write on main | off | Without it, writes, publishes, deletes and imports on `main` are refused |
| Promote | off | Without it, `promote` is refused and the agent asks for review |
| Rate limit | 120 requests per minute | Requests over it get a `429` |

Agents can never approve a review. Refusals come back as `403` with the reason, such as `agents cannot write on main unless allowed; work on a branch and call request_review`, so the agent can change course.

**Kill switch.** Disabling an agent in the project settings stops every token it holds at once, including OAuth tokens. Enable it again to restore access.

Agents show in presence, history, comments and reviews with their name and an `agent` tag, so you always know who changed what.

## Tokens and scopes

A token is a `gal_…` secret. It acts either as a member (a person or an agent), with that member's role and rules, or as the project itself, for sites and CI. Each token also has scopes, which cap what it may do whatever the role:

| Scope | Allows |
|---|---|
| `read:published` | Published content, the schema and media |
| `read:drafts` | `query` with drafts and branches, nothing more; Galerne gives it to the branch builds of [managed sites](/docs/sites.md) |
| `read` | Also drafts, branches, history, comments, export |
| `write` | Also every write, publish, review and promotion the role allows |
| `admin` | Also schema deploys, members, tokens, webhooks and settings |

A higher scope includes the lower ones. Use `read:published` in site code that runs in the browser, `read` for previews on your server, and `admin` for `galerne schema deploy` in CI. Project tokens without `admin` cannot write on `main`.

The tokens page lists every token and OAuth client with access, the member it acts as, its scopes and when it was last used. Revoking takes effect at once.

## Audit log

On the Business plan, the audit log records who did what in the project: every change made through a tool, from the studio, the API, the CLI or MCP, and every change to members, agents, tokens, SSO and site settings. Each entry has the actor (person, agent, token or system), the action, the target, the time and the IP address. Admins read it in **Settings**, **Audit log**, or with `get_audit_log`, filtered by actor or action. `GET /p/<project>/v1/audit.csv` downloads every entry as CSV, newest first, with an `admin` token. Entries are kept as long as the plan keeps history: one year on Business.

## Notifications

People get an email when someone asks for review of a branch (admins and editors), assigns them a task, or mentions them with `@email` or `@[Name]` in a comment. Agents and the author of the action get no email.

## Rate limits

Limits count requests per minute, per token or member: 600 for people and project tokens, the agent's own limit for agents, and 600 per IP address for anonymous reads. Over the limit, the API answers `429` with a `retry-after` header.

## What leaves Galerne

Galerne runs no language model. When an agent calls a tool, the result goes to the MCP client, which passes it to the model the client uses. That model provider is your choice, under your contract with it. Pick the agent's role, allowed types and scopes with that in mind: an agent can only read what its member may read. The [DPA](/legal/dpa) describes this flow.

## Metering

MCP calls count toward the plan: 50,000 a month on Free, 500,000 on Pro and 5 million on Business. Agents never count as seats; Free includes 2 agents and paid plans have no limit.
