# Połącz asystentów AI (MCP) Your AI Connector dostarcza oficjalny **serwer MCP** — punkt końcowy Model Context Protocol, który pozwala asystentom AI, takim jak **Claude Code**, **Claude Desktop**, **Cursor** oraz Twoim własnym aplikacjom, bezpośrednio obsługiwać Twoje konto Your AI Connector. Pytaj prostym językiem ("wymień moich agentów AI", "dodaj ten lead", "ile kosztowało mnie AI w tym tygodniu?"), a asystent wywoła dla Ciebie API Your AI Connector. To to samo API w wersji v1, do którego uzyskujesz dostęp za pomocą [klucza API](api-access.md), uwierzytelniane własnym kluczem API. Serwer MCP tworzy jedno narzędzie dla każdej operacji w naszej opublikowanej specyfikacji API, więc obejmuje ono większość, choć nie całe API v1: kontakty, wiadomości, kampanie, agenty AI, funkcje niestandardowe, bazę wiedzy, spotkania, analitykę, tagi, listy, transmisje, transakcje, połączenia kanałów i subkonta. Automatyzacje można wyświetlać i odczytywać, ale nie można ich jeszcze tworzyć ani edytować za pośrednictwem MCP; należy to robić w aplikacji. W ramach tego, co jest udostępniane, nie ma uprawnień dla poszczególnych narzędzi ani domyślnego trybu tylko do odczytu, więc klucz API stanowi pełną kontrolę dostępu. - **Punkt końcowy:** `https://mcp.youraiconnector.com/mcp` - **Autoryzacja:** Twój klucz API Your AI Connector (wysyłany jako nagłówek `X-API-Key`) - **Wymagania:** plan z dostępem do API. [Utwórz klucz API →](api-access.md#generating-your-api-key) > Twój klucz API działa w ramach **Twojego własnego konta**, z takimi samymi uprawnieniami jak > reszta API — i może odczytywać konta klientów, którymi zarządzasz, jeśli korzystasz z planu agencyjnego (patrz poniżej). Traktuj go jak hasło. Możesz go w każdej chwili unieważnić w sekcji Ustawienia → Integracje → Klucz API, co natychmiast odetnie dostęp asystenta. ## Claude Code ```bash claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` Następnie uruchom `/mcp` wewnątrz Claude Code, aby potwierdzić, że wyświetla się **ai-connector ✓ connected**. Domyślnie serwer jest dodawany w zakresie **lokalnym** (tylko Ty, ten projekt). Użyj `--scope user`, aby udostępnić go we wszystkich swoich projektach, lub `--scope project` to commit it to a repo's `.mcp.json` dla swojego zespołu: ```json { "mcpServers": { "ai-connector": { "type": "http", "url": "https://mcp.youraiconnector.com/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ## Claude Desktop Dodaj serwer jako niestandardowy konektor. Jest on konfigurowany na Twoim koncie Claude, dzięki czemu działa zarówno w aplikacji Claude Desktop, jak i na stronie claude.ai (darmowe konta Claude mogą dodać jeden niestandardowy konektor). 1. Otwórz **Customize → Connectors**, kliknij **+ Add**, a następnie **Add custom connector**. 2. Nadaj mu nazwę i wprowadź `https://mcp.youraiconnector.com/mcp` jako adres URL. 3. W sekcji **Authentication** wybierz **No sign in**. Serwer MCP nie posiada strony logowania: wybranie opcji logowania zakończy się błędem "Couldn't register with … sign-in service". 4. W sekcji **Request headers** dodaj nagłówek o nazwie `X-API-Key`, wpisując swój klucz API jako wartość. 5. Kliknij **Add**. Narzędzia Your AI Connector pojawią się w menu narzędzi w nowym czacie. **Brak pola Request headers?** Twoja wersja Claude Desktop jest przestarzała: zaktualizuj ją lub użyj pliku konfiguracyjnego. Plik konfiguracyjny (`claude_desktop_config.json`, Settings → Developer → Edit Config) uruchamia programy tylko na Twoim komputerze i ignoruje wpis `url`, więc wymaga małego mostka `mcp-remote`, który wymaga [Node.js](https://nodejs.org) w wersji 18 lub nowszej: ```json { "mcpServers": { "ai-connector": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.youraiconnector.com/mcp", "--header", "X-API-Key:${AI_CONNECTOR_KEY}" ], "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" } } } } ``` Zachowaj `X-API-Key:${AI_CONNECTOR_KEY}` dokładnie w takiej formie, bez spacji po dwukropku (w systemie Windows spacja rozdziela nagłówek), i umieść swój klucz tylko w `env`. Następnie całkowicie zamknij Claude Desktop (w systemie Windows kliknij prawym przyciskiem myszy ikonę w zasobniku → Quit) i otwórz go ponownie. ## ChatGPT ChatGPT nie może obecnie połączyć się z serwerem MCP. Jego formularz niestandardowego konektora oferuje tylko **OAuth** lub **Brak uwierzytelniania**, a serwer MCP Your AI Connector loguje się za pomocą Twojego klucza API, przesyłanego w nagłówku żądania. Wybór OAuth kończy się błędem "could not discover OAuth settings", a brak uwierzytelniania jest odrzucany, ponieważ każde żądanie wymaga klucza. Użyj asystenta, który pozwala na ustawienie nagłówka żądania: [Claude Code](#claude-code), [Claude Desktop](#claude-desktop), [Cursor lub inny klient MCP](#cursor--other-mcp-clients) lub [Claude API](#the-claude-api-build-it-into-your-own-app). ChatGPT nadal może czytać dokumentację pomocy bez połączenia: zobacz [Dokumentacja pomocy jest wbudowana](#the-help-docs-are-built-in) dla publicznych plików `llms.txt`. ## Cursor i inni klienci MCP Większość edytorów obsługujących MCP korzysta z tego samego formatu `.mcp.json`, co pokazano powyżej (serwer HTTP z nagłówkiem `url` i `X-API-Key`). Dodaj serwer `ai-connector` wskazujący na `https://mcp.youraiconnector.com/mcp` i wklej swój klucz API w nagłówku. ## API Claude (wbudowanie we własną aplikację) Możesz połączyć się z serwerem MCP programowo za pomocą konektora MCP API Claude, dzięki czemu tworzony przez Ciebie agent może korzystać z narzędzi Your AI Connector bez oddzielnego klienta: ```json { "model": "claude-opus-4-8", "messages": [{ "role": "user", "content": "List my AI agents" }], "mcp_servers": [ { "type": "url", "name": "ai-connector", "url": "https://mcp.youraiconnector.com/mcp", "authorization_token": "YOUR_API_KEY" } ] } ``` ## Co możesz zrobić W ramach części API v1 udostępnianej przez serwer MCP asystent automatycznie wybiera odpowiednie narzędzie: - **Agenci AI:** lista, tworzenie, aktualizacja, wstrzymywanie/wznawianie, sprawdzanie konfiguracji. - **Kontakty:** wyszukiwanie, tworzenie, tagowanie, dodawanie do list, importowanie. - **Baza wiedzy / FAQ:** dodawanie, edycja, import masowy, zatwierdzanie sugestii AI. - **Wiadomości:** czytanie konwersacji, wysyłanie wiadomości do kontaktu. - **Spotkania:** lista, rezerwacja, anulowanie. - **Zadania:** tworzenie, kończenie, lista. - **Analityka:** statystyki wiadomości, zużycie kredytów, koszt AI. - **Kanały:** sprawdzanie statusu połączenia, rozpoczynanie procesu łączenia. ## Pytania o konta Twoich klientów (agencje) Jedno połączenie obejmuje wszystkie konta, którymi zarządzasz. Nie musisz dodawać drugiego połączenia dla każdego klienta: w planie agencyjnym asystent może odczytać dowolne konto klienta podpięte pod Ciebie, dzięki czemu możesz pytać o nie wszystkie w ramach jednej konwersacji. Wystarczy wymienić nazwę klienta: - "Ile kontaktów ma Bella's Bistro?" - "Ile kosztowało AI każdego z moich klientów w tym tygodniu?" - "Jaki jest stan kanałów Northside Dental i ile czatów wpłynęło w tym tygodniu?" Obejmuje to odczyt kontaktów, wiadomości, czatów, kampanii, spotkań, zadań, tagów, wydarzeń, FAQ, źródeł bazy wiedzy, numerów telefonów, kanałów, webhooków i analityki. Zanim cokolwiek zostanie uruchomione, sprawdzamy, czy konto rzeczywiście należy do Ciebie — zapytanie o konto, które do Ciebie nie należy, zwróci wynik „nie znaleziono”. Jeśli pominiesz nazwę klienta, asystent odczyta Twoje własne konto, dokładnie tak jak wcześniej. **Zmiana konta klienta** działa w ten sam sposób. Każda akcja w API, która akceptuje konto klienta, jest dostępna dla wybranego klienta: konfigurowanie agentów AI, bazy wiedzy, funkcji niestandardowych, szablonów WhatsApp, punktów wejścia, połączeń kanałów, kontaktów, tagów, transmisji, spotkań, transakcji i zadań oraz wysyłanie wiadomości. Wyjątkiem są akcje na poziomie agencji, które zawsze są wykonywane na Twoim własnym koncie agencyjnym: zarządzanie samymi kontami klientów (limity, funkcje, cennik, wstrzymywanie), migawki, Twój zespół oraz klucze API. Dodawanie kontaktów do listy klienta lub usuwanie ich z niej nie jest jeszcze dostępne dla wybranego klienta; należy to zrobić za pomocą klucza tego klienta lub bezpośrednio na jego koncie. [Przewodnik po API agencji](../agency/api-for-agencies.md#where-sub_account_id-is-supported) zawiera listę obsługiwanych funkcji. ::: neutral-mcp Narzędzia agencyjne znajdują się wyłącznie pod standardowym, nieoznakowanym adresem `https://mcp.youraiconnector.com/mcp`. Adres MCP typu white-label we własnej domenie (`mcp.youragency.com`) jest przeznaczony dla Twoich klientów i nie zawiera tych narzędzi, dlatego podczas zarządzania kontami klientów należy łączyć się za pomocą standardowego, nieoznakowanego adresu. ::: Jest to również rozwiązanie dla klienta, który prowadzi **kilka firm w ramach jednego loginu**. Przypisz każdej firmie osobne konto, a następnie zaproś adres e-mail klienta jako członka zespołu do wszystkich z nich: loguje się on raz i przełącza między swoimi markami za pomocą selektora kont na pasku bocznym. ### Testowanie agenta klienta Poproś asystenta o przetestowanie agenta klienta („wyślij 'czy dostarczacie w niedziele?' do agenta Bakery klienta X i pokaż mi, co zrobił”). Wysyła on wiadomość typu Try Out z Twoim kluczem agencyjnym oraz `sub_account_id` klienta, czeka, a następnie odczytuje odpowiedź oraz wszelkie działania podjęte przez agenta. Nie jest wymagana kopia agenta. Jeśli asystent twierdzi, że nie masz konta agencyjnego, oznacza to, że jest połączony z kluczem klienta: połącz go ponownie za pomocą klucza swojego konta agencyjnego. Zobacz [Try Out](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant). ## Klienci z limitem narzędzi ::: neutral-mcp Niektórzy klienci AI akceptują tylko serwer z ograniczoną liczbą narzędzi. Na przykład Composio odrzuca serwer, który zawiera listę ponad 500 narzędzi i nie importuje żadnego z nich. Pełne połączenie z agencją zawiera ich więcej, dlatego dodaj `?tags=` do adresu, uwzględniając tylko potrzebne grupy narzędzi. W przypadku agencji, która chce wyświetlić listę kont swoich klientów, odczytywać ich kontakty, czaty i wiadomości oraz wysyłać wiadomości: ``` https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages ``` To ładuje około 80 narzędzi. Wskaż klienta w swoim żądaniu, a asystent będzie działał na koncie tego klienta, zgodnie z powyższym opisem. - Rozdzielaj grupy przecinkami; wielkość liter nie ma znaczenia. - Aby dodać pojedyncze narzędzia, wymień ich dokładne nazwy za pomocą `tools=`, na przykład `?tags=Contacts&tools=list_or_get_subaccounts`. Otrzymasz wszystkie narzędzia z obu list. - Narzędzia z dokumentacji pomocy są zawsze uwzględniane. - Klucz API nadal należy umieszczać w nagłówku `X-API-Key` (lub `Authorization: Bearer YOUR_API_KEY`), nigdy w adresie. ::: ## Dokumentacja pomocy jest wbudowana Serwer MCP udostępnia asystentowi Twoje **konto** oraz tę **dokumentację**. Trzy narzędzia odczytują dokumentację pomocy na żywo, dzięki czemu asystent może sprawdzić, jak działa dana funkcja lub co ostatnio się zmieniło, zamiast zgadywać: - `docs_search`: znajduje sekcje odpowiadające na pytanie i zwraca je wraz z linkiem do strony. - `docs_read`: odczytuje całą stronę lub jej wybraną sekcję. - `docs_list`: wyświetla listę wszystkich stron według obszarów. Nie ma nic do skonfigurowania, a narzędzia dokumentacji nigdy nie ingerują w dane Twojego konta. Zapytaj „jak działają punkty wejścia?” lub „co nowego w automatyzacjach?”, a asystent najpierw przeszuka dokumentację. Ponieważ narzędzia odczytują samą witrynę pomocy, asystent dowiaduje się o nowej funkcji, gdy tylko zostanie opublikowany jej przewodnik. Asystent, który nie jest połączony przez MCP, nadal może czytać dokumentację: wskaż mu `https://docs.youraiconnector.com/llms.txt` (indeks każdej strony pomocy z linkiem do wersji Markdown każdej z nich) lub `https://docs.youraiconnector.com/llms-full.txt` (cała dokumentacja w jednym pliku Markdown). Oba są publiczne, nie wymagają klucza i są przebudowywane przy każdej zmianie w dokumentacji. ## Znajdowanie lub generowanie klucza API Klucz API używany przez to połączenie znajduje się w sekcji **Ustawienia → Integracje → Klucz API** — jest to osobna sekcja, niezależna od Webhooków. Zobacz [Dostęp do API](api-access.md#generating-your-api-key), aby poznać dokładne kroki. ## Rozwiązywanie problemów - **"Connection refused" lub "not found"** — w adresie brakuje `/mcp` na końcu. Użyj `https://mcp.youraiconnector.com/mcp`, a nie `https://mcp.youraiconnector.com`. - **`Needs authentication` / 401** — Twój klucz API jest nieprawidłowy lub go brakuje. Dodaj serwer ponownie z poprawnym `X-API-Key`. - **"Could not discover OAuth settings" (ChatGPT)** — ChatGPT obsługuje dla niestandardowych konektorów tylko OAuth lub brak uwierzytelniania, a serwer MCP używa klucza API, więc ChatGPT nie może się obecnie połączyć. Zobacz [ChatGPT](#chatgpt). - **"Couldn't register with … sign-in service" lub "add an OAuth Client ID" (Claude Desktop)** — niestandardowy konektor został dodany z opcją logowania. Nie ma identyfikatora klienta OAuth do wprowadzenia: usuń konektor i dodaj go ponownie, wybierając **Authentication → No sign in** oraz wpisując swój klucz API jako nagłówek żądania `X-API-Key`, zgodnie z instrukcją [Claude Desktop](#claude-desktop). - **Claude Desktop nie pokazuje narzędzi po edycji pliku konfiguracyjnego** — plik konfiguracyjny ignoruje wpis `"url"`; użyj niestandardowego konektora lub formularza `mcp-remote` w [Claude Desktop](#claude-desktop), a następnie całkowicie zamknij i otwórz ponownie aplikację. - **Narzędzie zwraca `403`** — Twój plan lub rola w zespole nie zezwalają na tę akcję; serwer MCP nie narzuca żadnych dodatkowych ograniczeń, obowiązuje ta sama kontrola uprawnień co w API. - **Tool not found** — lista narzędzi jest generowana na żywo z API, więc zawsze odpowiada bieżącej wersji; połącz się ponownie, aby odświeżyć. - **Ostrzeżenie o zabezpieczeniach lub certyfikacie w Twojej własnej domenie** — samo wskazanie rekordu DNS na nas nie wystarczy: subdomena musi również zostać zweryfikowana w panelu, zanim będzie mogła obsługiwać bezpieczne połączenie. Agencje korzystające z white-label mogą umieścić adres MCP w swojej własnej domenie (np. `mcp.youragency.com`) z poziomu karty **Custom domain** w sekcji **Settings → White Labeling** — najpierw dodaj rekord CNAME u swojego rejestratora, następnie wprowadź nazwę hosta w bloku **MCP domain (AI assistants)** i kliknij **Verify**; proces jest taki sam jak w przypadku innych Twoich markowych subdomen. Markowy adres nie zawiera narzędzi agencji; w tym celu nadal używaj standardowego, niemarkowego adresu. Dopóki Twój markowy adres nie zostanie zweryfikowany, używaj standardowego, niemarkowego adresu: można go bezpiecznie udostępniać klientom. --- ## Następne kroki - [Dostęp do API](api-access.md) — wygeneruj lub zresetuj klucz używany przez to połączenie. - [Webhooki](webhooks.md) — odpowiednik tego połączenia MCP typu pull, działający w modelu push.