Serwer MCP

Wprowadzenie

Model Context Protocol to otwarty standard, przez który asystenci sztucznej inteligencji rozmawiają z zewnętrznymi systemami. Nasz serwer wystawia całą produkcję piosenek jako narzędzia MCP: agent może utworzyć piosenkę, sprawdzić status, pobrać tekst i dźwięk oraz uruchomić ponowne generowanie.

Przewaga nad REST API polega na rozmowie. Agent wie, jakich szczegółów brakuje, żeby piosenka stała się osobista, i sam o nie pyta. Użytkownik opowiada o swoim ojcu, agent robi z tego brief i zamawia piosenkę.

Serwer działa pod https://mcp.mojamelodia.pl i mówi po HTTP z Server-Sent Events, czyli transportem, który wspiera każdy dzisiejszy klient. Używa tych samych kluczy co REST API, więc kto już integruje, nie potrzebuje nowych danych.

Dostęp

Klucze wydajemy ręcznie, tak jak przy REST API. Napisz na songs@maxkuch.com i podaj, co chcesz zbudować, jaki przewidujesz wolumen i w jakich językach. Odblokowanie trwa zwykle jeden dzień roboczy.

Dostaniesz klucz testowy z przedrostkiem sk_test_ i produkcyjny z przedrostkiem sk_live_. Przy kluczu testowym wszystkie narzędzia działają tak samo, ale nie startuje żadna prawdziwa produkcja i nic nie kosztuje.

Kto ma już klucz API, nie potrzebuje nic więcej: ten sam klucz otwiera serwer MCP.

Połączenie

Adres serwera to https://mcp.mojamelodia.pl/sse. Uwierzytelnianie odbywa się tokenem bearer w nagłówku Authorization, dokładnie jak w REST API.

Serwer realizuje wersję protokołu 2026-03-26 i zgłasza swoje możliwości podczas powitania: narzędzia, zasoby i prompty. Klienci znający tylko starsze wersje pozostają zgodni, po prostu bez promptów.

curl https://mcp.mojamelodia.pl/health

Konfiguracja w klientach

Prawie każdy klient MCP konfiguruje się małym plikiem JSON. Poniżej trzy najczęstsze warianty, w każdym klucz we właściwym miejscu.

Claude Code

claude mcp add --transport http songs \
  https://mcp.mojamelodia.pl/mcp \
  --header "Authorization: Bearer $SONG_API_KEY"

Claude Desktop

{
  "mcpServers": {
    "songs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mojamelodia.pl/mcp",
               "--header", "Authorization: Bearer ${SONG_API_KEY}"],
      "env": { "SONG_API_KEY": "sk_live_..." }
    }
  }
}

Cursor

