# Sitedrive MCP

Connect Sitedrive to your AI assistant using the [Model Context Protocol](https://modelcontextprotocol.io).
The Sitedrive MCP server provides secure access to Sitedrive tools, prompts and reference material
through your existing Sitedrive account.

## Set up Sitedrive MCP

### Server URL

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

Add this URL as a remote **Streamable HTTP** MCP server. For the recommended OAuth setup, do not
configure an API key, bearer token, client ID or client secret. Your client discovers Sitedrive OAuth
and opens the sign-in flow automatically.

### Choose your client

#### Claude.ai and Claude Desktop

For an individual plan:

1. Open **Customize → Connectors**.
2. Select **+ → Add custom connector**.
3. Enter `https://api.app.sitedrive.com/mcp` as the remote MCP server URL. Leave OAuth Client ID and Client Secret empty.
4. Add the connector, sign in to Sitedrive and approve access.

For Team and Enterprise, an Owner first adds the URL under **Organization settings → Connectors**;
members then connect it from **Customize → Connectors**. Hosted Claude connects from Anthropic's
cloud, so use a deployed HTTPS endpoint rather than a local `localhost` URL.

#### Claude Code

```bash
claude mcp add --transport http sitedrive https://api.app.sitedrive.com/mcp
claude mcp login sitedrive
```

You can also open `/mcp` in Claude Code and select Sitedrive to authenticate.

#### OpenAI Codex

Codex CLI, the IDE extension and Codex in the ChatGPT desktop app share MCP configuration:

```bash
codex mcp add sitedrive --url https://api.app.sitedrive.com/mcp --oauth-resource https://api.app.sitedrive.com/mcp
codex mcp login sitedrive --scopes mcp
```

Open `/mcp` in a new Codex session to inspect the connection and available tools.

#### ChatGPT

ChatGPT receives third-party MCP connections through plugins. Once the Sitedrive plugin is
published or added to your workspace marketplace, install it from **Plugins**, connect Sitedrive
when prompted and start a new chat. Pasting the raw MCP URL into a normal ChatGPT conversation does
not install a connector.

#### Other MCP clients

Choose **remote MCP** or **Streamable HTTP**, enter `https://api.app.sitedrive.com/mcp`, and leave custom headers empty.
For clients that accept the common `mcpServers` JSON shape:

```json
{
  "mcpServers": {
    "sitedrive": {
      "type": "streamable-http",
      "url": "https://api.app.sitedrive.com/mcp"
    }
  }
}
```

Some clients call the same transport `http`. Follow the client's schema if it differs. Clients that
only support local stdio servers can use the third-party compatibility bridge:

```bash
npx -y mcp-remote https://api.app.sitedrive.com/mcp
```

Native Streamable HTTP is preferred because it removes the local bridge and lets the client manage
OAuth directly.

### Confirm the connection

Ask the assistant:

> Call `sitedrive_whoami` and show the structured result.

The result should contain `"authenticated_via": "oauth"` and the Sitedrive accounts the user can
currently access. Then ask it to call `sitedrive_get_schedule_templates` without a template
ID to verify a read-only tool. Do not test a write tool against a production account unless you
intend to keep the result.

## Authentication and permissions

Connecting opens Sitedrive in your browser. Sign in and approve the connection; your password is
never shared with the MCP client. The client receives short-lived access tokens and manages renewal
through OAuth.

MCP operations run as the signed-in user and remain limited by that user's current account, site and
project permissions. Account API-key and Sitedrive-hosted AI settings do not change these personal
permissions. Account-scoped tools ask for an account ID or derive it from the selected site or project.

## Available capabilities

### 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 and Cursor surface prompts in their command picker
without the `mcp__` prefix.

### Tools

For an existing schedule, start with `sitedrive_find_projects` using a project, site or account name. Its account ID filter is optional. Use `sitedrive_whoami` when you need the signed-in identity, not as a prerequisite to finding a project.

| Tool | What it does |
|---|---|
| `sitedrive_whoami` | Returns the authenticated Sitedrive user and their accounts, including a link to each account in the app. Use for identity or authentication questions. To find a schedule, call sitedrive_find_projects directly; its search does not need an account ID. |
| `sitedrive_find_projects` | First step for finding a schedule: search project, site or account names directly, without calling sitedrive_whoami. A site can contain several schedules with unrelated names; show candidates and ask which one when ambiguous. Search is required and literal, case-insensitive. Narrow by account_id only when already known. Results include names, IDs, timezone, match source and a project link. Only readable active projects appear. has_more means refine the name or account. A known project ID from a schedule URL can go directly to a project-scoped tool. |
| `sitedrive_find_locations` | Resolve a named floor, room or work area within a known project. By default search covers both physical spaces and persisted work areas, regardless of space_type: older floors may be typed ZONE. Supply a non-empty name search. Names and ancestor paths disambiguate matches; do not choose the first duplicate. For a physical floor or room, use the space result as space_id; use a work_area result as work_area_id only when the user means that schedule breakdown. Same-named spaces and work areas can contain different work, so ask which scope when unclear. A selected work area may extend beyond the named floor. has_more means narrow the search. |
| `sitedrive_find_teams` | Find a crew by name on a known project site, or resolve returned team_ids in one bounded IDs lookup. Supply a name or IDs. Use returned IDs in project-scoped team filters. has_more means narrow the name or IDs. |
| `sitedrive_get_work_package_summaries` | Browse current schedule packages/phases and their whole-package planned/actual dates, weighted progress and planned working duration. Use parent_id=null for a top-level overview or a package ID for a focused phase summary. Returns package IDs, parent IDs and names in structural order. Every package includes has_location_rows regardless of fields: false means skip its location-detail lookup; true includes eligible work in leaf descendants and unplaced work, but additional location filters may still return no rows. This is neither a location count nor an indication of child packages. Request a parent by its ID only when additional hierarchy context is needed. No location summaries. Use sitedrive_get_work_package_location_summaries for work on a floor, personal/team assignments or date filters. Use returned IDs to narrow follow-up requests. Never average displayed child progress to obtain parent totals. Working duration is planned calendar span, not labor effort. Returns a bounded answer; has_more means narrow search or package scope. Use REST summary resources for full extraction. |
| `sitedrive_get_work_package_location_summaries` | Find current schedule work by floor/location, person, team, dates or package. First resolve the project with sitedrive_find_projects, a physical floor with sitedrive_find_locations, and a named crew with sitedrive_find_teams when needed. For “what is unfinished on Level 3?”, use the physical space ID as space_id and completion=incomplete. Returns one complete package/location aggregate per item, not nested package totals. Filters select complete package–location summaries; their progress includes all contributing tasks. Includes package and location names. Use package summaries for additional package hierarchy context. Use assigned_user_id=me for my work. A floor match may include a work area extending beyond that floor. Returns a bounded answer; has_more means narrow the question. Do not interpret a bounded result as an exact total. Never enumerate the whole schedule through repeated calls. Use REST summary resources for full extraction. Use response timezone and explicit offsets for calendar weeks. Starts next week: planned_start_from/planned_start_before. Use completion for task-state selection, overdue_as_of for unfinished work past planned end, and sort_by=progress with limit=10 for least-complete locations. These are location results, not whole-package overdue totals. Do not infer readiness, delay causes, forecasts or historical progress. Working duration is planned calendar span, not labor effort. |
| `sitedrive_set_work_package_progress` | Set current reported progress for the TASK work in a package or phase. First find the project and package, then use location summaries if the user named a specific work area. Omit location_id to update every descendant leaf and location; pass one exact location_id for that work area, or null for unplaced work. This is a real schedule mutation and may affect actual dates; ask the user before calling when intent is ambiguous. Every selected TASK instance receives the same percentage, while displayed package progress remains weighted. At 100%, legacy prerequisite tasks are completed too. Never retry automatically after a timeout; read the current summary first. |
| `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. |
| `sitedrive_submit_mcp_feedback` | When Sitedrive MCP cannot meet a user goal after trying the relevant tools, explain the gap and offer to submit feedback. Call this tool only if the user explicitly asks you to submit it or accepts your offer. Do not submit for missing permissions, a transient error, or a legitimate empty result. The short feedback text is stored in Sitedrive logs and analytics for product review. Never include secrets or a full chat transcript. |

### Resources

The server registers its reference documents as MCP resources at `sitedrive://reference/<slug>`.
Clients with resource support list them automatically, and the assistant can fetch them on demand.

| 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 |
| `schedule-questions` | How to scope schedule questions and interpret Gantt measures |
| `zone-sizing` | Per-archetype zone sizing heuristics and location_level guidance |

## Troubleshooting

**The browser does not open** — Remove any manually configured authorization header, then reconnect
using only the MCP URL.

**A hosted client cannot connect to a local URL** — Claude.ai, ChatGPT and other hosted clients make
requests from their own cloud. Use the deployed HTTPS MCP URL. Local URLs work only with clients
running on the same machine, such as Claude Code or Codex CLI.

**Authorization request expired** — Start the connection again from the MCP client.

**Authentication is required again** — Let the client refresh first. If it cannot, clear the stored
authentication and reconnect. A revoked grant requires new consent.

**Tool calls return `Forbidden`** — Your Sitedrive role does not allow the operation on the target
account, site or project.

**The server is connected but no tools appear** — Reconnect or restart the client so it refreshes
the MCP tool catalog.

---

## Protocol support

### Discovery smoke test

```bash
curl -s https://api.app.sitedrive.com/.well-known/oauth-protected-resource/mcp
```

The response should name `https://api.app.sitedrive.com/mcp` as the resource and contain an HTTPS authorization-server
URL. Use a real MCP client for the authorization flow; OAuth access tokens are intentionally managed
by the client rather than copied into shell commands.

- Transport: **Streamable HTTP** ([implemented protocol revision](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 discovery, Authorization Code with PKCE, Dynamic Client Registration, Client ID Metadata
  Documents, refresh-token rotation and revocation are supported for public clients
  (`token_endpoint_auth_method=none`) and for confidential clients such as Microsoft Copilot Studio
  (`client_secret_basic` or `client_secret_post`) and clients that sign with their own key, such
  as ChatGPT (`private_key_jwt`). PKCE is required for every client.

Client references: [Claude remote MCP](https://code.claude.com/docs/en/mcp),
[Claude custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp),
[OpenAI Codex MCP](https://developers.openai.com/codex/mcp/).