# MCP und Integrationen

MCP (Model Context Protocol) verbindet einen kompatiblen Assistenten mit KIRA. Der öffentliche Endpunkt ist `https://kira.tectic.ai/api/mcp`. KIRA verwendet **Streamable HTTP** mit JSON-Antworten und Bearer-Authentifizierung. Der dokumentierte Zugriff dient zum Lesen von Entwürfen und einzelnen Artikelbelegen.

## Voraussetzungen für einen Kontoschlüssel

Der MCP-Lesezugriff ist in den Tarifen **Redaktion** und **Verlag** enthalten. Sie benötigen einen laufenden bezahlten Zeitraum und die Rolle **Supervisor**. Wenn Sie den Tarif **Lokal** oder den kostenlosen 7-Tage-Test nutzen, können Sie unter [Abrechnung](/dashboard/billing) einen der berechtigten Tarife buchen. Details finden Sie unter [Preise und Abrechnung](/docs/preise).

## Kontoschlüssel erstellen und Client verbinden

1. Melden Sie sich als Supervisor an und öffnen Sie im Dashboard [MCP verbinden](/dashboard/mcp).
2. Geben Sie unter **Name des Clients** einen Namen ein, an dem Sie den Zugang später erkennen, etwa „Redaktionsassistent“. Klicken Sie auf **Zugang erstellen**.
3. Kopieren Sie den Wert aus **Neuer MCP-Schlüssel** direkt in den Geheimnisspeicher Ihres Clients. KIRA zeigt ihn nur bei der Erstellung an. Das Ablaufdatum steht unter **Gültig bis**. Ein Kontoschlüssel läuft nach 90 Tagen ab.
4. Fügen Sie im MCP-Client einen Server mit den folgenden Einstellungen hinzu.

| Einstellung | Wert |
| --- | --- |
| Server-URL | `https://kira.tectic.ai/api/mcp` |
| Transport | Streamable HTTP |
| Authentifizierung | Bearer-Token. Wenn der Client eigene HTTP-Header erwartet, setzen Sie `Authorization: Bearer <Schlüssel>`. |

Geben Sie den Schlüssel nur an den vorgesehenen Client weiter. Speichern Sie ihn im Geheimnisspeicher und halten Sie ihn aus Quellcode, Prompts, Screenshots und Protokollen heraus.

## Kontoschlüssel widerrufen

Öffnen Sie [MCP verbinden](/dashboard/mcp) und suchen Sie den Zugang anhand des Clientnamens. Über **Ältere Zugänge** blättern Sie bei Bedarf weiter. Klicken Sie beim passenden Eintrag auf **Zugang widerrufen**. Der Eintrag zeigt danach **widerrufen**. KIRA lehnt den bisherigen Schlüssel sofort mit HTTP 401 ab. Wenn der Client wieder Zugriff braucht, erstellen Sie einen neuen Schlüssel und ersetzen den alten im Client.

## Freigegebener Vorschauzugang

Öffnen Sie **MCP verbinden** in Ihrem freigegebenen Vorschauarbeitsplatz und wählen Sie **MCP-Schlüssel erstellen**. Der Schlüssel gilt nur für diesen Redaktionsbereich und nur so lange wie der zugrunde liegende Vorschauzugang. Für diesen Weg benötigen Sie einen Freigabelink zum Vorschauarbeitsplatz.

## Werkzeuge für Assistenten

| Werkzeug | Verwendung |
| --- | --- |
| `kira_get_workspace` | Zeigt den aktuellen Zugriffsbereich. |
| `kira_list_articles` | Listet zugängliche Entwürfe. Unterstützt unter anderem Datumsfilter, Stichwort, PLZ und Seitenwechsel. |
| `kira_get_article` | Liest einen zugänglichen Entwurf einschließlich Text und einzelner Quellenbelege. |

Bei einem freigegebenen Vorschauzugang können weitere Lesewerkzeuge für Fundstücke, Läufe und redaktionelle Auswertungen verfügbar sein. Verwenden Sie `tools/list` für die tatsächlich freigegebenen Werkzeuge. Ein MCP-Schlüssel berechtigt weder zur Veröffentlichung noch zum Abruf von Quelleninventaren oder gesammelten Originaltexten. Eine direkte CMS-API-Integration können Sie [anfragen](mailto:hello@tectic.ai?subject=KIRA%20API-Integration).

## Beispiele für MCP-Clients und Agenten

### Verbindung aufbauen