{
  "mcpServers": {
    "songs": {
      "url": "https://mcp.mojamelodia.pl/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Po restarcie klienta narzędzia pojawiają się na liście. Jeśli się nie pojawiają, przyczyną jest prawie zawsze brakujący klucz albo JSON z błędem składni.

Narzędzia

Serwer udostępnia siedem narzędzi. Jest ich świadomie mało i mają jasne nazwy, żeby agent wybierał dobrze.

Tylko create_song i regenerate_song coś zmieniają. Klienci, którzy pytają przed operacjami zapisu, zapytają więc dokładnie przy tych dwóch.

create_song w szczegółach

To narzędzie centralne. Jego schemat jest celowo rozgadany, żeby agent wiedział, jakie informacje musi najpierw zdobyć.

{
  "name": "create_song",
  "description": "Write and produce a personalised song. Returns immediately with a song id; the recording is ready a few minutes later.",
  "inputSchema": {
    "type": "object",
    "required": ["occasion", "recipient_name", "details"],
    "properties": {
      "occasion":       { "type": "string", "enum": ["birthday", "wedding", "anniversary", "farewell", "funeral", "christening", "graduation", "christmas", "declaration", "other"] },
      "recipient_name": { "type": "string", "maxLength": 80 },
      "relationship":   { "type": "string", "maxLength": 80 },
      "language":       { "type": "string", "default": "pl" },
      "mood":           { "type": "string", "enum": ["happy", "warm", "funny", "romantic", "gentle", "epic", "surprise_me"] },
      "style":          { "type": "string" },
      "voice":          { "type": "string", "enum": ["female", "male", "duet", "choir", "childrens", "surprise_me"] },
      "details":        { "type": "string", "minLength": 40, "maxLength": 4000 },
      "wait":           { "type": "boolean", "default": false, "description": "Block until the preview is ready, at most 10 minutes." }
    }
  }
}

Decydujące jest pole details. Opis w schemacie mówi agentowi wprost, że potrzeba konkretnych szczegółów, a nie przymiotników. Dobry agent nie pyta "jaki jest twój ojciec", tylko "co zawsze mówi, kiedy coś go zdenerwuje".

{
  "content": [
    { "type": "text", "text": "Song sng_3n8Kd2ZpQv for Anna is written. Lyrics below, the 45 second preview is ready." },
    { "type": "resource", "resource": { "uri": "song://sng_3n8Kd2ZpQv/lyrics", "mimeType": "text/plain" } },
    { "type": "resource", "resource": { "uri": "song://sng_3n8Kd2ZpQv/preview", "mimeType": "audio/mpeg" } }
  ],
  "structuredContent": {
    "id": "sng_3n8Kd2ZpQv",
    "status": "preview_ready",
    "preview_url": "https://cdn.mojamelodia.pl/preview/sng_3n8Kd2ZpQv.mp3",
    "paid": false
  },
  "isError": false
}

Odpowiedź zawiera tekst dla agenta i dane strukturalne dla kodu. Wywołanie wraca od razu, produkcja trwa w tle.

Kształt odpowiedzi

Każde narzędzie zwraca dwie rzeczy: czytelny blok tekstu, który agent może oddać wprost, i structuredContent z tymi samymi danymi w formie nadającej się dla maszyny. Agent może więc odpowiedzieć użytkownikowi, nie gubiąc identyfikatorów.

Identyfikatory piosenek są te same co w REST API. Piosenkę utworzoną przez MCP można później pobrać przez REST i odwrotnie, co przydaje się, gdy agent zbiera brief, a dostawą zajmuje się twój backend.

Zasoby

Poza narzędziami serwer oferuje zasoby, czyli treści tylko do odczytu, które klient może wczytać do kontekstu bez wywoływania narzędzia.

song://sng_3n8Kd2ZpQv           the song object as JSON
song://sng_3n8Kd2ZpQv/lyrics    the full lyrics as plain text
song://sng_3n8Kd2ZpQv/preview   the first 45 seconds as audio/mpeg
song://sng_3n8Kd2ZpQv/audio     the full recording, only after payment

song://options zawiera wszystkie dopuszczalne wartości, song://guide/details krótki przewodnik o tym, co czyni piosenkę osobistą, song://songs/{id} pojedynczą piosenkę z tekstem i statusem. Przewodnik jest przede wszystkim dla agentów: wyraźnie zwiększa szansę, że zapytają o właściwe rzeczy.

Prompty

Serwer niesie ze sobą gotowe prompty, które klient może udostępnić jako polecenia. Oszczędzają użytkownikowi tłumaczenia, co ma opowiedzieć.

{
  "name": "birthday_song",
  "description": "Collects the five things a birthday song needs and then creates it.",
  "arguments": [
    { "name": "recipient_name", "required": true },
    { "name": "age",            "required": false },
    { "name": "details",        "required": false }
  ]
}

gather_song_details prowadzi agenta przez krótką rozmowę kończącą się użytecznym briefem. write_song_brief zamienia istniejący tekst, na przykład wiadomość od klienta, w uporządkowany brief. suggest_occasion pomaga, gdy okazja nie mieści się w zwykłych kategoriach.

Typowa rozmowa

Tak to wygląda w praktyce, z użytkownikiem, który jeszcze nie bardzo wie, czego chce.

User:  My sister Anna turns 34 on Friday. She climbs, she is always late,
       and she calls everyone chef. Make her a song.

Claude: [calls create_song with occasion=birthday, recipient_name=Anna,
        relationship=sister, mood=funny, details="climbs every weekend,
        always ten minutes late, calls everyone chef"]

        Done. Here are the lyrics, and the first 45 seconds are playable
        right away. Should the chorus lean more on the climbing or more
        on the chef thing?

User:  More chef.

Claude: [calls regenerate_song with keep_lyrics=false,
        note="put the chef running gag in the chorus"]

        New version is running, about five minutes.

Sedno jest w środku. Agent nie zadowala się pierwszym ogólnym opisem, tylko dopytuje dwa razy, i to właśnie te dwa pytania zamieniają piosenkę o kimkolwiek w piosenkę o tej osobie.

Płatność

Agent nie może uruchomić płatności. Może tylko utworzyć link do płatności i przekazać go dalej, płaci się w przeglądarce. Tak to zbudowaliśmy celowo: model nie powinien podejmować decyzji o zakupie, której człowiek nie widział.

get_checkout_link zwraca adres ważny 24 godziny. Po zapłacie piosenka przechodzi w stan complete, a przy następnym get_song całe nagranie jest gotowe. Agent nie musi niczego subskrybować, wystarczy późniejsze wywołanie.

Kto obsługuje płatność we własnym systemie i tylko rozlicza się z nami, może poprosić o odblokowanie drogi bezpośredniej w REST API. Wtedy link do płatności odpada, a piosenka jest odblokowywana od razu.

Uprawnienia i zakresy

Każdy klucz niesie uprawnienia. Domyślnie jest to odczyt i zapis bez dostępu do rozliczeń, co pasuje większości agentów.

Narzędzia, do których brakuje uprawnienia, w ogóle nie pojawiają się na liście narzędzi. To przyjemniejsze niż komunikat o błędzie w środku rozmowy, bo model nie proponuje wtedy niczego, czego i tak nie umie.

Błędy

Błędy przychodzą jako wynik narzędzia z isError: true i zrozumiałym tekstem, a nie jako błąd protokołu. Dzięki temu agent może zareagować i wytłumaczyć użytkownikowi, czego brakuje, zamiast się przerwać.

{
  "content": [
    { "type": "text", "text": "The song is not paid for yet, so the full recording cannot be handed over. The checkout link is https://pay.mojamelodia.pl/c/cs_live_8Hd2Kq..." }
  ],
  "isError": true
}

Kody błędów odpowiadają tym z REST API: validation_error, rate_limit, not_found, permission_error, api_error. Tekst jest sformułowany tak, żeby agent mógł oddać go słowo w słowo.

Limity

Obowiązują te same limity co w REST API: 60 wywołań narzędzi na minutę i klucz oraz dziesięć równoczesnych produkcji. Kolejne wywołania czekają w kolejce, zamiast zawodzić.

Sesja MCP stoi otwarta tak długo, jak trzyma ją klient. Po 30 minutach bezczynności zamykamy połączenie; każdy dzisiejszy klient łączy się z powrotem sam.

Gdy wolumen rośnie, napisz do nas, a podniesiemy limity.

Dane

To, co przekazuje nam agent, wykorzystujemy do wyprodukowania tej jednej piosenki i do niczego więcej. Żadnego trenowania własnych modeli na treściach twoich użytkowników.

Dane wejściowe i gotowe piosenki zostają 90 dni, potem są usuwane. Do wcześniejszego usunięcia służy DELETE /v1/songs/{id} w REST API.

Przypominaj użytkownikom, że opowiadają prywatne rzeczy o prawdziwych ludziach. Agent powinien pytać o konkretne szczegóły, nie kierując rozmowy ku wrażliwym informacjom o zdrowiu czy finansach.

Eksploatacja

Serwer MCP działa na tej samej infrastrukturze co REST API. Nie ma osobnego komponentu do instalowania ani aktualizowania: nowe narzędzia dodajemy przyrostowo, istniejące pozostają stabilne.

Klient powinien czytać listę narzędzi przy starcie, a nie wpisywać ją na sztywno. To zwykły sposób i przynosi ci nowości bez zmian w kodzie.

O planowanych pracach serwisowych uprzedzamy aktywne konta mailem co najmniej 48 godzin wcześniej. Jak dotąd nie było planowanych przerw.

Wsparcie

Pytania o konfigurację, zakresy, wyższe limity albo przypadki szczególne: songs@maxkuch.com. Przy problemach technicznych podaj nazwę narzędzia i przybliżoną godzinę wywołania.

Kto woli integrować bezpośrednio, niż iść przez agenta, znajdzie REST API na /api/. Obie drogi używają tych samych kluczy i tych samych identyfikatorów.