# MCP-Server

> KI-Assistenten über das Model Context Protocol mit HILLS verbinden: Server-URL, OAuth-Anmeldung, wer sich verbinden kann, und die Tools.

<!-- Generated from openapi/hills-mcp.json by scripts/mcp-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

Über den HILLS Music MCP-Server lesen KI-Assistenten, die das [Model Context Protocol](https://modelcontextprotocol.io) unterstützen, Ihren Workspace: Katalog, Release-Status, Streams und Erlöse, Abrechnungen und Anfragen. Jeder Aufruf läuft als das HILLS-Konto, das die Verbindung hergestellt hat, und sieht genau das, was dieses Konto im Workspace sieht.

<a id="connect"></a>

## Verbinden

| | |
| --- | --- |
| Server-URL | `https://mcp.hillsmusic.com` |
| Transport | Streamable HTTP, zustandslos: JSON-RPC-Nachrichten per POST, Antworten als JSON (kein Server-Sent-Stream, keine Session). GET und DELETE antworten mit 405. |
| Anmeldung | OAuth 2.1 mit Ihrem HILLS-Konto (Scope `read`) |
| Rate Limit | 120 Aufrufe pro Minute und verbundener App |

Fügen Sie die Server-URL in Ihrem Assistenten als Remote-MCP-Server (Custom Connector) hinzu. Er öffnet eine HILLS-Anmeldung, Sie bestätigen die Verbindung, und die Tools erscheinen. Trennen können Sie die Verbindung jederzeit in der HILLS Web-App unter Settings, Connected apps.

<a id="authorization"></a>

## Autorisierung

HILLS ist der OAuth-2.1-Autorisierungsserver, der MCP-Endpunkt die geschützte Ressource. Eine Anfrage ohne gültiges Token erhält 401 mit einem WWW-Authenticate-Header, der die Resource-Metadaten nennt – so finden MCP-Clients heraus, wo die Anmeldung erfolgt. Clients registrieren sich selbst (Dynamic Client Registration), der Nutzer bestätigt die Verbindung in der HILLS Web-App, und jeder Tool-Aufruf läuft als dieses Konto.

| | |
| --- | --- |
| Resource-Metadaten | `https://mcp.hillsmusic.com/.well-known/oauth-protected-resource` |
| Metadaten des Autorisierungsservers | `https://mcp.hillsmusic.com/.well-known/oauth-authorization-server` |
| Scope `read` | Lesezugriff auf Ihren Katalog, Ihre Streams und Abrechnungen |
| PKCE | Nur S256 |
| Access-Tokens | Gültig für 1 Stunde |
| Refresh-Tokens | Gültig für 30 Tage, bei jeder Verwendung rotiert (ein erneut verwendetes Token beendet die Verbindung) |

<a id="who-can-connect"></a>

## Wer sich verbinden kann

- Kunden (Partnerkonten) und ihre Teammitglieder, Inhaber und Admins: standardmäßig aktiviert.
- Artists und Labels mit eigenem HILLS-Konto sowie weitere Mitarbeitende: wenn das HILLS-Team den Zugang freischaltet.
- Artists und Labels unter einem Kunden: nie; MCP gehört dem Kunden.
- Einige Tools sind nur für Kundenkonten da (Guthaben und Auszahlungen auch für direkte Artists und Labels, an die HILLS auszahlt); ein Konto, das ein Tool nicht nutzen darf, sieht es nicht.
- Ein Teammitglied eines Kunden braucht die Rollenberechtigung, die beim jeweiligen Tool steht; das HILLS-Team sieht, was seine Rollenberechtigungen freigeben.

## Tools

| Tool | Was es tut | Wer es erhält |
| --- | --- | --- |
| [`list_members`](https://developer.hillsmusic.com/de/mcp/list-members/) | Artists und Labels auflisten | Nur Kundenkonten und ihr Team |
| [`payouts`](https://developer.hillsmusic.com/de/mcp/payouts/) | Guthaben und Auszahlungen | Nur bestimmte Konten |
| [`smartlinks`](https://developer.hillsmusic.com/de/mcp/smartlinks/) | Smart Links | Nur Kundenkonten und ihr Team |
| [`list_deliveries`](https://developer.hillsmusic.com/de/mcp/list-deliveries/) | DDEX-Auslieferungen | Nur Kundenkonten und ihr Team |
| [`delivery_status`](https://developer.hillsmusic.com/de/mcp/delivery-status/) | Status einer Auslieferung | Nur Kundenkonten und ihr Team |
| [`search_catalog`](https://developer.hillsmusic.com/de/mcp/search-catalog/) | Katalog durchsuchen | Jedes Konto mit MCP-Zugang |
| [`release_status`](https://developer.hillsmusic.com/de/mcp/release-status/) | Release-Status | Jedes Konto mit MCP-Zugang |
| [`streams_and_revenue`](https://developer.hillsmusic.com/de/mcp/streams-and-revenue/) | Streams und Erlöse | Jedes Konto mit MCP-Zugang |
| [`statements`](https://developer.hillsmusic.com/de/mcp/statements/) | Abrechnungen | Jedes Konto mit MCP-Zugang |
| [`requests`](https://developer.hillsmusic.com/de/mcp/requests/) | Anfragen | Jedes Konto mit MCP-Zugang |

<a id="what-assistants-are-told"></a>

## Was Assistenten mitgeteilt wird

Der Server gibt jedem Assistenten beim Verbinden diese Anweisungen mit (im Original, auf Englisch):

> HILLS Music distribution data for the signed-in account, read-only. Find releases with search_catalog, then use their ids with release_status and streams_and_revenue. Streams and revenue come from monthly store statements (USD, net of the store's share), usually 1–3 months behind, so there are no daily or weekly figures — say so when asked for days or weeks and use the latest months instead. Everything is limited to what this account can see in the HILLS workspace.

Quelle: https://developer.hillsmusic.com/de/mcp/overview/