> ## Documentation Index
> Fetch the complete documentation index at: https://manager.harmix.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Довідник MCP

> Endpoint POST /v1/mcp/memory, методи JSON-RPC, автентифікація та поведінка протоколу.

Увесь трафік Memory MCP надсилайте на один endpoint. Автентифікація визначає користувача — шлях однаковий для всіх акаунтів.

## Endpoint

```
POST https://api.pam.harmix.ai/v1/mcp/memory
```

| Метод  | Шлях             | Призначення                                 |
| ------ | ---------------- | ------------------------------------------- |
| `GET`  | `/v1/mcp/memory` | SSE keep-alive для Streamable HTTP клієнтів |
| `POST` | `/v1/mcp/memory` | JSON-RPC 2.0 MCP запити                     |

## Автентифікація

Memory MCP приймає **або** статичні ключі агента, **або** OAuth Bearer tokens.

### Desktop / скрипт

```
Authorization: pam_mkey_<key>
```

Деякі клієнти додають префікс `Bearer `. Сервер приймає обидва формати для статичних ключів.

Генеруйте ключі на **[Setup](https://pam.harmix.ai/setup)** — не через цей endpoint.

### Браузерні LLM (Claude web, ChatGPT)

```
Authorization: Bearer <opaque_oauth_access_token>
```

Токени через OAuth 2.1 Authorization Code + PKCE:

| Крок                          | Endpoint                                                       |
| ----------------------------- | -------------------------------------------------------------- |
| Protected resource metadata   | `GET /.well-known/oauth-protected-resource`                    |
| Authorization server metadata | `GET /.well-known/oauth-authorization-server`                  |
| Реєстрація клієнта (DCR)      | `POST /v1/oauth/register`                                      |
| Авторизація                   | `GET /v1/oauth/authorize`                                      |
| Code / refresh                | `POST /v1/oauth/token` (`authorization_code`, `refresh_token`) |
| Відкликання                   | `POST /v1/oauth/revoke`                                        |

Scope: `memory:read`. Access token — близько 1 години; refresh token ротується при кожному оновленні, термін близько 30 днів. Повторне використання відкликаного refresh token відкликає всю сім'ю підключення.

Альтернативне discovery: `GET /.well-known/oauth-protected-resource/v1/mcp/memory`.

Див. [Налаштування клієнта](/docs/uk/client-setup).

## Методи JSON-RPC

| Метод                                    | Враховується в квотах? | Призначення                                   |
| ---------------------------------------- | ---------------------- | --------------------------------------------- |
| `initialize`                             | Ні                     | MCP handshake; повертає інформацію про сервер |
| `initialized`                            | Ні                     | Підтвердження клієнта (порожня 200)           |
| `tools/list`                             | Ні                     | Повертає схему інструменту `retrieve_memory`  |
| `resources/list`                         | Ні                     | Порожній список у v1                          |
| `prompts/list`                           | Ні                     | Порожній список у v1                          |
| **`tools/call`** + **`retrieve_memory`** | **Так**                | Retrieval контексту компанії                  |

## Відповідь tools/list

Сервер надає один інструмент у v1:

```json theme={null}
{
  "name": "retrieve_memory",
  "description": "Retrieve relevant company memory for the current user's prompt. Use when the task may depend on company-specific context: people, projects, decisions, processes, priorities, history, customers, or internal terminology. Prefer calling this before making assumptions.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": { "type": "string" },
      "session_id": { "type": "string" }
    },
    "required": ["prompt"]
  }
}
```

Повний опис параметрів і відповідей — у [retrieve\_memory](/docs/uk/retrieve-memory).

## Форма результату інструменту

Успішні та помилкові відповіді повертають HTTP 200 у такому форматі:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "# Retrieved Company Context\n\n**Query:** Хто наші основні enterprise-клієнти і які акаунти мають найвищий recurring revenue?\n\n**Summary:** Enterprise-клієнти охоплюють media і publishing; tracked MRR сконцентрований у трьох active accounts.\n\n## Relevant Facts\n\n- [97%] **Tier-1 strategic accounts включають великого broadcaster і двох enterprise publishers.**\n- [95%] **Три активні акаунти генерують задокументований monthly recurring revenue.**\n\n---\n*Retrieved 12 items | Avg relevance: 89% | Coverage: comprehensive*"
    }
  ],
  "structuredContent": {
    "status": "ok",
    "memory_ready": true,
    "readiness_state": "ready_rich",
    "content_text": "# Retrieved Company Context\n\n...",
    "triage": {
      "decision": "retrieve",
      "reasoning": "Запит залежить від company-specific client контексту."
    },
    "retrieval": {
      "context_summary": "Enterprise-клієнти охоплюють media і publishing; tracked MRR сконцентрований у трьох active accounts.",
      "total_items": 12,
      "avg_relevance_score": 0.89,
      "coverage_assessment": "comprehensive"
    },
    "diagnostics": {
      "request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
      "duration_ms": 48210,
      "estimated_tokens": 8400
    }
  },
  "isError": false
}
```

Помилки на рівні інструменту мають `isError: true` і `structuredContent.error_code`:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Ви досягли тижневого ліміту Memory MCP. Спробуйте знову після понеділка 00:00 UTC або зменшіть частоту викликів retrieve_memory."
    }
  ],
  "structuredContent": {
    "status": "error",
    "error_code": "quota_exceeded",
    "error_message": "Ви досягли тижневого ліміту Memory MCP. Спробуйте знову після понеділка 00:00 UTC або зменшіть частоту викликів retrieve_memory."
  },
  "isError": true
}
```

## Приклад: tools/call

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "retrieve_memory",
    "arguments": {
      "prompt": "Хто наші основні enterprise-клієнти і які акаунти мають найвищий recurring revenue?",
      "session_id": "cursor-thread-k7m2p"
    }
  }
}
```

## Session ID та MCP-заголовки

Сервер може повертати заголовок `Mcp-Session-Id` під час MCP handshake. `session_id` в аргументах інструменту **необов'язковий** — якщо не передано, сервер використовує цей MCP session ID для виклику.

Явний `session_id` перевизначає handshake ID (наприклад, один ID на thread агента). Сервер зберігає останні **5 prompt** на session у Redis (TTL 30 днів) і може додати останні **3** prompt лише на етап **triage** при наступному виклику, коли triage увімкнено. Це легка server-side підказка, а не повний контекст розмови.

## Пов'язані розділи

* [retrieve\_memory](/docs/uk/retrieve-memory) — параметри інструменту та поля відповіді
* [Квоти та ліміти](/docs/uk/quotas-and-limits) — що враховується в лімітах
* [Коди помилок](/docs/uk/error-codes) — усі значення `error_code`
* [API для розробників](/docs/uk/developer-api-overview) — керування ключами та історія запитів