Serwer MCP: Twój agent AI właśnie nauczył się rezerwować

Twój agent AI potrafi napisać esej, przeanalizować kontrakt i przetłumaczyć dokumentację na 30 języków. Ale czy potrafi zarezerwować wizytę u fryzjera?

Do niedawna odpowiedź brzmiała: nie. Nie dlatego, że modele językowe są zbyt głupie. Dlatego, że nie miały standardowego sposobu na komunikację z zewnętrznymi systemami. Każda integracja wymagała dedykowanego kodu, mapowania endpointów i ręcznego zarządzania autoryzacją.

Model Context Protocol (MCP) zmienia tę sytuację. To otwarty standard komunikacji między agentami AI a narzędziami zewnętrznymi — coś w rodzaju USB-C dla sztucznej inteligencji. A Timerise API ma wbudowany serwer MCP, który pozwala agentom wykonywać prawdziwe operacje rezerwacyjne od pierwszej minuty.

Czym jest Model Context Protocol?

MCP (Model Context Protocol) to protokół opracowany przez Anthropic, który definiuje, jak agenci AI mogą odkrywać i używać narzędzi udostępnianych przez zewnętrzne serwery. Zamiast hardkodować wywołania API w promptach, agent łączy się z serwerem MCP i automatycznie dowiaduje się, jakie operacje ma do dyspozycji.

Analogia? Pomyśl o tym jak o menu w restauracji. Zamiast zgadywać, co kuchnia potrafi przygotować, agent dostaje listę dań (narzędzi) z opisami i składnikami (parametrami). Wybiera to, czego potrzebuje, i składa zamówienie.

W praktyce wygląda to tak:

Agent wysyła żądanie initialize do serwera MCP.
Serwer zwraca listę dostępnych narzędzi z ich opisami i schematami parametrów.
Agent wywołuje konkretne narzędzie z odpowiednimi argumentami.
Serwer wykonuje operację i zwraca wynik.

Żadnego kodu klejącego. Żadnej ręcznej dokumentacji. Agent sam rozumie, co może zrobić.

Jak działa serwer MCP w Timerise?

Serwer MCP jest zamontowany bezpośrednio na Timerise API pod ścieżką /mcp. Nie trzeba uruchamiać osobnego procesu ani konfigurować dodatkowej infrastruktury. Wystarczy klucz API i adres serwera:

Sandbox: https://sandbox-api.timerise.io/mcp
Produkcja: https://api.timerise.io/mcp

Przepływ autoryzacji jest prosty:

Agent wysyła POST /mcp z nagłówkiem Authorization: Bearer <klucz-api>.
Serwer tworzy prywatną sesję MCP i zwraca identyfikator sesji w nagłówku mcp-session-id.
Każde kolejne wywołanie w ramach tej sesji używa tego samego klucza API.
Agent wysyła DELETE /mcp, aby zakończyć sesję.

Wszystkie mechanizmy kontroli dostępu Timerise działają bez zmian — klucz API określa, do których projektów i usług agent ma dostęp.

16 narzędzi do pełnej obsługi rezerwacji

Serwer MCP udostępnia 16 narzędzi podzielonych na cztery grupy. Pokrywają cały cykl życia rezerwacji oraz dają programistom dostęp do schematu API i zarządzania kluczami.

Odkrywanie usług

list_projects — lista projektów dostępnych dla danego klucza API
get_project — szczegóły wybranego projektu
list_services — lista usług w ramach projektu
get_service — szczegóły usługi, w tym wymagane pola formularza (formFields)
list_locations — lista lokalizacji fizycznych lub wirtualnych

Sprawdzanie dostępności

list_available_slots — zapytanie o dostępne sloty w podanym zakresie dat

Zarządzanie rezerwacjami

create_booking — tworzenie rezerwacji (slot-based lub range-based)
confirm_booking — potwierdzenie rezerwacji (zmiana statusu z NEW na CONFIRMED)
cancel_booking — anulowanie rezerwacji
reschedule_booking — przeniesienie rezerwacji na inny termin
list_bookings — lista rezerwacji z filtrami (status, usługa, zakres dat)
get_booking_details — pełne szczegóły konkretnej rezerwacji

Narzędzia dla programistów

