# MCP server

> Kết nối trợ lý AI với HILLS qua Model Context Protocol: URL server, đăng nhập OAuth, ai có thể kết nối và các công cụ.

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

MCP server của HILLS Music cho phép các trợ lý AI hỗ trợ [Model Context Protocol](https://modelcontextprotocol.io) đọc không gian làm việc của bạn: danh mục, trạng thái bản phát hành, lượt nghe và doanh thu, sao kê và các yêu cầu. Mọi lệnh gọi chạy dưới tài khoản HILLS đã kết nối và thấy đúng những gì tài khoản đó thấy trong không gian làm việc.

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

## Kết nối

| | |
| --- | --- |
| URL server | `https://mcp.hillsmusic.com` |
| Transport | Streamable HTTP, không trạng thái: gửi message JSON-RPC bằng POST, phản hồi JSON (không có luồng server-sent, không có session). GET và DELETE trả về 405. |
| Đăng nhập | OAuth 2.1 bằng tài khoản HILLS của bạn (scope `read`) |
| Rate limit | 120 lệnh gọi mỗi phút cho mỗi ứng dụng đã kết nối |

Thêm URL server dưới dạng một MCP server từ xa (custom connector) trong trợ lý của bạn. Trợ lý sẽ mở trang đăng nhập HILLS, bạn chấp thuận kết nối, và các công cụ xuất hiện. Bạn có thể ngắt kết nối bất cứ lúc nào tại Settings, Connected apps trong ứng dụng web HILLS.

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

## Ủy quyền

HILLS là authorization server OAuth 2.1, và endpoint MCP là resource được bảo vệ. Request không có token hợp lệ nhận 401 với header WWW-Authenticate chỉ đến metadata của resource: đó là cách các MCP client biết nơi cần đăng nhập. Client tự đăng ký (dynamic client registration), người dùng chấp thuận kết nối trong ứng dụng web HILLS, và mọi lệnh gọi công cụ chạy dưới tài khoản đó.

| | |
| --- | --- |
| Metadata của resource | `https://mcp.hillsmusic.com/.well-known/oauth-protected-resource` |
| Metadata của authorization server | `https://mcp.hillsmusic.com/.well-known/oauth-authorization-server` |
| Scope `read` | Quyền chỉ đọc danh mục, lượt nghe và sao kê của bạn |
| PKCE | Chỉ S256 |
| Access token | Hiệu lực 1 giờ |
| Refresh token | Hiệu lực 30 ngày, được xoay vòng mỗi lần dùng (dùng lại token cũ sẽ chấm dứt kết nối) |

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

## Ai có thể kết nối

- Khách hàng (tài khoản đối tác) và thành viên nhóm của họ, chủ tài khoản và quản trị viên: bật mặc định.
- Nghệ sĩ và hãng đĩa có tài khoản HILLS riêng, và các nhân viên khác: khi đội ngũ HILLS bật quyền này.
- Nghệ sĩ và hãng đĩa thuộc một khách hàng: không bao giờ; MCP thuộc về khách hàng.
- Một số công cụ chỉ dành cho tài khoản khách hàng (số dư và rút tiền: cả nghệ sĩ và hãng đĩa trực tiếp, những người được HILLS thanh toán); tài khoản không dùng được một công cụ sẽ không thấy công cụ đó.
- Thành viên nhóm của khách hàng cần quyền vai trò mà mỗi công cụ yêu cầu; nhân viên HILLS thấy những gì quyền vai trò của họ cho phép.

<a id="tools"></a>

## Công cụ

| Công cụ | Chức năng | Ai được dùng |
| --- | --- | --- |
| [`list_members`](https://developer.hillsmusic.com/vi/mcp/list-members/) | Liệt kê nghệ sĩ và hãng đĩa | Chỉ tài khoản khách hàng và nhóm của họ |
| [`payouts`](https://developer.hillsmusic.com/vi/mcp/payouts/) | Số dư và rút tiền | Chỉ một số tài khoản |
| [`smartlinks`](https://developer.hillsmusic.com/vi/mcp/smartlinks/) | Smart link | Chỉ tài khoản khách hàng và nhóm của họ |
| [`list_deliveries`](https://developer.hillsmusic.com/vi/mcp/list-deliveries/) | Phân phối DDEX | Chỉ tài khoản khách hàng và nhóm của họ |
| [`delivery_status`](https://developer.hillsmusic.com/vi/mcp/delivery-status/) | Trạng thái phân phối | Chỉ tài khoản khách hàng và nhóm của họ |
| [`search_catalog`](https://developer.hillsmusic.com/vi/mcp/search-catalog/) | Tìm trong danh mục | Mọi tài khoản có quyền truy cập MCP |
| [`release_status`](https://developer.hillsmusic.com/vi/mcp/release-status/) | Trạng thái bản phát hành | Mọi tài khoản có quyền truy cập MCP |
| [`streams_and_revenue`](https://developer.hillsmusic.com/vi/mcp/streams-and-revenue/) | Lượt nghe và doanh thu | Mọi tài khoản có quyền truy cập MCP |
| [`statements`](https://developer.hillsmusic.com/vi/mcp/statements/) | Sao kê | Mọi tài khoản có quyền truy cập MCP |
| [`requests`](https://developer.hillsmusic.com/vi/mcp/requests/) | Yêu cầu | Mọi tài khoản có quyền truy cập MCP |

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

## Trợ lý AI được hướng dẫn những gì

Server gửi cho mọi trợ lý các hướng dẫn sau khi kết nối (trích nguyên văn tiếng Anh, đúng như server gửi):

> 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.

Nguồn: https://developer.hillsmusic.com/vi/mcp/overview/