> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Serwer MCP Paperjoy dla Claude i asystentów AI

> Pozwól, by Claude lub inny asystent AI pisał, wysyłał i śledził odręczne pocztówki za Ciebie.

Paperjoy udostępnia zdalny serwer [MCP](https://modelcontextprotocol.io). Podłącz go do swojego asystenta AI i poproś zwykłym językiem: *„Wyślij kartkę z podziękowaniem do Anny Kowalskiej, ul. Marszałkowska 10, Warszawa”.*

| Ustawienie | Wartość |
| - | - |
| Adres serwera | `https://paperjoy.co/mcp` |
| Transport | Streamable HTTP |
| Uwierzytelnianie | OAuth, przez przeglądarkę |
| Wersja serwera | 1.2.0 |

> [!WARNING]
>
> Serwer MCP zawsze działa w **trybie live**, nawet jeśli w przeglądarce masz włączony tryb testowy. Domyślnie asystent zapisuje pocztówki jako darmowe [szkice](https://docs.paperjoy.co/postcards/drafts.md), więc nic nie zostanie wysłane, dopóki Ty albo asystent nie wyślecie szkicu. Wysłanie szkicu zużywa jeden kredyt.

## Podłącz asystenta

Nie potrzebujesz klucza API. Przy pierwszym połączeniu otworzy się okno przeglądarki z prośbą o zalogowanie do Paperjoy i zatwierdzenie dostępu.

> [tab] Claude
>
> W Claude (w przeglądarce lub aplikacji desktopowej):
>
> 1. Otwórz **Settings → Connectors** i wybierz **Add custom connector**.
> 2. Nazwij go `Paperjoy` i wklej `https://paperjoy.co/mcp` jako adres URL.
> 3. Kliknij **Add**, potem **Connect**, i zatwierdź dostęp w oknie, które się otworzy.
>
> W planach Team i Enterprise właściciel organizacji może najpierw musieć dodać konektor w ustawieniach konektorów organizacji.
>
> > [!NOTE]
> >
> > Nie dodawaj Paperjoy do `claude_desktop_config.json`. Ten plik służy do serwerów lokalnych; zdalne serwery, takie jak Paperjoy, dodaje się jako konektory.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http --scope user paperjoy https://paperjoy.co/mcp
> ```
>
> Następnie uruchom `/mcp` w Claude Code, wybierz **paperjoy** i zaloguj się w przeglądarce. Użyj `--scope project`, aby udostępnić serwer zespołowi przez plik `.mcp.json` projektu.

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add paperjoy --url https://paperjoy.co/mcp
> codex mcp login paperjoy
> ```
>
> Otworzy się przeglądarka, w której zalogujesz się i zatwierdzisz dostęp. Codex CLI, rozszerzenie Codex do IDE i aplikacja ChatGPT na tym samym komputerze korzystają z tej samej konfiguracji.

> [tab] Cursor
>
> Dodaj serwer do `~/.cursor/mcp.json` dla wszystkich projektów albo do `.cursor/mcp.json` w jednym projekcie:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "paperjoy": {
>       "url": "https://paperjoy.co/mcp"
>     }
>   }
> }
> ```
>
> Otwórz ustawienia MCP w Cursorze, wybierz Paperjoy i zaloguj się. W Cursor Agent w terminalu uruchom `cursor-agent mcp login paperjoy`.

> [tab] Inni klienci
>
> Dodaj zdalny serwer **Streamable HTTP** o nazwie `paperjoy` i adresie `https://paperjoy.co/mcp`. Wiele klientów używa takiego formatu:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "paperjoy": {
>       "type": "http",
>       "url": "https://paperjoy.co/mcp"
>     }
>   }
> }
> ```
>
> Niektórzy klienci nazywają ten typ `streamable-http` albo rozpoznają go po adresie. Klient musi obsługiwać OAuth 2.1 z przepływem authorization code, PKCE i logowaniem w przeglądarce. Paperjoy rejestruje klienta automatycznie, więc nie potrzebujesz identyfikatora klienta. Przepływ z kodem urządzenia (device code) nie jest obsługiwany.

![Ekran autoryzacji Paperjoy zatytułowany Autoryzuj Claude, z zalogowanym kontem, uprawnieniem serwera MCP oraz przyciskami Anuluj i Autoryzuj.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/mcp-consent.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=f3a8cf0a3266279937564759c60b4f14)

Ekran zgody pokazuje konto i uprawnienia, które otrzyma asystent.

Kliknij **Autoryzuj**, aby połączyć asystenta, albo **Anuluj**, aby odmówić.

## Dostępne narzędzia

| Narzędzie | Co robi |
| - | - |
| `get-account-status` | Zwraca dane konta i `available_credit_balance`. |
| `create-postcard-tool` | Domyślnie zapisuje darmowy [szkic](https://docs.paperjoy.co/postcards/drafts.md). Wszystkie pola są opcjonalne. Ustaw `draft` na `false`, aby od razu złożyć zamówienie: zużywa to jeden kredyt i wymaga uprawnienia `mcp:submit`. Opcjonalny `idempotency_key`: ponowienie z tym samym kluczem zwraca pierwszą pocztówkę zamiast tworzyć drugą. |
| `update-draft-tool` | Zmienia szkic. Zmieniają się tylko przesłane pola; `null` czyści pole. Wysłanych pocztówek nie można zmienić. |
| `preview-postcard-tool` | Renderuje pocztówkę po ID: PNG odręcznej kartki, PNG zaadresowanej koperty, gdy podano adres, odbiorcę i pismo, oraz podsumowanie z polami `ready_to_submit`, `issues` (brakujące lub nieprawidłowe pola), `overflowing_fields` (tekst, który nie mieści się na kartce) i `envelope_issue`. Dla szkiców zwraca też `review_url`, link otwierający szkic w edytorze Paperjoy. |
| `submit-postcard-tool` | Składa zamówienie ze szkicu po ID i zużywa jeden kredyt. Wymaga uprawnienia `mcp:submit`. Niekompletny szkic zostaje szkicem, a błąd wskazuje, co poprawić. Opcjonalny `idempotency_key`, więc ponowienie rozliczane jest tylko raz. |
| `delete-draft-tool` | Trwale usuwa szkic po ID. Wysłanych pocztówek nie można usunąć. |
| `list-postcards-tool` | Wyświetla Twoje pocztówki od najnowszych, w tym szkice. Filtry: `company_name`, `last_name` (dopasowanie częściowe), `status` (np. `draft`), `limit` (1–100, domyślnie 25). |
| `get-postcard-tool` | Zwraca jedną pocztówkę po ID, np. `pc_MXP7a4Ni0c`. |
| `list-signatures-tool` | Wyświetla Twoje aktywne [własne podpisy](https://docs.paperjoy.co/postcards/custom-signatures.md). Przekaż ID jako `signature_id` przy tworzeniu pocztówki. |

## O co możesz poprosić

* *„Ile kredytów Paperjoy mi zostało?”*
* *„Przygotuj szkic kartki z podziękowaniem dla Studio Forma w Poznaniu i pokaż mi podgląd.”*
* *„Wyślij tę samą kartkę urodzinową do tych trzech osób i użyj mojego podpisu.”*
* *„Czy kartka do Katarzyny Zielińskiej została już wysłana?”*

## Rozwiązywanie problemów

* **Nie otworzyło się okno przeglądarki.** Uruchom ponownie polecenie logowania klienta albo kliknij **Connect** lub **Authenticate** w ustawieniach MCP.
* **Paperjoy jest widoczny, ale nie ma narzędzi.** Sprawdź, czy adres to dokładnie `https://paperjoy.co/mcp`, a potem uruchom ponownie lub odśwież klienta.
* **Klucz API został odrzucony.** Tak ma być. Serwer MCP akceptuje tylko logowanie OAuth.
* **Klient prosi o kod urządzenia.** Użyj klienta, który obsługuje przepływ authorization code z PKCE.

