# Übersicht & Verbindung

Die **Maetra MCP Server** bietet Model Context Protocol-Clients fähigkeitsbasierten Zugriff auf Task Guard, Govern und Secure mit dem gleichen Workspace-API-Schlüssel wie die REST-API.

Ein verbundener Agent kann die Arbeit an einer benutzerautorisierten Aufgabe verankern, prüfen, ob vorgeschlagene Aktionen ausgerichtet bleiben, Inhalte scannen, Richtlinienbewertung oder menschliche Genehmigung anfordern, eine Genehmigung für eine genaue Ausführung verwenden und Provider-Versuche und beobachtete Effekte beibehalten.

### Beginnen Sie mit dem Flow, den Sie brauchen

Beginnen Sie mit der Genehmigung. Erstellen Sie einen API-Schlüssel und Aufruf `request_approval` vor einer geregelten Aktion. Wenn Ihre Integration nur die Genehmigungsentscheidung benötigt, ist dies der Basisfluss.

Um diese Entscheidung mit dem zu verbinden, was danach läuft, verwenden Sie Ausführungsbelege. Fügen Sie drei Aufrufe hinzu: Autorisieren Sie die genaue Anfrage, notieren Sie jeden Anbieterversuch und notieren Sie, was sich geändert hat. Ihr API-Schlüssel und Ihre MCP-Verbindung bleiben wiederverwendbar. Nur die Autorisierung für diese spezifische genehmigte Ausführung kann einmal verwendet werden.

Der MCP-Endpunkt ist:

```
https://mcp.maetra.io/mcp
```

### Auf einen Blick

|                     |                                               |
| ------------------- | --------------------------------------------- |
| **Servername** | `maetra-mcp` |
| **Fassung** | `1.0.0` |
| **MCP-Protokoll** | `2024-11-05` |
| **Transport** | HTTP, JSON-RPC 2.0 über `POST` |
| **Endpunkt** | `POST https://mcp.maetra.io/mcp` |
| **Authen** | `Authorization: Bearer maetra_...` (erforderlich) |
| **Streaming (SSE)** | Nicht aktiviert — nur Anfrage/Antwort |
| **Gesundheit** | `GET /health` |

### Authentifizierung und Zugang zu Fähigkeiten

Jede MCP-Anfrage trägt einen Workspace-API-Schlüssel:

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Ohne gültigen Schlüssel gibt der Server den JSON-RPC-Fehler zurück `-32001`. Der Workspace MCP-Zugriff muss ebenfalls aktiviert sein. Der Schlüssel [Geltungsbereiche](https://maetra.io/de/docs/getting-started/authentication), Modulberechtigungen und Arbeitsbereichskonfiguration bestimmen, welche Werkzeuge verfügbar sind.

Zu Beginn jedes neuen Benutzerwechsels oder Arbeitszyklus - und nach Kontextverdichtung, Neustart oder einer Aktualisierung des Zugriffs - rufen Sie auf:

```
get_mcp_access
```

Es gibt zurück:

* Die aktivierten `secure`, `govern`, und `task_guard` Fähigkeiten
* die genauen Werkzeuge, die derzeit für jede Fähigkeit erlaubt sind
* Erforderliches Wirtsverhalten
* kurzlebig `mcp_access_token`
* Das Token Expiration

Passieren Sie `mcp_access_token` Zu jedem späteren Maetra-fähigkeits-tool-aufruf. `get_mcp_access` ist das einzige Werkzeug, das es nicht benötigt.

> **Important**
> Cache das Fähigkeits-Token nicht über Arbeitszyklen hinweg. Erfrischen Sie es mit `get_mcp_access`, und rufen Sie niemals ein Tool auf, dessen Fähigkeit im zurückgegebenen Zugriffsdokument deaktiviert ist.


### Fähigkeitsabhängige Tools

`tools/list` ist dynamisch. Es beinhaltet immer `get_mcp_access`, enthält dann nur die Werkzeuge, die für den aktuellen Arbeitsbereich und Schlüssel zugelassen sind. Ein Arbeitsbereich mit allen aktivierten Funktionen kann bis zu 18 Werkzeuge empfangen.

| Leistungsfähigkeit | Werkzeuge |
| ---------- | ----- |
| Zugang | `get_mcp_access` |
| Task Guard | `start_task`, `get_task_context`, `check_task_alignment`, `explain_task_relationship`, `record_task_progress`, `record_action_effect`, `complete_task` |
| Secure | `check_action`, `list_active_rules`, `create_rule`, `update_rule` |
| Govern | `request_approval`, `get_approval_status`, `list_active_policies`, `authorize_execution`, `record_execution_attempt`, `record_execution_effect` |

Siehe: [Bezug auf die Werkzeuge](https://maetra.io/de/docs/mcp-server/tools-reference) für Inputs und erforderliches Verhalten.

### Verbinden eines Clients

#### Claude Desktop / Code

Fügen Sie den HTTP-Server Ihrer MCP-Client-Konfiguration hinzu:

```json
{
  "mcpServers": {
    "maetra": {
      "type": "http",
      "url": "https://mcp.maetra.io/mcp",
      "headers": {
        "Authorization": "Bearer maetra_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

#### Raw JSON-RPC

```bash
curl -X POST https://mcp.maetra.io/mcp \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "0.1.0" }
    }
  }'

curl -X POST https://mcp.maetra.io/mcp \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'
```


### Unterstützte JSON-RPC Methoden

| Methode | Verhalten |
| ----------------- | --------- |
| `initialize` | Gibt Serverfunktionen und Anweisungen für die aktivierten Maetra-Steuerelemente zurück. |
| `tools/list` | Renditen `get_mcp_access` und die derzeit zulässigen Fähigkeiten. |
| `tools/call` | Ruft ein benanntes Tool mit einem `arguments` Objekt. |
| `ping` | Keep-alive; Rücksendungen `{}`. |
| `notifications/*` | Akzeptiert und anerkannt ohne Antwortstelle. |

Der Server unterstützt gestapelte JSON-RPC-Anfragen. Batch kein Fähigkeits-Tool mit dem `get_mcp_access` aufrufen, von dem es abhängt, weil die spätere anfrage das vom preflight zurückgegebene token benötigt.