# Подключение Cursor, Claude и ChatGPT к MM Table через MCP

Прод MCP: `https://mmtable.crystalsystems.ru/mcp`  
Локально: `http://127.0.0.1:4173/mcp`

## Cursor (Bearer PAT)

**Инструкция для сотрудников:** [cursor-mcp-guide/](./cursor-mcp-guide/) · [открыть HTML](./cursor-mcp-guide/index.html)

1. Войдите в MM Table.
2. Меню → **Профиль** → блок **MCP / Cursor / Claude**.
3. **Создать токен** → скопировать `mmt_...` (один раз).
4. **Копировать конфиг** → вставить в Cursor (`Settings → Tools & MCP` → `mcp.json`):

```json
{
  "mcpServers": {
    "mmtable": {
      "url": "https://mmtable.crystalsystems.ru/mcp",
      "headers": {
        "Authorization": "Bearer mmt_..."
      }
    }
  }
}
```

## Claude (OAuth 2.1)

Custom connector на [claude.ai/customize/connectors](https://claude.ai/customize/connectors) (Pro/Max/Team; на Free — один connector).

1. **+** → **Add custom connector**
2. URL: `https://mmtable.crystalsystems.ru/mcp`
3. Advanced / OAuth Client ID/Secret — **не нужны** (DCR)
4. **Add** → **Connect** → логин MM Table → **Разрешить**
5. В чате: **+** → Connectors → включите MM Table

Альтернатива без OAuth: Request headers → `Authorization: Bearer mmt_...` (тот же PAT, что для Cursor).

OAuth callback Claude: `https://claude.ai/api/mcp/auth_callback`. Claude Code использует loopback `http://localhost:<port>/callback`.

## ChatGPT (OAuth 2.1)

**Инструкция со скриншотами:** [chatgpt-mcp-guide/](./chatgpt-mcp-guide/) · [открыть HTML](./chatgpt-mcp-guide/index.html)

PAT в ChatGPT обычно вставить нельзя — нужен OAuth.

1. Settings → Apps → Advanced → **Developer mode**
2. **Create** → URL `https://mmtable.crystalsystems.ru/mcp`, Auth = **OAuth**
3. Войдите email/паролем MM Table и разрешите доступ
4. В чате: **+** → Developer mode → включите MM Table

ChatGPT / Claude получают пару токенов:
- `access_token` (`oat_...`) — ~1 час
- `refresh_token` (`ort_...`) — ~90 дней (silent refresh, как у Notion)

Discovery endpoints:

| URL | Назначение |
|-----|------------|
| `/.well-known/oauth-protected-resource` | resource + authorization_servers |
| `/.well-known/oauth-authorization-server` | authorize / token / register |
| `/oauth/register` | Dynamic Client Registration |
| `/oauth/authorize` | login + consent + auth code + PKCE |
| `/oauth/token` | обмен code → access token |

Поддерживается CIMD (`client_id_metadata_document_supported: true`) и DCR. PKCE: только `S256`.

## Возможности (tools)

| Tool | Назначение |
|------|------------|
| `list_documents` | список документов |
| `create_document` | новый документ |
| `get_document_overview` | листы, BP, таблицы |
| `describe_sheet` | snapshot листа (ids) |
| `create_sheet` / `rename_sheet` / `delete_sheet` | листы документа |
| `create_shape` / `update_shape` / `delete_shapes` / `move_shapes` | фигуры |
| `create_table` / `get_table` / `set_table_cells` | таблицы |
| `create_business_process` / `list_business_processes` / `delete_business_process` | BP целиком |
| `add_bp_stage` / `update_bp_stage` / `delete_bp_stage` | стадии |
| `add_bp_task` / `update_bp_task` / `delete_bp_task` | задачи (поля формы + results) |
| `add_bp_automation` / `update_bp_automation` / `delete_bp_automation` | автоматизации (when/conditions/results) |
| `connect_shapes` | связи |

## REST API

Тот же функционал доступен как Bearer REST (`mmt_...` или OAuth `oat_...`):

- `GET/POST /api/v1/docs`
- `GET /api/v1/docs/<id>`
- `POST /api/v1/docs/<id>/sheets` — создать лист (`name`, `activate`)
- `PATCH/DELETE /api/v1/docs/<id>/sheets/<sheetId>` — переименовать / удалить
- object endpoints под `/api/v1/docs/<id>/...`

Scopes: `docs:read`, `docs:write`.

## Ограничения v1

- Нет raw-записи всего `layout_json` через MCP.
- Нет Bitrix / freedraw / image.
- Для записи нужна роль `editor+` на документ.
- OAuth access ~1 час, refresh ~90 дней (с ротацией refresh token).

Контракт данных: [MCP_LAYOUT_CONTRACT.md](./MCP_LAYOUT_CONTRACT.md).