Przejdź do treści
Zweryfikowano

MCP

Ten sam klucz API, udostępniony agentowi AI jako jedno typowane narzędzie na każdą dozwoloną metodę.

Xuda uruchamia serwer Model Context Protocol pod /mcp, obok /cpi. Połącz z nim agenta obsługującego MCP, przez zalogowanie albo kluczem API, a każda metoda, którą ten klucz może wywołać, pojawia się jako typowane narzędzie, bez osobnej integracji dla agentów AI do napisania.

Łączenie

Są dwa sposoby wejścia i oba kończą się w tym samym miejscu: uprawnieniach klucza API.

Zaloguj się (konektory Claude i inni klienci OAuth)

Dodaj https://xuda.ai/mcp jako własny konektor w Claude (Ustawienia, Konektory, Dodaj własny konektor), zostaw puste pola identyfikatora klienta OAuth i sekretu i naciśnij Połącz. Claude otwiera Xuda: zaloguj się, jeśli jeszcze nie jesteś zalogowany, a okno w panelu zapyta, jako który z Twoich kluczy API ma działać to połączenie. Wybierz jeden i naciśnij Połącz. Claude w sieci, na komputerze, na telefonie i w Cowork dzielą to połączenie, a każde inne konto Claude dodaje je tak samo. Karta Deweloperzy, MCP w panelu pokazuje adres do wklejenia, te kroki i wszystko poniżej.

Claude Code loguje się w ten sam sposób, gdy dodasz serwer bez nagłówka, a potem uruchom /mcp i wybierz Authenticate:

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp

Połączenie nigdy nie ma własnych uprawnień. Każde wywołanie narzędzia działa jako wybrany klucz, więc tryb dostępu klucza, jego lista dozwolonych i jego cofnięcie są też własnością połączenia: cofnij klucz w Deweloperzy, Klucze API i połączenie przestaje działać, a następne logowanie poprosi o inny klucz. Strona wymienia tylko Twoje własne aktywne klucze, a gdy ich nie ma, najpierw utwórz jeden.

Dla deweloperów klientów MCP: serwer jest zgodny ze specyfikacją autoryzacji MCP:

Wywołanie /mcp bez użytecznego tokenu odpowiada 401 z WWW-Authenticate: Bearer resource_metadata="...", dzięki czemu klient znajduje resztę. Tokeny dostępu żyją godzinę, tokeny odświeżania 90 dni i są zastępowane przy każdym użyciu. Pętlowy adres przekierowania (http://localhost albo http://127.0.0.1) pasuje na dowolnym porcie.

Klucz API w nagłówku

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Klucz idzie w nagłówku Authorization: Bearer, ten sam klucz, którego użyłbyś jako api_key w /cpi. Nie ma osobnego poświadczenia MCP. Żądanie bez nagłówka Authorization albo z kluczem, który nie wskazuje aktywnego dokumentu xuda_api_keys, jest odrzucane z 401, zanim zarejestruje się jakiekolwiek narzędzie.

Sesje

Transport to streamable HTTP: pierwsze żądanie to wywołanie MCP initialize, które otwiera sesję i zwraca nagłówek mcp-session-id, a każde kolejne żądanie w tym połączeniu niesie ten sam nagłówek i to samo poświadczenie. Sesja zamyka się po 10 minutach bez żądania. Żądanie w zamkniętej sesji odpowiada 404, a klient MCP sam wtedy zaczyna nową sesję.

Co staje się narzędziem

Narzędzia rejestrują się na początku sesji na podstawie trybu dostępu, który klucz już ma:

  • Pełny dostęp: każda metoda w katalogu, która nie jest private, rejestruje się jako narzędzie, rozstrzygana w chwili połączenia, więc metoda dodana po utworzeniu klucza jest dostępna bez żadnej zmiany samego klucza.
  • Dostęp niestandardowy: rejestrują się tylko metody z listy dozwolonych klucza.

Działająca sesja nadąża za swoim kluczem: sprawdza klucz co minutę, a moduły i wtyczki, które za nim stoją, co pięć, i gdy zestaw narzędzi się zmienił, wysyła notifications/tools/list_changed. Klient, który nasłuchuje (Claude tak robi), odczytuje nową listę bez ponownego łączenia, więc metoda, którą dopuścisz na kluczu, dociera do agenta już połączonego.

Każde narzędzie zachowuje kształt metody: nazwa narzędzia to nazwa metody (get_account_projects, dbs_read, ...), jego tytuł to nazwa metody pisana wielkimi literami na początku słów, jego opis to własny description metody, a jego schemat wejścia jest budowany pole po polu z fields metody, pola obowiązkowe pozostają wymagane, wszystkie inne są opcjonalne. Pole bez rozpoznanego typu nadal staje się dopuszczalnym argumentem narzędzia, zamiast psuć całą sesję, więc jedna dziwnie opisana metoda nigdy nie zabiera ze sobą reszty katalogu.

Klucze Full Stack VPS niosą dodatkowe narzędzia

Klucz ograniczony do Full Stack VPS wystawia też narzędzia zainstalowanych na tej maszynie wtyczek obok powyższych metod ekosystemu, więc agent może sięgnąć w jednej sesji i po platformę, i po to, co deweloper zbudował na maszynie. Zobacz Full Stack VPS.

Wywoływanie narzędzia

Agent wywołuje narzędzie z tymi samymi argumentami, które opisują pola metody. Xuda odpowiada, wywołując metodę wewnętrznie, tak jak zrobiłoby to /cpi/<method>, i zwraca narzędziu kopertę {code, data} metody jako tekst. Nieudane wywołanie nadal wraca normalnie na warstwie MCP, kod -1 i niższy widać w wyniku narzędzia dokładnie tak, jak w zwykłym wywołaniu REST, więc agent odczytuje go tak samo, jak Twoja własna obsługa błędów. Zobacz Błędy.

Żądanie, które zawodzi, zanim jakiekolwiek narzędzie się uruchomi, czyli brakujące lub odrzucone poświadczenie (401), zamknięta sesja (404, kod -32001) albo zniekształcony komunikat MCP, wraca jako błąd JSON-RPC zamiast wyniku narzędzia:

json
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: Invalid Api key" }, "id": null }

Dalej