---
title: MCP server — technický manuál
order: 2
description: Endpoint, auth, dostupné tooly, JSON-RPC formát.
---
# MCP server — technický manuál

JÁ² Akademie implementuje **MCP Streamable HTTP transport** (jeden POST endpoint, JSON-RPC 2.0).

---

## Endpoint

```
POST /api/mcp
Content-Type: application/json
Authorization: Bearer <tvuj-token>
```

Token získáš v `/konektory` po přihlášení. Format `ak2_xxxxx` (32 base64url znaků). SHA-256 hashed v DB — plain text se ti zobrazí **jen 1×** při vygenerování.

---

## JSON-RPC 2.0 methods

| Method | Auth | Co dělá |
|---|---|---|
| `initialize` | bez | Handshake (`protocolVersion: "2024-11-05"`) |
| `notifications/initialized` | bez | Ack od klienta (no response) |
| `tools/list` | Bearer | Seznam všech tools |
| `tools/call` | Bearer | Spustí konkrétní tool |

### Error codes

| Code | Význam |
|---|---|
| `-32700` | Parse error (invalid JSON) |
| `-32600` | Invalid Request |
| `-32601` | Method not found |
| `-32602` | Invalid params |
| `-32603` | Internal error |
| `-32001` | Unauthorized (chybí token, neznámý, revoked) |

---

## Dostupné tooly

### Kontext (čtení)

| Tool | Co vrátí |
|---|---|
| `ja2_bootstrap` | All-in-one payload (kontext + značky + projekty + tools manifest + Angel operating instructions) |
| `ja2_get_personal_context` | Osobní vrstva (5 slotů) |
| `ja2_get_expert_context` | Expertní vrstva (2 sloty) |
| `ja2_get_angel_context` | Angel persona (jak má mluvit) |
| `ja2_list_brands` | Seznam značek + počet vyplněných slotů |
| `ja2_get_brand(brand_id)` | Kontext konkrétní značky |
| `ja2_list_projects` | Seznam projektů |
| `ja2_get_project(project_id)` | **3-tier merged** kontext: project + brand + global + user-meta |
| `ja2_get_my_crm` | CRM profil — registrace, vstupenky, vouchery, support history (jen tvoje data, strict isolation) |

### Kontext (zápis)

| Tool | Args | Co dělá |
|---|---|---|
| `ja2_update_context` | scope, file_type, content_md, action | Přímý zápis (pro „zapamatuj si že…") |
| `ja2_log_insight` | content_md, proposed_layer, confidence | Návrh změny → review v `/checkpoint` |

### Studio (workspace, jen power user)

Vyžaduje permission `akademie.workspace`. Bez ní tooly vrátí Forbidden.

| Tool | Co dělá |
|---|---|
| `ja2_workspace_index` | **Preferovaný entry** — overview všech files s headings, tagy, summary, by_folder, tags_index |
| `ja2_workspace_outline(path)` | Heading tree jednoho souboru bez načtení celku |
| `ja2_workspace_read(path)` | Načti konkrétní soubor |
| `ja2_workspace_search(query)` | Fuzzy full-text search |
| `ja2_workspace_grep(pattern, is_regex?, case_sensitive?)` | Precision regex search s line context |
| `ja2_workspace_list` | Plain list paths (lightweight, preferuj index) |
| `ja2_workspace_write(path, content_md, title?)` | Upsert soubor |

---

## Klient: doporučený workflow

```
1. initialize           → handshake
2. tools/list           → vidíš, co máš k dispozici
3. tools/call ja2_bootstrap → načti celý kontext (1× za session)
4. … další tools podle potřeby …
```

---

## Tools manifest (bez auth)

Bezpečný discovery endpoint pro statickou kontrolu — vrátí JSON s manifest tools (bez user data):

```
GET /api/mcp/tools
```

Vrátí: `{ tools: [{name, description, args?}, ...] }`. Tento endpoint **nevyžaduje** Bearer token (jen čtení manifestu).

---

## Raw dokumentace pro AI

Pokud jsi AI agent (např. Claude), můžeš si stáhnout tuto stránku jako čistý markdown:

```
GET /api/docs/mcp
```

Vrátí `text/markdown; charset=utf-8` bez HTML formátování. Hodí se pro RAG / reference.