Sitedrive MCP

# Sitedrive MCP Server

The Sitedrive MCP server lets AI assistants — Claude Code, Claude Desktop, Cursor, and other [Model Context Protocol](https://modelcontextprotocol.io) clients — read and write Sitedrive data on your behalf. It exposes a curated subset of our internal API as MCP tools.

The server is hosted at:

```
https://api.app.sitedrive.com/mcp
```

It speaks the **Streamable HTTP** transport (current MCP spec) and is stateless — every request is self-contained.

---

## Authentication

The Sitedrive MCP server uses **Personal Access Tokens (PATs)** as its primary authentication method. Pass the token in the `Authorization` header:

```
Authorization: Bearer sd_pat_prod_<...>
```

### Creating a PAT

1. Sign in to Sitedrive.
2. Open the user-settings menu and choose **Personal API keys**.
3. Click **New key**, give it a name, and submit.
4. Copy the token *immediately* — you will only see it once.

PATs are scoped to MCP only — they grant access to the operations exposed as MCP tools and nothing else. They cannot be used to call the regular Sitedrive API or sign in to the UI. Revoke tokens you no longer use.

---

## Setup

### Claude Code

```bash
claude mcp add --transport http sitedrive https://api.app.sitedrive.com/mcp \
  --header "Authorization: Bearer sd_pat_prod_..."
```

Then restart Claude Code. Tools appear under the `sitedrive` server.

### Claude Desktop

Claude Desktop's config file only supports **stdio** servers, so connect through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge (a plain `"type": "http"` entry is rejected as invalid). Open `Settings → Developer → Edit Config` and add:

```json
{
  "mcpServers": {
    "sitedrive": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.app.sitedrive.com/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer sd_pat_prod_..." }
    }
  }
}
```

Restart Claude Desktop. (The token goes in `env.AUTH_HEADER` and is referenced as `${AUTH_HEADER}` in args because Claude Desktop splits arg strings on spaces — passing `Authorization: Bearer …` directly would mangle it.)

### Cursor

In Cursor settings (`Cursor Settings → MCP → Add new MCP server`):

```json
{
  "sitedrive": {
    "url": "https://api.app.sitedrive.com/mcp",
    "headers": {
      "Authorization": "Bearer sd_pat_prod_..."
    }
  }
}
```

---

## Slash commands (MCP Prompts)

The server exposes two project-bootstrap flows as MCP Prompts. Pick the one that matches your starting point, then attach the source material when the assistant prompts for it.

| Slash command | When to use |
|---|---|
| `/mcp__sitedrive__replicate-existing-schedule` | Faithful data-shape transform from an external source schedule into Sitedrive. Consolidates per-(work × location) source rows into one WP per work-type, derives the space model from the encoded locations, and pins every emitted TaskInstance to the source dates. Soft-verifies coverage before commit. |
| `/mcp__sitedrive__plan-new-schedule` | Greenfield project bootstrap. Identifies the project archetype, fetches a Sitedrive-blessed WBS template via `sitedrive_get_schedule_templates`, adapts the phases phase-by-phase, builds the space model, sets per-phase `location_level` and `timing_strategy` from archetype defaults, and commits via `sitedrive_import_project`. |

Each command inserts a templated kickoff message that walks the assistant through the workflow and the two-mode output flow on `sitedrive_import_project` (`preview` → `commit` for direct write).

The exact slash-command syntax depends on your client (Claude Code uses `/mcp__<server>__<prompt>`; Claude Desktop / Cursor surface them in the slash-command picker without the `mcp__` prefix).

---

## Tools

| Tool | What it does |
|---|---|
| `sitedrive_whoami` | Returns the authenticated Sitedrive user (id, email, display name) and the list of accounts they can access. Use this to identify the current user and discover which accounts/tenants are available before making other calls. |
| `sitedrive_import_project` | Bootstrap a Sitedrive project end-to-end: site + schedule + space-model + WBS + per-WP zone assignments, in one tool. The MCP wires every WP to its zones server-side from a declarative input — no manual "drag WP onto zone" step in the UI. |
| `sitedrive_get_schedule_templates` | Returns canonical Sitedrive schedule templates — reference WBS structures for common project archetypes (apartment building, office, hospital, tram, road, etc.). Use during the `plan-new-schedule` prompt flow as the starting point for the WBS; never as the final answer. |

---

## Resources

The server registers its reference documents as MCP Resources at `sitedrive://reference/<slug>`. Clients with Resource support (Claude Desktop, Claude Code) list them automatically; the assistant can fetch any of them on demand for deep-dive guidance.

| Slug | Topic |
|---|---|
| `design-principles` | Design principles for a good Sitedrive WBS |
| `intake-checklist` | What to know about a project before drafting WBS / Space Model |
| `location-breakdowns-and-space-tags` | The distinction between location_level (UI management view) and property_type (physical zone matching) |
| `project-types` | Catalogue of project archetypes and per-archetype Space Model conventions |
| `zone-sizing` | Per-archetype zone sizing heuristics and location_level guidance |

---

### Curl (smoke test)

```bash
curl -sN -X POST https://api.app.sitedrive.com/mcp \
  -H "Authorization: Bearer sd_pat_prod_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sitedrive_whoami","arguments":{}}}'
```

Other useful methods for verifying setup: `tools/list`, `prompts/list`, `resources/list`.

---

## Troubleshooting

**`401 missing authorization`** — The `Authorization: Bearer ...` header was missing. Check your client's config.

**`401 invalid api key`** — The PAT format is wrong or the token has been revoked. Mint a new one.

**`401 invalid token`** — A non-PAT bearer token was sent and Firebase rejected it. The MCP server expects a PAT (`sd_pat_*`).

**Tool calls return `Forbidden`** — Your user does not have permission for that resource. Within MCP, a PAT acts on behalf of the user who minted it, with that user's permissions — it cannot escalate.

---

## Spec notes

- Transport: **Streamable HTTP** ([spec 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports))
- Stateless — no `Mcp-Session-Id` tracking. Every `POST` to the endpoint is a fresh transaction.
- OAuth 2.1 / Dynamic Client Registration is **not** supported yet. Bearer-token PATs only.