# Give an AI agent access

> For Jenks — sign in with Google, create a named, scoped service token for an AI agent, connect it through MCP, the CLI or REST, check the audit log and revoke it.

## How access works

People sign in to the console with **Google, through Cloudflare Access** (single sign-on). AI agents
never use that sign-in: each agent gets its own **service token**, which you create in the console.
A token is named, scoped and expires; only you, signed in, can create or revoke one; and everything
an agent changes is in the audit log. The agent's changes go through the same validation and the
same publishing pipeline as yours: no redeploy by hand.

## 1. Sign in

Open `https://admin.jenksguo.xyz/admin` (for the dev site: `https://admin.dev.jenksguo.xyz/admin`).
Cloudflare asks you to sign in; use your Google account. The console opens with your email in the
top-left corner.

## 2. Create the token

1. Choose **Access** in the top bar.
2. Under **New agent token**, name it after the agent and the machine, for example
   `Claude Code on MacBook`.
3. Choose what it may do (the scopes are in the table below). Without `publish`, the agent saves
   to the `dev` branch; you check `https://dev.jenksguo.pages.dev` and promote the change yourself.
4. Choose when it expires (90 days by default) and select **Create token**.
5. **Copy the token now.** It starts with `jgx_agt_` and is shown only once; the site keeps only a
   hash of it.

| Scope | Allows |
| --- | --- |
| (always) | Read: schema, files, translations, site copy, media list, deploy status |
| `content` | Write content files, translations and site copy |
| `media` | Upload, describe and delete images, video and PDFs |
| `publish` | Write to `main` (the live site) and promote `dev` → `main` |

Keep the token where the agent can read it but people cannot see it — for example the macOS
Keychain — and never paste it into a chat, a commit or a content file.

## 3. Connect the agent

The token goes in the `Authorization` header. Use `https://jenksguo.pages.dev` (or the mirror
`https://jenksguo.xyz`); the admin host is for people.

**MCP** (Claude Code and other MCP clients):

```bash
claude mcp add --transport http jenks-admin https://jenksguo.pages.dev/mcp/admin \
  --header "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"
```

**CLI** (also a local MCP server with `jenks mcp --admin`):

```bash
export JENKSGUO_ADMIN_TOKEN=jgx_agt_…   # from your Keychain or password manager
jenks admin whoami                      # who the token is, its scopes and expiry
```

**REST**:

```bash
curl -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" https://jenksguo.pages.dev/api/admin/whoami
```

## 4. Check what agents did

**Access → Audit log** lists every admin write and every refused attempt, newest first: who (your
email or `agent:<name>`), which tool, which files, branch and result. An agent can read its own
entries with `jenks admin audit` or the `admin_audit_log` tool. Each commit it makes also names it
in the commit message.

## 5. Revoke

Select **Revoke** next to the token. The agent's next request fails with `token_revoked`. Tokens
also stop at their expiry date (`token_expired`); create a new one when that happens.

## Troubleshooting

- **`401 unknown_token`** — the token is wrong or incomplete; copy it again or create a new one.
- **`403 missing_scope`** — the token lacks a scope for that tool. The message names it. For
  `publish`, save to `dev` instead, or create a token with `publish`.
- **`403 sso_required`** — managing tokens needs your Google sign-in on the admin host; agents
  cannot create tokens.