## Limity

* 120 żądań MCP na minutę.
* Zamawianie pocztówek (wysyłka szkicu albo tworzenie z `draft: false`) dzieli dzienny limit 100 z API i edytorem. Szkice się nie wliczają.
* Do 100 otwartych szkiców jednocześnie.
* Podglądy dzielą limit 30 na minutę.

Każda odpowiedź narzędzia dotycząca szkicu zawiera `review_url`, więc asystent może podać Ci link do sprawdzenia i wysłania jej samodzielnie w edytorze.

## Wysyłanie wymaga osobnego uprawnienia

Przy łączeniu Paperjoy prosi o dwa uprawnienia, a ekran akceptacji wyświetla oba:

| Uprawnienie | Na co pozwala |
| - | - |
| `mcp:use` | Odczyt konta, podpisów i pocztówek oraz tworzenie, podgląd i edycja szkiców. |
| `mcp:submit` | Wysyłanie pocztówek w Twoim imieniu, co zużywa kredyty. |

Bez `mcp:submit` asystent może przygotowywać szkice, ale nie może ich wysyłać. `submit-postcard-tool` oraz `create-postcard-tool` z `draft: false` zwracają wtedy błąd z prośbą, by wysłać szkic z pulpitu albo połączyć serwer ponownie i zatwierdzić `mcp:submit`.

Połączenia nawiązane przed wprowadzeniem tego uprawnienia mają tylko `mcp:use`. Połącz serwer ponownie i zatwierdź dostęp jeszcze raz, aby asystent mógł wysyłać pocztówki.

Asystent widzi tylko pocztówki i podpisy z Twojego konta.

> [!NOTE]
>
> Klucze API (`pj_live_`, `pj_test_`) nie działają z serwerem MCP. Używaj ich z [API](https://docs.paperjoy.co/getting-started/quickstart.md) i [Zapierem](https://docs.paperjoy.co/integrations/zapier.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.