get_api_schema — pobranie pełnego schematu GraphQL API w formacie SDL, przydatne do eksploracji struktury danych i budowania integracji
list_api_users — lista użytkowników API i ich kluczy w ramach projektu
create_api_key — utworzenie nowego klucza API dla projektu (klucz jest wyświetlany tylko raz)
delete_api_key — usunięcie klucza API po jego identyfikatorze

Dzięki tym narzędziom agent AI może nie tylko obsługiwać rezerwacje, ale też pomagać programiście w onboardingu — pobrać schemat API, utworzyć klucz sandboxowy i od razu rozpocząć integrację. Wszystko bez wychodzenia z IDE.

Agent nie musi znać struktury GraphQL ani formatu żądań. Serwer MCP abstrahuje te szczegóły i udostępnia czyste, opisane narzędzia.

Od pytania do rezerwacji — krok po kroku

Zobaczmy, jak agent AI przeprowadza pełny proces rezerwacji za pomocą narzędzi MCP. Użytkownik pisze: "Umów mnie na strzyżenie w poniedziałek rano, jeśli coś jest dostępne."

Krok 1: Znajdź projekt

Agent wywołuje list_projects i otrzymuje listę projektów, np. "Haircut Studio" z identyfikatorem prj_abc123.

Krok 2: Znajdź usługę

Agent wywołuje list_services z projectId i znajduje "Men's Haircut" z identyfikatorem svc_xyz789.

Krok 3: Sprawdź wymagane pola

Agent wywołuje get_service, aby dowiedzieć się, jakie dane są potrzebne do rezerwacji. Serwer zwraca listę pól: imię i nazwisko (wymagane), email (wymagane), telefon (opcjonalnie).

Krok 4: Sprawdź dostępność

Agent wywołuje list_available_slots z zakresem dat na poniedziałek rano i otrzymuje listę wolnych slotów z identyfikatorami.

Krok 5: Utwórz rezerwację

Agent wywołuje create_booking z wybranym slotem, danymi użytkownika i strefą czasową. Rezerwacja zostaje utworzona ze statusem NEW.

Krok 6: Potwierdź rezerwację

Agent wywołuje confirm_booking, aby zmienić status na CONFIRMED.

Sześć wywołań narzędzi. Zero linii kodu integracyjnego. Agent sam ustala kolejność operacji na podstawie opisów narzędzi udostępnionych przez serwer MCP.

Konfiguracja w 2 minuty

Serwer MCP Timerise działa z każdym klientem wspierającym protokół MCP. Oto jak podłączyć go do wybranych narzędzi.

Claude Desktop

Edytuj plik konfiguracyjny (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "timerise": {
      "url": "https://sandbox-api.timerise.io/mcp",
      "headers": {
        "Authorization": "Bearer SANDBOX-twoj-klucz-api"
      }
    }
  }
}

Produkcja: zamień URL na https://api.timerise.io/mcp i użyj klucza z prefiksem PROD-.

Po restarcie Claude Desktop ikona młotka w pasku narzędzi potwierdzi, że narzędzia MCP są aktywne. Zapytaj Claude: "Jakie projekty Timerise widzisz?" — automatycznie wywoła list_projects.

Claude Code (CLI)

claude mcp add timerise \
  --transport http \
  --url https://sandbox-api.timerise.io/mcp \
  --header "Authorization: Bearer SANDBOX-twoj-klucz-api"

Cursor

Edytuj ~/.cursor/mcp.json lub skorzystaj z Cursor Settings → MCP → Add Server:

{
  "mcpServers": {
    "timerise": {
      "url": "https://sandbox-api.timerise.io/mcp",
      "headers": {
        "Authorization": "Bearer SANDBOX-twoj-klucz-api"
      }
    }
  }
}

OpenAI Agents SDK (Python)

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    url="https://sandbox-api.timerise.io/mcp",
    headers={"Authorization": "Bearer SANDBOX-twoj-klucz-api"},
) as timerise:
    agent = Agent(
        name="Asystent rezerwacji",
        instructions="Pomagasz użytkownikom rezerwować wizyty.",
        mcp_servers=[timerise],
    )
    result = await Runner.run(
        agent, "Zarezerwuj mi slot na poniedziałek rano."
    )

W każdym przypadku konfiguracja sprowadza się do podania adresu URL serwera MCP i klucza API. Resztę obsługuje protokół.

Narzędzia do testowania i debugowania

Zanim wypuścisz agenta na produkcję, warto przetestować połączenie z serwerem MCP. Timerise daje Ci do tego kilka ścieżek.

MCP Inspector

