# Servidor MCP

> Conecte assistentes de IA à HILLS pelo Model Context Protocol: URL do servidor, login OAuth, quem pode conectar e as ferramentas.

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

O servidor MCP da HILLS Music permite que assistentes de IA compatíveis com o [Model Context Protocol](https://modelcontextprotocol.io) leiam o seu espaço de trabalho: catálogo, status dos lançamentos, streams e receita, relatórios de royalties e solicitações. Cada chamada roda como a conta HILLS que fez a conexão e vê o que essa conta vê no espaço de trabalho.

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

## Conectar

| | |
| --- | --- |
| URL do servidor | `https://mcp.hillsmusic.com` |
| Transporte | Streamable HTTP, sem estado: mensagens JSON-RPC via POST, respostas em JSON (sem stream enviado pelo servidor, sem sessão). GET e DELETE respondem 405. |
| Login | OAuth 2.1 com a sua conta HILLS (escopo `read`) |
| Limite de chamadas | 120 chamadas por minuto por app conectado |

Adicione a URL do servidor como servidor MCP remoto (conector personalizado) no seu assistente. Ele abre um login da HILLS, você aprova a conexão e as ferramentas aparecem. Desconecte quando quiser em Settings, Connected apps no app web da HILLS.

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

## Autorização

A HILLS é o servidor de autorização OAuth 2.1, e o endpoint MCP é o recurso protegido. Uma requisição sem token válido recebe 401 com WWW-Authenticate indicando os metadados do recurso, e é assim que os clientes MCP descobrem onde fazer login. Os clientes se registram sozinhos (registro dinâmico de clientes), o usuário aprova a conexão no app web da HILLS e cada chamada de ferramenta roda como essa conta.

| | |
| --- | --- |
| Metadados do recurso | `https://mcp.hillsmusic.com/.well-known/oauth-protected-resource` |
| Metadados do servidor de autorização | `https://mcp.hillsmusic.com/.well-known/oauth-authorization-server` |
| Escopo `read` | Acesso somente leitura ao seu catálogo, aos seus streams e aos seus relatórios de royalties |
| PKCE | Apenas S256 |
| Tokens de acesso | Válidos por 1 hora |
| Tokens de atualização | Válidos por 30 dias, renovados a cada uso (reutilizar um deles encerra a conexão) |

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

## Quem pode conectar

- Clientes (contas de parceiros) e os membros da equipe deles, o proprietário e os administradores: ativado por padrão.
- Artistas e gravadoras com conta própria na HILLS, e outros membros da equipe HILLS: quando a equipe da HILLS ativa.
- Artistas e gravadoras vinculados a um cliente: nunca; o MCP é do cliente.
- Algumas ferramentas são só para contas de cliente (saldo e saques: também artistas e gravadoras diretos, que a HILLS paga); uma conta que não pode usar uma ferramenta não a vê.
- Um membro da equipe de um cliente precisa da permissão de função que cada ferramenta indica; a equipe da HILLS vê o que as permissões da sua função liberam.

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

## Ferramentas

| Ferramenta | O que faz | Quem tem acesso |
| --- | --- | --- |
| [`list_members`](https://developer.hillsmusic.com/pt/mcp/list-members/) | Listar artistas e gravadoras | Apenas contas de cliente e a equipe delas |
| [`payouts`](https://developer.hillsmusic.com/pt/mcp/payouts/) | Saldo e saques | Apenas algumas contas |
| [`smartlinks`](https://developer.hillsmusic.com/pt/mcp/smartlinks/) | Smartlinks | Apenas contas de cliente e a equipe delas |
| [`list_deliveries`](https://developer.hillsmusic.com/pt/mcp/list-deliveries/) | Entregas DDEX | Apenas contas de cliente e a equipe delas |
| [`delivery_status`](https://developer.hillsmusic.com/pt/mcp/delivery-status/) | Status da entrega | Apenas contas de cliente e a equipe delas |
| [`search_catalog`](https://developer.hillsmusic.com/pt/mcp/search-catalog/) | Buscar no catálogo | Todas as contas com acesso ao MCP |
| [`release_status`](https://developer.hillsmusic.com/pt/mcp/release-status/) | Status do lançamento | Todas as contas com acesso ao MCP |
| [`streams_and_revenue`](https://developer.hillsmusic.com/pt/mcp/streams-and-revenue/) | Streams e receita | Todas as contas com acesso ao MCP |
| [`statements`](https://developer.hillsmusic.com/pt/mcp/statements/) | Relatórios de royalties | Todas as contas com acesso ao MCP |
| [`requests`](https://developer.hillsmusic.com/pt/mcp/requests/) | Solicitações | Todas as contas com acesso ao MCP |

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

## O que os assistentes recebem

O servidor passa estas instruções a todo assistente que se conecta (em inglês, como são enviadas):

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

Fonte: https://developer.hillsmusic.com/pt/mcp/overview/