---
type: how-to
title: Den MCP-Server nutzen
summary: Verbinde einen KI-Agenten über den MCP-Server mit Caputchin, authentifizier ihn mit einem Access Token und steuer die Management-API in natürlicher Sprache, mit einem ausgearbeiteten Beispiel.
---

Der Caputchin-MCP-Server lässt einen KI-Agenten (Claude, Cursor oder jeden [Model-Context-Protocol](https://modelcontextprotocol.io)-Client) dein Konto verwalten, indem er dieselbe [Management-API](/docs/automation/management-api) aufruft, die das Dashboard nutzt. Der Server ist eine dünne Transport-und-Auth-Hülle: er stellt ein MCP-Tool pro Management-Operation bereit und reicht jeden Aufruf an die API weiter. So kann der Agent alles tun, was du kannst, außer Abrechnung, in natürlicher Sprache.

## Ein Access Token prägen [#mint-an-access-token]

Der Server authentifiziert sich mit einem Access Token aus der Umgebungsvariable `CAPUTCHIN_TOKEN`. Beide Arten funktionieren (siehe [API-Authentifizierung](/docs/automation/management-api#mint-an-access-token)):

- ein [Personal Access Token](/docs/account-management/personal-access-token) für volle Konto-Kontrolle, oder
- ein [Troop Access Token](/docs/troops/tokens), um den Agenten mit Least Privilege auf bestimmte Teams einzuschränken, was der sicherere Standard ist, wenn du einem autonomen Agenten Zugriff gibst.

Kopier den Token bei der Erstellung; er wird einmal gezeigt.

## Zwei Wege zu verbinden

Es gibt zwei Transporte, und sie stellen die **gleichen Tools** bereit, gestützt auf dieselbe Management-API. Wähl danach, wie dein Client sich verbindet:

| | Lokal (stdio) | Gehostet (HTTP) |
|---|---|---|
| Was es ist | Das `@caputchin/mcp`-Paket, ausgeführt auf deiner Maschine | Ein entfernter Endpunkt unter `api.caputchin.com/mcp` |
| Client braucht | Einen lokalen Prozess zu starten (stdio) | Sich mit einem entfernten MCP-Server zu verbinden (HTTP) |
| Auth | `CAPUTCHIN_TOKEN` in der Prozessumgebung | `Authorization: Bearer`-Header auf der Verbindung |
| Am besten wenn | Lokale Entwicklung, ein Desktop-Client, kein eingehendes Netzwerk | Ein gehosteter Agent, kein lokaler Prozess zu starten |

### Lokal: der npx-Server (stdio)

Der Server ist als `@caputchin/mcp` auf npm veröffentlicht. Du führst ihn meist nicht von Hand aus; du verdrahtest ihn in die Config deines MCP-Clients, und er wird über stdio gestartet, mit dem Token in seiner Umgebung:

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

Um zu prüfen, dass er läuft, starte ihn direkt; er spricht MCP über stdio und beendet sich mit einem Fehler, wenn der Token fehlt:

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### Gehostet: der HTTP-Endpunkt

Für Clients, die sich mit einem entfernten MCP-Server verbinden, statt einen lokalen zu starten, hostet Caputchin denselben Server unter:

```
https://api.caputchin.com/mcp
```

Er authentifiziert sich mit deinem Token als `Bearer`-Header auf der Verbindung (dieselbe Anmeldedatei, nur über HTTP statt über die Umgebung übergeben):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

Die genaue Config-Form hängt von deinem MCP-Client ab; was zählt, ist die URL und der `Authorization: Bearer`-Header. Nichts zu installieren und kein lokaler Prozess; der Kompromiss ist, dass der Token pro Anfrage zum gehosteten Endpunkt reist, statt in einer lokalen Prozessumgebung zu bleiben.

## Die Tools

Jedes Tool heißt `caputchin_<verb>_<noun>` und bildet eine Management-Operation ab, zum Beispiel `caputchin_list_troops`, `caputchin_create_site`, `caputchin_rotate_site_secret`, `caputchin_add_troop_member`, `caputchin_site_stats`. Der Agent entdeckt den vollständigen Satz und die Parameter jedes Tools automatisch über MCP, also beschreibst du das Ziel und der Agent wählt die Tools.

## Ein ausgearbeitetes Beispiel

Mit dem in deinen Client verdrahteten Server kannst du den Agenten in einfacher Sprache fragen:

> "Erstell einen Site-Key namens shop-frontend in meinem shop-team-Team, dann schalt das Spiel-Gate dafür ein."

Der Agent löst das in eine Folge von Tool-Aufrufen auf: `caputchin_list_troops`, um die Team-id zu finden, `caputchin_create_site` mit dieser `troop_id`, dann `caputchin_update_site_security`, um ein Spiel zu verlangen. Jeder Aufruf trifft die Management-API unter deinem Token, und auf Apex landet jeder in deinem [Audit-Log](/docs/audit-logs/overview), dem Token zugeschrieben, sodass die Aktionen eines Agenten so nachverfolgbar sind wie die einer Person.

Weil der Agent mit der vollen Reichweite deines Tokens agiert, bevorzug ein eingeschränktes Team-Token, wenn du kannst, und widerruf es in dem Moment, in dem die Aufgabe erledigt ist.

## Die vollständige Referenz

Für die vollständige Liste der Tools, jedes mit einer einzeiligen Beschreibung und der Berechtigung, die sein Token halten muss, sieh dir die [MCP-Tools-Referenz](/docs/automation/mcp-tools) an. Die Tools spiegeln die Management-API eins zu eins, also ist die [interaktive API-Referenz](/docs/api-reference) die maßgebliche Beschreibung der Parameter und Antwort jeder Operation: lies die MCP-Beschreibung eines Tools für die agenten-gewandte Zusammenfassung und die API-Referenz für das genaue Schema.

## Siehe auch

- [MCP-Tools-Referenz](/docs/automation/mcp-tools): jedes Tool, seine Beschreibung und die Berechtigung, die es braucht.
- [Caputchin über die API verwalten](/docs/automation/management-api): die HTTP-API, die jedes Tool aufruft.
- [Terraform oder OpenTofu nutzen](/docs/automation/terraform): die Infrastructure-as-Code-Fläche.
- [Personal Access Token](/docs/account-management/personal-access-token) und [Team-Tokens](/docs/troops/tokens): die Anmeldedaten, die der Server nutzt.