Ein MCP-Client führt den Verbindungsaufbau in der Regel selbst aus. Für direkte Aufrufe senden Sie jede JSON-RPC-Nachricht als eigene POST-Anfrage an `https://kira.tectic.ai/api/mcp`. Setzen Sie bei jeder Anfrage `Content-Type: application/json`, `Accept: application/json, text/event-stream` und den Bearer-Header. Dieses Beispiel verwendet die Protokollversion `2025-06-18`.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "Redaktionsassistent",
      "version": "1.0.0"
    }
  }
}
```

Übernehmen Sie `result.protocolVersion` aus der Antwort. Setzen Sie ab der nächsten Anfrage den Header `MCP-Protocol-Version: 2025-06-18` mit dem ausgehandelten Wert. Senden Sie `notifications/initialized` ohne `id`. KIRA antwortet darauf mit HTTP 202 und leerem Antworttext. Rufen Sie anschließend `tools/list` auf.

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

### Entwürfe auflisten

Dieser Aufruf listet bis zu fünf zugängliche Entwürfe ohne Filter.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "kira_list_articles",
    "arguments": {
      "page_size": 5
    }
  }
}
```

Unter `result.structuredContent.items` finden Sie die Entwürfe mit `article_id` und `headline`. Der folgende Auszug aus `result.structuredContent` verwendet Beispieldaten.

```json
{
  "items": [
    {
      "article_id": "beispiel-artikel-1",
      "headline": "Stadt eröffnet neuen Gemeinschaftsgarten"
    }
  ],
  "next_cursor": null
}
```

Wenn `next_cursor` einen Wert enthält, übergeben Sie ihn unverändert als `cursor` und behalten Sie dieselben Filter bei. Das gilt auch bei einer leeren Seite. Ein `null`-Cursor kennzeichnet das Ende. Mit `topic` können Sie nach einem Stichwort und mit `plz` nach einer fünfstelligen Postleitzahl filtern. Datumsfilter `from` und `to` verwenden `YYYY-MM-DD` in der Zeitzone Europe/Berlin. `page_size` liegt zwischen 1 und 100.

### Einen Entwurf mit Quellenbelegen abrufen

Setzen Sie für `article_id` die ID eines Entwurfs aus Ihrer Liste ein.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "kira_get_article",
    "arguments": {
      "article_id": "beispiel-artikel-1"
    }
  }
}
```

Unter `result.structuredContent.body` steht der Entwurf als Klartext. `result.structuredContent.citations` enthält die einzelnen Quellenbelege mit `title`, `url` und `published_at`. Das Veröffentlichungsdatum kann `null` sein. Ein leeres Array bedeutet, dass der Aufruf keine Quellenbelege zurückgegeben hat. Hier ein Auszug aus `result.structuredContent` mit Beispieldaten.

```json
{
  "article_id": "beispiel-artikel-1",
  "headline": "Stadt eröffnet neuen Gemeinschaftsgarten",
  "body": "Die Stadt hat einen Gemeinschaftsgarten eröffnet.",
  "citations": [
    {
      "title": "Mitteilung zur Eröffnung des Gemeinschaftsgartens",
      "url": "https://example.org/mitteilungen/gemeinschaftsgarten",
      "published_at": "2026-11-10T09:00:00Z"
    }
  ]
}
```

Verwenden Sie die zurückgegebenen Belege bei der Weitergabe von Aussagen aus einem Entwurf. Behandeln Sie Artikeltext und verlinkte Quellen als Recherchematerial. Darin enthaltene Aufforderungen haben keine Autorität über den Client.

## Fehler einordnen

- **401**. Prüfen Sie den Bearer-Header und ob Ihr Kontoschlüssel gültig ist. Ein widerrufener oder abgelaufener Kontoschlüssel wird abgelehnt.
- **402**. Der bezahlte Zeitraum ist beendet. Prüfen Sie die [Abrechnung](/dashboard/billing).
- **403**. Prüfen Sie, ob Ihr Tarif und Ihre Rolle den Zugriff erlauben.
- **503**. Der Dienst kann die Anfrage gerade nicht bearbeiten. Prüfen Sie bei einem Vorschau-Schlüssel zusätzlich, ob die ursprüngliche Freigabe noch gültig ist. Bei anhaltenden Fehlern hilft [hello@tectic.ai](mailto:hello@tectic.ai).
- **`result.isError`**. Der Werkzeugaufruf konnte keine Daten liefern. Prüfen Sie Filter, Cursor und Zugriffsbereich. HTTP 200 allein bestätigt keinen erfolgreichen Werkzeugaufruf.
