# Cline MCP server setup and continuity test

Use this workflow to connect Cline IDE or Cline CLI to Handover's remote MCP
server, verify the authenticated boundary, and prove another agent can retrieve
and continue the work.

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

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

First-party Cline installation contract:
https://github.com/44-pixels/handover-mcp/blob/main/llms-install.md

## What a passing setup proves

1. Cline 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. Denied, stale, and revoked paths remain constrained.

A visible server, green status, or tool list proves transport discovery only.

## 1. Create named service identities

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

```text
Cline publisher:  cline-publisher
Cline successor:  cline-successor
```

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

## 2A. Connect Cline CLI

Install and authenticate Cline:

```bash
npm install -g cline
cline auth
```

Open the MCP wizard with Handover's public values prefilled:

```bash
cline mcp install handover \
  --transport http \
  "https://handover.sh/api/mcp?profile=core"
```

Choose:

```text
Server name:     handover
Server type:     Remote (HTTP)
Authentication:  Static headers
```

At the private prompt, enter the `Authorization` header and the publisher's
bearer credential. Do not include the real value in shell history.

Confirm the saved server and enabled state:

```bash
cline config mcp
cline config mcp --json
```

The installation wizard requires an interactive terminal because it collects
the authentication details before saving.

## 2B. Connect the Cline IDE extension

1. Open **MCP Servers** in the Cline panel.
2. Select **Remote Servers**.
3. Set the server name to `handover`.
4. Set the URL to `https://handover.sh/api/mcp?profile=core`.
5. Select **Streamable HTTP**.
6. Add `Authorization` through Cline's private Static headers UI.
7. Keep automatic approval empty while validating the integration.

The equivalent private extension configuration is:

```json
{
  "mcpServers": {
    "handover": {
      "type": "streamableHttp",
      "url": "https://handover.sh/api/mcp?profile=core",
      "headers": {
        "Authorization": "Bearer <SERVICE_AGENT_TOKEN>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Do not commit a populated version. Cline's current documentation recommends
setting `type` explicitly; omitting it falls back to legacy SSE.

## 3. Verify identity before data

Ask Cline:

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

Expected operation:

```text
handover.whoami
```

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

## 4. Verify protected reads

Expected operations:

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

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

Pass only when:

- the record belongs to the expected workspace;
- the principal is allowed to read it;
- the artifact contents match the canonical source;
- a record outside the grant remains undiscoverable.

An empty search may be correct for a new isolated workspace. Confirm with a
known marker rather than widening access.

## 5. Run an approved write and read-back

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

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

Attach a Markdown artifact containing:

```markdown
# Cline MCP verification

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

Expected operations:

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

Pass only when:

- the server attributes the revision to `cline-publisher`;
- visibility is private;
- the returned revision is current;
- the artifact is byte-for-byte retrievable;
- the stable link or identifier is recorded.

## 6. Prove successor continuity

Start a fresh Cline profile or separate Cline installation using the
`cline-successor` credential. Give it only the stable link or marker, not the
publisher's conversation.

Ask:

```text
Find this handoff, verify your identity, 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 `cline-successor`;
2. the successor retrieves the publisher's exact artifact;
3. the marker is reproduced from the artifact;
4. 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.

## 7. Run negative tests

### Missing credential

Remove the Static header temporarily. A protected call must return `401`; the
server must not fall back to a browser session or another actor.

### Denied workspace

Use an identity without the test workspace grant. Search and direct reads must
not reveal the title, summary, artifact, annotation, 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

Attempt a continuation with an obsolete `expectedRevisionId`. The write must be
rejected until the agent reads and reconciles the current revision.

### Revoked credential

Revoke a dedicated test service agent, then call `handover.whoami` again. The
old credential must fail even if the local Cline server entry remains enabled.

## 8. Troubleshoot by checkpoint

```text
404 or transport error
  Verify the full /api/mcp?profile=core URL and Streamable HTTP transport.

401 Unauthorized
  Re-enter, rotate, or revoke the private Static header.

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

Server visible but tools missing
  Restart the server and refresh Cline's tool list.

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

Write conflict
  Read the current revision, reconcile, then retry with explicit approval.
```

## 9. Remove access

1. Disable or remove `handover` from Cline.
2. Revoke the named service agent in Handover.
3. Call `handover.whoami` with the old credential.
4. Pass only when the protected call fails.

Removing local configuration without revoking the remote credential is not
complete offboarding.

## 10. Record the result

```markdown
# Cline MCP setup result

- Cline surface: IDE | CLI
- Cline version:
- 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:
- Overall result: PASS | FAIL
- First failing checkpoint:
- Evidence:
```

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