MCP Inspector to przeglądarkowe narzędzie do interaktywnego testowania serwerów MCP. Uruchom je jednym poleceniem:

npx @modelcontextprotocol/inspector

W interfejsie pod http://localhost:5173 wybierz transport Streamable HTTP, wpisz adres https://sandbox-api.timerise.io/mcp i dodaj nagłówek autoryzacyjny. Możesz przeglądać wszystkie 16 narzędzi, wywoływać je z dowolnymi argumentami i obserwować surowe komunikaty JSON-RPC w zakładce Network.

Testowanie z curl

Jeśli wolisz terminal, zainicjuj sesję ręcznie:

curl -si -X POST https://sandbox-api.timerise.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SANDBOX-twoj-klucz-api" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "0.1" }
    },
    "id": 1
  }'

Serwer zwróci nagłówek mcp-session-id. Użyj go w kolejnych żądaniach, np. do pobrania listy narzędzi (tools/list) lub wywołania konkretnego narzędzia (tools/call).

Typowe problemy

404 Session not found — sesja wygasła lub API zostało zrestartowane. Wyślij nowe żądanie initialize bez nagłówka mcp-session-id.
Not authorized — klucz API nie ma dostępu do danego projektu. Sprawdź uprawnienia w dashboardzie Timerise.
Slot not available — slot został zarezerwowany przez kogoś innego. Wywołaj list_available_slots ponownie.

Sesje MCP żyją po stronie serwera. Jeśli połączenie zostanie przerwane, agent powinien ponownie zainicjować sesję.

OAuth 2.1 dla Claude.ai i innych platform

Oprócz autoryzacji Bearer token, Timerise wspiera OAuth 2.1 z PKCE — standard wymagany przez Claude.ai, ChatGPT, Google Gemini i inne platformy AI łączące się ze zdalnymi serwerami MCP.

Proces wygląda następująco:

Administrator tworzy dane uwierzytelniające OAuth przez API GraphQL (mcpOAuthClientCreate).
clientId i clientSecret konfiguruje się w ustawieniach platformy AI.
Platforma automatycznie przeprowadza discovery endpointów OAuth, autoryzację i wymianę tokenów.
Wynikowy token dostępu to standardowy klucz API Timerise.

Dzięki temu agent AI na Claude.ai może korzystać z tych samych 16 narzędzi MCP, co agent podłączony przez Bearer token — bez dodatkowej konfiguracji po stronie programisty.

Kiedy MCP ma sens?

Serwer MCP w Timerise sprawdza się w scenariuszach, w których agent AI musi samodzielnie wykonywać operacje rezerwacyjne bez interwencji programisty:

Chatboty obsługi klienta — bot na stronie lub w WhatsApp, który sam rezerwuje, przełożony lub anuluje wizytę.
Asystenci głosowi — voicebot w klinice, który proponuje pacjentowi nowy termin podczas rozmowy telefonicznej.
Agenci w IDE — programista w Cursorze prosi agenta o sprawdzenie dostępnych slotów testowych w środowisku sandbox.
Automatyzacja wewnętrzna — skrypt Pythona z OpenAI Agents SDK, który codziennie sprawdza obłożenie i generuje raport.

W każdym z tych przypadków agent nie potrzebuje dedykowanego kodu integracyjnego. Wystarczy połączenie z serwerem MCP i klucz API z odpowiednimi uprawnieniami.

Podsumowanie

Model Context Protocol to brakujące ogniwo między inteligentnymi modelami językowymi a realnymi systemami biznesowymi. Timerise wbudowuje serwer MCP bezpośrednio w API, eliminując konieczność pisania kodu integracyjnego.

16 narzędzi pokrywa pełen cykl rezerwacji — od odkrycia usług, przez sprawdzenie dostępności, po tworzenie i zarządzanie rezerwacjami. Konfiguracja zajmuje minuty, nie dni. A dzięki wsparciu OAuth 2.1, serwer MCP działa zarówno z lokalnymi narzędziami deweloperskimi, jak i z platformami AI w chmurze.

Jeśli budujesz agenta AI, który ma obsługiwać rezerwacje, nie pisz kolejnego wrappera na REST API. Podłącz go do serwera MCP Timerise i pozwól mu działać.

Dokumentacja MCP w Timerise →

Przetestuj serwer MCP z MCP Inspector →

Zarejestruj się i zacznij budować za darmo →

<br>

Mateusz Sowa