# Gemini CLI MCP server setup and continuity test

Use this workflow to connect Gemini CLI to Handover's remote MCP server,
verify the authenticated boundary, and prove a fresh Gemini CLI agent can
retrieve and continue exact source context.

Canonical guide:
https://handover.sh/guides/gemini-cli-mcp-server-setup

Handover endpoint:
https://handover.sh/api/mcp?profile=core

Machine-readable host recipes:
https://handover.sh/recipes/mcp-hosts.json

## What a passing setup proves

1. Gemini CLI reaches the remote Streamable HTTP server.
2. A protected tool call resolves the expected service identity.
3. Search and reads stay inside that identity's authorized boundary.
4. An approved private handoff can be created and read back exactly.
5. A separately authenticated successor can retrieve and continue it.
6. Missing, denied, read-only, stale, and revoked paths remain constrained.

`Connected`, a visible server, or a tool list proves transport discovery only.

## 1. Create two named service identities

In Handover, create two service agents with the minimum workspace grants and
scopes required for the test:

```text
Gemini publisher:  gemini-publisher
Gemini successor:  gemini-successor
```

Use separate credentials. Record the human owner, purpose, scope, expiry, and
revocation path for each. Never paste the credentials into a prompt,
repository, handoff, screenshot, or this file.

## 2. Add Handover to Gemini CLI

Use a temporary shell variable so the value does not appear in shell history:

```bash
read -s HANDOVER_TOKEN
export HANDOVER_TOKEN

gemini mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer ${HANDOVER_TOKEN}" \
  handover \
  "https://handover.sh/api/mcp?profile=core"

unset HANDOVER_TOKEN
chmod 600 ~/.gemini/settings.json
gemini mcp list
```

The current Gemini CLI writes a user-scoped entry like this:

```json
{
  "mcpServers": {
    "handover": {
      "url": "https://handover.sh/api/mcp?profile=core",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <SERVICE_AGENT_TOKEN>"
      }
    }
  }
}
```

The populated header is stored locally in `~/.gemini/settings.json`. Keep that
file private and never commit or share it.

Gemini CLI supports automatic OAuth discovery for compatible remote servers.
Handover now exposes first-party dynamic client registration, authorization
code + PKCE, and rotating refresh tokens. Interactive users can omit the static
Authorization header and sign in through the browser; unattended profiles can
keep the named service-identity setup above.

## 3. Inspect the explicit connection state

From the shell:

```bash
gemini mcp list
```

Inside Gemini CLI:

```text
/mcp
/mcp list
```

Gemini CLI can suppress user-level MCP servers in an untrusted folder. A
`Disabled` result is not the same as a network or authentication failure.
Review the repository before trusting it. Do not bypass the trust boundary
only to make the indicator green.

After a configuration change, refresh discovery:

```text
/mcp reload
```

## 4. Verify identity before reading data

Ask Gemini CLI:

```text
Call Handover's identity tool. Show the server-resolved principal, company,
workspace, role, and scopes. Stop if any value differs from the expected
gemini-publisher identity.
```

Expected operation:

```text
handover.whoami
```

Pass only when the result matches the named publisher and intended grants.
Never accept an identity, company, or workspace supplied only in prompt text.

## 5. Verify protected reads

Expected operations:

```text
handover.search
handover.get
handover.read_artifact
```

Search for a known private record the publisher should see. Open its current
revision and read one exact source artifact.

Pass only when:

- the record belongs to the expected workspace;
- the principal has permission to read it;
- the artifact matches the canonical source;
- a record outside the grant remains undiscoverable.

Empty search may be correct for a new isolated workspace. Use a known unique
marker rather than widening access.

## 6. Run an approved write and exact read-back

Ask before the first write. Create a disposable private handoff with a unique
marker:

```text
GEMINI-MCP-SETUP-2026-08-04-01
```

Attach:

```markdown
# Gemini CLI MCP verification

- Marker: GEMINI-MCP-SETUP-2026-08-04-01
- Objective: prove authenticated publish and read-back
- Constraint: private to the test workspace
- Next action: retrieve from gemini-successor
```

Expected operations:

```text
handover.create
handover.get
handover.read_artifact
```

Pass only when the server attributes the revision to `gemini-publisher`,
visibility remains private, and the exact artifact is retrievable from the
canonical revision.

## 7. Prove successor continuity

Use a fresh Gemini CLI profile or installation with the `gemini-successor`
credential. Give it only the stable link or marker, not the publisher's chat.

Ask:

```text
Verify your identity, find this handoff, read the current source artifact,
state the exact marker, and continue the bounded next action using the current
expected revision. Read the result back.
```

Expected operations:

```text
handover.whoami
handover.search
handover.get
handover.read_artifact
handover.annotations
handover.continue
handover.get
```

Pass only when:

1. the server reports `gemini-successor`;
2. the successor retrieves the publisher's exact artifact;
3. the marker is reproduced from that artifact;
4. the constraints remain intact;
5. the new revision records the successor as author;
6. the write uses the prior revision as `expectedRevisionId`;
7. the new canonical revision is read back.

## 8. Run negative tests

### Missing credential

Remove the Authorization header temporarily. A protected call must return
`401`; the server must not guess or reuse another actor.

### Denied workspace

Use an identity without the test workspace grant. Search and direct reads must
not expose titles, summaries, artifacts, annotations, or counts.

### Read-only scope

A read-only identity may inspect granted context but must not create, continue,
annotate, assign, archive, or delete.

### Stale revision

Continue with an obsolete `expectedRevisionId`. The server must reject the
write until the agent reads and reconciles the current revision.

### Revoked credential

Revoke a dedicated test agent and call `handover.whoami` again. The old
credential must fail even if Gemini CLI still shows the local server entry.

## 9. Troubleshoot by checkpoint

```text
Disabled
  Review the current folder trust state before enabling user-level servers.

Disconnected or timeout
  Verify the full /api/mcp?profile=core URL, network, and HTTP transport.

401 Unauthorized
  Replace or rotate the credential stored in the user settings file.

403 Forbidden
  Inspect whoami, workspace grants, role, and scopes.

Connected but tools missing
  Run /mcp reload and inspect includeTools, excludeTools, and allowed servers.

Search returns nothing
  Verify the expected tenant and search a known unique marker.

Write conflict
  Read the current revision, reconcile, and retry only with approval.
```

## 10. Remove local and remote access

Remove the local entry:

```bash
gemini mcp remove --scope user handover
```

Then revoke the named service agent in Handover and require the old credential
to fail against `handover.whoami`.

Removing only the local entry leaves the remote credential valid. Revoking
only the credential leaves stale local configuration. Complete offboarding
requires both.

## 11. Record the result

```markdown
# Gemini CLI MCP setup result

- Gemini CLI version:
- Configuration scope: user | project
- Handover endpoint:
- Publisher identity:
- Successor identity:
- Workspace:
- Publisher revision:
- Successor revision:
- Exact artifact read-back passed:
- Missing credential passed:
- Denied workspace passed:
- Read-only scope passed:
- Stale revision passed:
- Revocation passed:
- Local removal passed:
- Overall result: PASS | FAIL
- First failing checkpoint:
- Evidence:
```

Mark the workflow `PASS` only after the second authenticated identity retrieves
the exact source artifact and creates a verified successor revision.