Skonfiguruj Claude Desktop

1. Pobierz klucz API

W panelu przejdź do Org Settings → API Keys → Create. Nadaj scope mcp:* (obejmuje wszystkie pięć narzędzi poniżej). Sekret pokazuje się tylko raz; skopiuj cały string snt_live_<prefix>.<secret>.

Trzymaj go w keychainie systemu lub lokalnym .env — nigdy nie commituj. Klucz jest powiązany z twoją organizacją (i opcjonalnie z jednym projektem); calle poza scope zwracają 404. Unieważnij w panelu w dowolnej chwili; unieważnione klucze zwracają 401 przy kolejnym callu.

2. Instalacja (lub pomiń)

Serwer MCP publikowany jest na npm i Homebrew. Z npx nie musisz nic instalować — Claude Desktop pobiera najnowszą wersję przy każdym uruchomieniu. Z brew dostajesz przypięty lokalny binarny — przydatne za rygorystycznymi firewallami.

1// instalacja niepotrzebna — npx pobiera najnowsze @sonenta/mcp na żądanie2npx -y @sonenta/mcp --version

1// opcjonalnie: instalacja raz globalnie — pojawi się przy starcie V12brew install sonenta/tap/sonenta-mcp

3. Podłącz Claude Desktop

Otwórz plik konfiguracyjny Claude Desktop, dodaj wpis sonenta pod mcpServers, potem zamknij i ponownie uruchom aplikację.

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "sonenta": {6      "command": "npx",7      "args": ["-y", "@sonenta/mcp"],8      "env": {9        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

Trzy zmienne env w sumie: SONENTA_TOKEN (wymagana), SONENTA_PROJECT (opcjonalna — wstępnie zawęź projekt, by agent nie musiał najpierw wołać list_projects) oraz SONENTA_API_BASE (opcjonalna — domyślnie https://api.sonenta.com; nadpisz dla self-hosted lub stagingu).

SONENTA_PROJECTS wymaga @sonenta/mcp ≥ 0.11.0. W starszych wydaniach zobacz Rétrocompatibilité poniżej.

Wywołania narzędzi wieloprojektowe

Gdy SONENTA_PROJECTS wymienia więcej niż jeden UUID, agent nie może odgadnąć, o który projekt chodzi — każde wywołanie narzędzia musi zawierać project_uuid. Przy pojedynczym UUID (lub gdy ustawione jest tylko starsze SONENTA_PROJECT) jest ono opcjonalne, a wywołanie domyślnie odnosi się do tego projektu.

1// list_missing_keys — project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID2{3  "name": "list_missing_keys",4  "arguments": {5    "project_uuid": "<uuid1>",6    "namespace": "checkout",7    "language_code": "ja"8  }9}

Sformułuj swój prompt z myślą o projekcie („w projekcie Checkout wylistuj brakujące klucze dla ja”) — agent rozwiąże projekt do jego UUID i przekaże project_uuid w wywołaniu narzędzia. Przy promptcie niejednoznacznym pomiędzy wieloma projektami agent najpierw wywoła list_projects.

Cursor (i inni klienci MCP)

Ten sam JSON, inny plik. W Cursor wrzuć go do .cursor/mcp.json (scope projektu) albo ~/.cursor/mcp.json (scope użytkownika). Dla innych klientów postępuj zgodnie z dokumentacją konfiguracji MCP twojego klienta — wpis mcpServers.sonenta jest identyczny.

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "sonenta": {5      "command": "npx",6      "args": ["-y", "@sonenta/mcp"],7      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }8    }9  }10}

5 narzędzi V1

Po konfiguracji agent ma dostęp do tych narzędzi. Nie wołasz ich po nazwie — opisz swój zamiar w czacie, a agent wybierze. Nazwy poniżej to kanoniczne identyfikatory, przydatne przy czytaniu trace'ów agenta lub budowaniu własnych agentów na tym samym serwerze.

Limity i kwoty według planu

Płacisz, gdy agent modyfikuje Twój projekt, a nie gdy go obserwuje. Odczyty i listowania są darmowe; zapisy zużywają jedną jednostkę; operacje masowe i wspomagane przez AI skalują się wraz z wykonaną pracą.

Co liczy się jako wywołanie płatne

Pułapy według planu

Kwota miesięczna, twardy limit na minutę, równoczesne sesje MCP oraz to, czy zapisy są dozwolone. Te same wartości zasilają nagłówek X-MCP-Quota-Remaining w każdej odpowiedzi.

Gdy osiągniesz pułap

Powyżej tempa na minutę → 429 mcp_rate_limited z Retry-After (sekundy). Powyżej kwoty miesięcznej → 429 mcp_quota_exceeded z Retry-After ustawionym na moment rolloveru. Zapisy na planie Free → 403 mcp_writes_disabled. Kwoty resetują się 1. dnia każdego miesiąca kalendarzowego, UTC.

Weryfikacja

1. 1 Zrestartuj Claude Desktop w pełni (zamknij, uruchom ponownie — konfiguracja czytana jest przy starcie).
2. 2 Otwórz nowy czat. Ikona młotka powinna pokazać sonenta z 5 dostępnymi narzędziami.
3. 3 Wpisz „List my Sonenta projects." Agent powinien wywołać list_projects i zwrócić twoje workspace'y.

Utknąłeś? Sprawdź logi Claude Desktop w ~/Library/Logs/Claude/mcp*.log (macOS). 90% problemów to literówki w JSON-ie albo nieaktualny token.