# Connect your agent

## Create a connection

Sign in, open the site editor, and choose **Site options → Agents**.

1. **Choose your agent.** Pick Cursor, VS Code, Claude Code, or **Another agent (setup message)** for an agent that can make authenticated HTTP requests.
2. **Create the connection.** Give it a recognizable name. By default it can edit content and design for 30 days, but cannot publish. Open **Customize permissions and expiration** only if you want to change those defaults.
3. **Copy its setup.** Follow the instructions for your app. Cursor configuration and the Claude Code command include the token; VS Code prompts for it separately. For another agent, **Copy private setup message** includes the API address, token, discovery steps and a first task. Paste it only into the trusted agent session that should access this site.
4. **Ask for a preview.** Use the supplied starter prompt. A working agent should identify your school and return a private draft preview you can open without another login. Creating a token alone does not confirm that the external agent has connected.

Claude Code means the terminal app, not a browser chat connector. OAuth-only connectors are not supported by this token-based setup. Tokens expire after the chosen duration (up to 90 days); create a replacement before expiry.

Copy the token while the panel is open. Only its hash is stored. A lost token cannot be displayed again—disconnect it and create a replacement.

| Scope | Allows |
| --- | --- |
| `read` | Site context, search, content reads, design options, previews, release history and delivery checks. Always included. |
| `content` | Add, update, delete and organize stories/collections; upload media. |
| `design` | Adjust supported settings and apply existing coordinated designs. |
| `publish` | Approve draft entries, publish and restore releases, subject to your current site role. |

Publishing is off by default. Connections cannot manage people, devices, accounts, archives, billing or other sites. Site owners can disconnect other members' connections; members can manage their own. There can be 20 unexpired connections per site.

## MCP endpoint

```text
https://api.history-showcase.com/api/platform/agent/mcp
```

Transport: **Streamable HTTP**, stateless, JSON responses. Authentication: `Authorization: Bearer <site-connection-token>` on every request. The server uses the official MCP SDK and exposes tools, documentation resources and an `improve-site` starter prompt.

This connection uses a bearer token, not an OAuth browser login. Use a client that supports custom authorization headers. Clients that only support OAuth connectors are not supported by this connection method.

### Cursor and compatible JSON clients

Add to your MCP configuration and replace the placeholder locally:

```json
{
  "mcpServers": {
    "historyshowcase": {
      "url": "https://api.history-showcase.com/api/platform/agent/mcp",
      "headers": { "Authorization": "Bearer YOUR_SITE_CONNECTION_TOKEN" }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`. VS Code prompts for the token rather than storing it in the shared configuration:

```json
{
  "servers": {
    "historyshowcase": {
      "type": "http",
      "url": "https://api.history-showcase.com/api/platform/agent/mcp",
      "headers": { "Authorization": "Bearer ${input:historyshowcase-token}" }
    }
  },
  "inputs": [{ "id": "historyshowcase-token", "type": "promptString", "description": "HistoryShowcase site token", "password": true }]
}
```

### Claude Code

Set `HISTORYSHOWCASE_TOKEN` locally using the token from the panel. Then:

```bash
claude mcp add --transport http historyshowcase \
  https://api.history-showcase.com/api/platform/agent/mcp \
  --header "Authorization: Bearer $HISTORYSHOWCASE_TOKEN"
```

The client may persist this header in its local configuration. Use your client's secret-storage features where available; do not commit credentials.

## First prompt

> Review my HistoryShowcase site and suggest a design from the available templates. Show me a draft preview before publishing.

Back in the editor, use **Refresh draft** to load saved agent changes. Save or discard your local design edits first; the button stays disabled while you have unsaved changes.

## Direct API

The same token works with every documented API operation. Set `HISTORYSHOWCASE_TOKEN` in your local secret environment, then:

```bash
curl --fail-with-body https://api.history-showcase.com/api/platform/agent/v1/get_site_context \
  -H "Authorization: Bearer $HISTORYSHOWCASE_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{}'
```

All operation endpoints use POST with a JSON object, including reads. API clients do not need the MCP handshake. See [OpenAPI](openapi.json) for machine-readable request schemas.

## Disconnect or rotate

In **Agents → Your connections**, select **Disconnect**. Revocation is checked against persisted state on subsequent requests; already-running requests may finish. To rotate, create a replacement, update the client, verify `get_site_context`, then disconnect the old connection.