API trivia dla twórców agentów AI

Po co to istnieje

Co zbudujesz

Stack - MCP-first, hostowany zdalnie

• MCP po Streamable HTTP - pojedynczy POST na /mcp per tools/call, mieści się w standardowym prymitywie Web fetch. Bez SSE, bez długotrwałych połączeń, bez potoków stdio.
• Auth Bearer - Authorization: Bearer qb_pk_... przy każdym zapytaniu. Klucze publishable (prefiks qb_pk_) są projektowane pod narzędzia klienckie; klucze secret (qb_sk_) też zadziałają, jeśli wolisz trzymać klucz wyłącznie po stronie serwera.
• 12 narzędzi, 3 zasobów, 4 promptów - pełna powierzchnia możliwości MCP. quizbase_random, quizbase_list, quizbase_question_by_id, quizbase_categories, quizbase_topics, quizbase_topic_by_slug, quizbase_tags, quizbase_subcategories, quizbase_languages, quizbase_regions, quizbase_stats, quizbase_report. Plus zasoby z kanonicznymi listami kategorii/języków/topików oraz prompty build_quiz / explore_topic / warmup_round / client_mechanics_patterns.
• Bezstanowy, świeży per zapytanie - serwer używa sessionIdGenerator: undefined. Bez księgowania sesji, bez stanu w Redis, przyjazny GC. Hosty skalują się liniowo.
• Darmowy plan - 500 wywołań narzędzi/dzień, bez karty. Ten sam limit co REST (jeden licznik per użytkownik). Zapytania do MCP i REST czerpią z tej samej puli; nagłówki rate limit (RateLimit-Limit, RateLimit-Remaining) zwracane przy każdej odpowiedzi.

Zepnij to krok po kroku

Sześć kroków, pięć minut. Bez kodu do napisania - cała integracja to plik JSON i restart. Każdy krok to jeden akapit kontekstu, a po nim to, co wkleić. Jeśli krok zawiedzie, sekcja pułapek poniżej ma faktyczny fix na każdą częstą przyczynę.

1. Krok 1
   Zdobądź klucz API publishable

   Zarejestruj się na quizbase.runriva.com/pricing - wybierz darmowy plan (bez karty, 500 wywołań narzędzi/dzień, każdy endpoint i każde narzędzie odblokowane). Po rejestracji w dashboardzie masz przycisk "Create key". Wybierz **klucz publishable** (prefiks `qb_pk_…`, etykieta scope `publishable` w dashboardzie) - klucze publishable są projektowane pod narzędzia client-side i Custom Connectors. Skopiuj go raz (pokazany czystym tekstem dokładnie raz, ze względów bezpieczeństwa) i odłóż na bok do kolejnego kroku.

   txt

   qb_pk_<your_32_alphanumeric_publishable_key>

2. Krok 2
   Wybierz klienta i zepnij połączenie

   QuizBase MCP jest **zdalny** (Streamable HTTP, specyfikacja MCP 2025-11-25), więc spięcie zależy od tego, jakiego klienta używasz. **Claude.ai i Claude Desktop**: otwórz Settings → Connectors → Add custom connector → URL `https://quizbase.runriva.com/mcp`, wybierz Bearer token, wklej swój klucz `qb_pk_*`, zapisz. Czysty interfejs, bez pliku konfiguracyjnego. **Cursor**: wrzuć `.cursor/mcp.json` do katalogu głównego projektu (albo `~/.cursor/mcp.json` globalnie). **MCP Inspector** (do eksploracji deweloperskiej): uruchom `npx @modelcontextprotocol/inspector` i połącz się z Transport=Streamable HTTP, auth Bearer. Pełny przewodnik ze zrzutami ekranu znajdziesz pod `/docs/guides/mcp-for-claude`.

   json

   {
     "mcpServers": {
       "quizbase": {
         "url": "https://quizbase.runriva.com/mcp",
         "headers": {
           "Authorization": "Bearer qb_pk_your_key_here"
         }
       }
     }
   }

3. Krok 3
   Zrestartuj klienta i zweryfikuj

   Dla Cursora: zamknij i otwórz ponownie (Cmd+Q na macOS, nie samo zamknięcie okna - proces pomocniczy musi załapać `.cursor/mcp.json`). Dla Claude.ai lub Claude Desktop po dodaniu Custom Connectora: narzędzia pojawią się automatycznie w kolejnej wiadomości, bez restartu. W świeżej rozmowie wpisz prompt weryfikacyjny poniżej. Agent wyśle zapytanie `tools/list` do serwera QuizBase i odczyta z odpowiedzi jedenaście nazw narzędzi. Jeśli coś jest nie tak (literówka w URL, brakujący prefiks `Bearer `, odwołany klucz), klient zgłasza błąd po ludzku - RFC 9457 Problem Details po stronie serwera oznacza zrozumiałe komunikaty błędów, nie tylko kody statusu.

   txt

   What MCP tools do you have access to from the quizbase server?

4. Krok 4
   Wywołaj pierwsze narzędzie z języka naturalnego

   Nie wywołujesz narzędzi bezpośrednio - opisujesz, czego chcesz, a Claude wybiera narzędzie i parametry. Prompt poniżej produkuje `quizbase_random` z `{lang: "en", category: "history", limit: 5, difficulty: "medium"}` i renderuje wynik jako numerowaną listę. Zwróć uwagę, że agent sam dopasował slug kategorii (`history`) i enum trudności (`medium`) z inputSchema - bez promptu uczącego schematu. Na tym polega wartość MCP względem ręcznie sklejanej integracji REST.

   txt

   Use the quizbase MCP server to give me five medium-difficulty history questions in English. Show each question, the four answer choices (correct mixed with incorrect), and which one is the right answer.

5. Krok 5
   Komponuj przepływy z wieloma narzędziami w rozmowie

   Prawdziwa wartość agenta ujawnia się, gdy łączysz narzędzia w łańcuch. Prompt poniżej używa trzech narzędzi po kolei: `quizbase_categories`, żeby odkryć, co jest dostępne, `quizbase_topics`, żeby zawęzić w obrębie kategorii, a potem `quizbase_random` z filtrem topiku, żeby pobrać pytania. Claude wybiera właściwe narzędzie do każdego kroku, a Ty nie musisz go nazywać. Jeśli masz wielokrokowy framework agentowy (LangChain, Autogen, wewnętrzny orkiestrator), obowiązuje ten sam wzorzec - zadeklaruj serwer MCP raz, a agent wywoła to, czego potrzebuje.

   txt

   I want a Polish-language quiz about Roman history.
   
   1. List quizbase categories so I know what is available.
   2. Within history, list curated topics that match "rome" or "roman".
   3. Fetch five random questions from those topics in Polish.
   
   Show me what you found at each step, then the final five questions.

6. Krok 6
   Podłącz Cursor i Claude.ai tym samym kluczem

   Ten sam klucz działa we wszystkich trzech klientach - jeden limit, jedno miejsce do rotacji. Dla **Cursora** wrzuć snippet poniżej do `.cursor/mcp.json` (per projekt) albo `~/.cursor/mcp.json` (globalnie). Dla **Claude.ai web / Claude Desktop** użyj Custom Connectors (Settings → Connectors → Add custom connector, wklej URL i Bearer token, zapisz) - to kanoniczna ścieżka Streamable HTTP dla obu powierzchni Claude. Oba klienty wywołują `tools/list` przy inicjalizacji - `quizbase_*` pojawia się w dostępnych możliwościach niemal natychmiast.

   json

   {
     "mcpServers": {
       "quizbase": {
         "url": "https://quizbase.runriva.com/mcp",
         "headers": {
           "Authorization": "Bearer qb_pk_your_key_here"
         }
       }
     }
   }

Kompletna integracja - jeden plik JSON

Jeśli pominąłeś przewodnik i chcesz samo spięcie, oto cały `.cursor/mcp.json`. Podmień placeholder na swój klucz, wrzuć do katalogu głównego projektu, zrestartuj Cursora, a 12 narzędzi pojawi się w Twojej kolejnej wiadomości w composerze. Ta sama postać JSON działa dla dowolnego klienta MCP opartego na URL (Continue.dev, Windsurf, Zed - nieprzetestowane przez nas, ale zgodne ze specyfikacją). Dla Claude.ai / Claude Desktop odpowiednikiem jest interfejs Custom Connectors (Settings → Connectors → Add custom connector - ten sam URL i Bearer token, bez pliku).

{
  "mcpServers": {
    "quizbase": {
      "url": "https://quizbase.runriva.com/mcp",
      "headers": {
        "Authorization": "Bearer qb_pk_your_key_here"
      }
    }
  }
}

Pobierz darmowy klucz API na /pricing - bez karty kredytowej.

Niech AI zbuduje agenta - Cursor, Projekt Claude.ai, ChatGPT

Zepiąłeś serwer MCP. Teraz chcesz agenta, który go używa. Trzy prompty poniżej - wklej do Cursora (zbuduj klienta CLI w TypeScript), Custom Instructions w Claude.ai (trwały Projekt codziennej trivia) albo kreatora ChatGPT Custom GPT (zepnij akcję OpenAPI). Każdy prompt jest samodzielny: zawiera katalog narzędzi, schemat auth i oczekiwany kształt rezultatu, żeby AI nie musiało niczego zgadywać.

I have QuizBase MCP connected in Cursor (.cursor/mcp.json — 12 quizbase_* tools available).

Build a CLI utility in TypeScript that:

1. Accepts `--lang`, `--category`, `--count`, `--difficulty` flags.
2. Calls the quizbase_random tool with those filters.
3. Renders each question + shuffled choices to stdout.
4. Tracks the user's answers (read from stdin), shows feedback per question, prints a final score.
5. Handles the case where quizbase_random returns fewer questions than requested (small categories).
6. Uses the @modelcontextprotocol/sdk Client to connect — same Bearer key as the Cursor config, read from QUIZBASE_API_KEY env var.

Single file (src/cli.ts), runnable with `tsx src/cli.ts`. Use Node's readline for stdin, no external deps beyond the MCP SDK.

I have QuizBase MCP connected to Claude.ai / Claude Desktop via Custom Connectors. Build me a daily trivia routine I can save as a Claude.ai Project.

Project instructions should:

1. On first message of a session, call quizbase_categories to discover what is available.
2. Ask me which category I want today (default: random pick).
3. Use quizbase_random with that category, limit 5, difficulty random per question.
4. Render each question one at a time — wait for my answer before showing the correct one.
5. Track my score across the session.
6. After 5 questions, call quizbase_topics to suggest deeper topics in the categories I scored worst on.
7. Save the daily score to my Claude.ai memory (project artifact).

Generate the project description prompt I should paste into Claude.ai's new Project setup.

I want to wire QuizBase as a ChatGPT Custom GPT action.

ChatGPT actions consume OpenAPI — QuizBase exposes one at https://quizbase.runriva.com/openapi.json.

Generate the Custom GPT configuration:

1. Description and conversation starters that emphasize trivia agent use cases.
2. Instructions that explain to the model how to call the API (X-API-Key header, response shape, attribution requirements).
3. Authentication settings (API Key, header X-API-Key, custom prefix none).
4. The OpenAPI schema URL (the full openapi.json from the URL above).
5. Privacy policy URL (https://quizbase.runriva.com/legal/privacy).

Output the configuration as a checklist with the exact values to paste into each ChatGPT Custom GPT setup field.

Konfiguracja MCP - czterej klienci, ten sam klucz

Serwer Model Context Protocol pod `https://quizbase.runriva.com/mcp` wystawia 12 typowanych narzędzi, 3 zasobów i 4 promptów po Streamable HTTP z auth Bearer. Poniżej cztery konfiguracje klientów: trzej główni hostowani agenci (Cursor, Claude Code CLI, Claude.ai Custom Connectors) plus wrapper zbuduj-własny, gdy potrzebujesz własnej powierzchni narzędzi.

• Natywne wywołania narzędzi - Twój agent widzi quizbase_random, quizbase_categories i dziewięć kolejnych jako pełnoprawne możliwości z pełnym inputSchema, bez wymaganych promptów uczących schematu.
• Bezstanowy Streamable HTTP - jeden POST per tools/call, bez SSE, bez długotrwałych sesji, bez stanu w Redis po stronie agenta. Skaluje się razem ze środowiskiem uruchomieniowym Twojego agenta.
• RFC 9728 Protected Resource Metadata pod /.well-known/oauth-protected-resource - klienci MCP automatycznie wykrywają schemat auth i URL zasobu.
• Ten sam klucz qb_pk_* wszędzie - Claude Desktop, Cursor, Claude.ai Custom Connectors, Twój własny klient MCP. Jeden limit, jeden dashboard, jedno miejsce do rotacji.

{
  "mcpServers": {
    "quizbase": {
      "url": "https://quizbase.runriva.com/mcp",
      "headers": {
        "Authorization": "Bearer qb_pk_your_key_here"
      }
    }
  }
}

claude mcp add quizbase \
  --transport http \
  --url https://quizbase.runriva.com/mcp \
  --header "Authorization: Bearer qb_pk_your_key_here"

# verify
claude mcp list

Name:    QuizBase
URL:     https://quizbase.runriva.com/mcp
Auth:    Bearer token
Token:   qb_pk_your_key_here

# pip install mcp httpx
import os
from mcp.server.fastmcp import FastMCP
import httpx

QUIZBASE_KEY = os.environ["QUIZBASE_KEY"]
QUIZBASE_URL = "https://quizbase.runriva.com/api/v1"

mcp = FastMCP("daily-trivia")

@mcp.tool()
async def daily_trivia(lang: str = "en", count: int = 5) -> dict:
    """Fetch today's curated trivia mix — categories rotated daily."""
    async with httpx.AsyncClient() as client:
        r = await client.get(
            f"{QUIZBASE_URL}/questions/random",
            params={"lang": lang, "limit": count},
            headers={"X-API-Key": QUIZBASE_KEY},
        )
        return r.json()

if __name__ == "__main__":
    mcp.run()

Chcesz przetestować zanim cokolwiek skonfigurujesz? /playground/mcp to nasz interaktywny tester MCP - wklej klucz, zobacz wszystkie 12 narzędzia, uruchom je z poziomu formularza, skopiuj JSON.

Zobacz to w akcji

Inne stacki agentowe - te same dane, inne środowisko

MCP przez Claude Desktop / Cursor / Claude.ai to najłatwiejsze wejście. Jeśli Twój agent żyje w innym środowisku - LangChain, Vercel AI SDK albo czyste Claude Messages API - warstwa danych QuizBase wpina się porównywalnym kodem. Trzy warianty poniżej.

# pip install langchain langchain-mcp-adapters langchain-anthropic
from langchain_anthropic import ChatAnthropic
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient({
    "quizbase": {
        "url": "https://quizbase.runriva.com/mcp",
        "transport": "streamable_http",
        "headers": {"Authorization": "Bearer qb_pk_your_key_here"},
    }
})

async def main():
    tools = await client.get_tools()
    agent = create_react_agent(ChatAnthropic(model="claude-opus-4-7"), tools)
    response = await agent.ainvoke(
        {"messages": "Give me 3 hard science questions in Spanish."}
    )
    print(response["messages"][-1].content)

import asyncio; asyncio.run(main())

// npm i ai @ai-sdk/anthropic @modelcontextprotocol/sdk
import { anthropic } from '@ai-sdk/anthropic';
import { streamText, convertToModelMessages, type UIMessage } from 'ai';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp';

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const transport = new StreamableHTTPClientTransport(
    new URL('https://quizbase.runriva.com/mcp'),
    {
      requestInit: {
        headers: { Authorization: `Bearer ${process.env.QUIZBASE_KEY}` }
      }
    }
  );

  // Use the Vercel AI SDK MCP client to connect to QuizBase MCP.
  // The import + API for the MCP client have moved across AI SDK versions —
  // see https://ai-sdk.dev for the current import path and call signature.
  const mcp = await createMcpClientFromAiSdk({ transport });
  const tools = await mcp.tools();

  const result = streamText({
    model: anthropic('claude-opus-4-7'),
    messages: convertToModelMessages(messages),
    tools,
    onFinish: async () => { await mcp.close(); }
  });
  return result.toUIMessageStreamResponse();
}

// npm i @anthropic-ai/sdk
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const QUIZBASE_TOOL = {
  name: 'random_trivia',
  description: 'Fetch random trivia questions filtered by category and language.',
  input_schema: {
    type: 'object' as const,
    properties: {
      lang: { type: 'string', enum: ['en', 'pl'] },
      category: { type: 'string' },
      limit: { type: 'integer', minimum: 1, maximum: 50 }
    },
    required: ['lang']
  }
};

async function runTool(input: { lang: string; category?: string; limit?: number }) {
  const url = new URL('https://quizbase.runriva.com/api/v1/questions/random');
  url.searchParams.set('lang', input.lang);
  if (input.category) url.searchParams.set('category', input.category);
  url.searchParams.set('limit', String(input.limit ?? 5));
  const r = await fetch(url, {
    headers: { 'X-API-Key': process.env.QUIZBASE_KEY! }
  });
  return r.json();
}

const reply = await anthropic.messages.create({
  model: 'claude-opus-4-7',
  max_tokens: 1024,
  tools: [QUIZBASE_TOOL],
  messages: [{ role: 'user', content: 'Five hard history questions in English.' }]
});
// then handle tool_use → runTool(input) → tool_result loop

Pułapki - rzeczy, na których się potkniesz

Sześć haczyków, które widzimy w realnych zgłoszeniach do supportu, z faktycznym fixem. Jeśli na któryś trafisz, ta sekcja oszczędzi Ci dziesięciu minut archeologii w logach agenta.

• Claude mówi "I do not have any tools from quizbase" po tym, jak skonfigurowałem connector.

  Dla Custom Connectors w Claude.ai / Claude Desktop: otwórz rozmowę na nowo (narzędzia odświeżają się per rozmowę, nie zawsze per wiadomość). Zweryfikuj status connectora w Settings → Connectors - powinien pokazywać 'Connected' (zielona kropka). Wklej Bearer key ponownie, jeśli connector pokazuje błąd auth. Dla Cursora: zamknij w pełni (Cmd+Q na macOS) i otwórz ponownie - proces pomocniczy cache'uje .cursor/mcp.json aż do restartu. Zweryfikuj, że JSON się parsuje (jq . .cursor/mcp.json), że URL nie ma literówki (dokładnie https://quizbase.runriva.com/mcp) i że prefiks Authorization: Bearer jest poprawny w wartości nagłówka.

• Błędy `401 Unauthorized` w logach agenta.

  Częste przyczyny: brak prefiksu Bearer w wartości nagłówka Authorization (tak, spacja ma znaczenie), białe znaki na końcu klucza, klucz odwołany w dashboardzie albo użycie klucza z innego konta. Odpowiedź 401 niesie nagłówek RFC 9728 WWW-Authenticate: Bearer realm="quizbase", resource_metadata="..." - dobrze zachowujący się klienci MCP idą za nim do dokumentu metadanych i czytelnie zgłaszają problem z auth.

• Rate limit trafiony podczas dev - 429 z `/mcp` po kilkuset wywołaniach narzędzi.

  Darmowy plan to 500 wywołań narzędzi/dzień per konto. **Wywołania narzędzi liczą się tak samo jak zapytania REST** (jeden licznik per użytkownik) - jeśli jednocześnie uderzasz w /api/v1/* z testów, dzielicie tę samą pulę. Odpowiedź 429 zawiera RateLimit-Remaining: 0, RateLimit-Reset: i Retry-After: . Poczekaj albo upgrade. Ten sam dashboard, ten sam klucz - bez osobnego cennika MCP.

• Cursor / Claude.ai łączy się, ale zgłasza 'CORS error' albo 'forbidden host'.

  QuizBase MCP włącza ścisłe CORS - dozwolone są tylko origins claude.ai, app.cursor.sh i localhost. Plus ochrona przed DNS rebinding: nagłówek Host musi pasować do quizbase.runriva.com (albo *.up.railway.app dla domen Railway). Jeśli uruchamiasz własnego klienta z nietypowego origina, przepuść ruch przez własny backend; serwer jest zaprojektowany pod klientów first-party, nie pod bezpośredni fetch z przeglądarki z dowolnych domen.

• Wywołanie narzędzia zwraca `isError: true` z `error: "not_found"` - co się stało?

  Błędy narzędzi mapują się na RFC 9457 Problem Details w structuredContent.error. not_found dla quizbase_topic_by_slug oznacza, że slug nie istnieje - najpierw wylistuj dostępne przez quizbase_topics. invalid_input oznacza, że schemat Zod odrzucił argumenty (sprawdź details.path po nazwę pola). rate_limit_exceeded to 429 powyżej; internal_error to bug serwera - zgłoś go przez quizbase_report (tak, meta-narzędzie) z request id z odpowiedzi.

• Przepływ OAuth jeszcze niewspierany - mój klient oczekuje Dynamic Client Registration.

  QuizBase używa statycznych tokenów Bearer (jeden klucz publishable per agent). RFC 9728 Protected Resource Metadata jest wystawione pod /.well-known/oauth-protected-resource, więc klienci mogą wykryć schemat auth. Jeśli Twój klient MCP upiera się przy tańcu OAuth, zahardkoduj nagłówek Bearer w requestInit.headers transportu zamiast pozwalać klientowi negocjować.

Najczęściej zadawane pytania

Czy serwer MCP liczy się inaczej niż REST przy rate limitach?

Nie. Jest jeden limit per konto użytkownika - zapytania REST, `tools/call` MCP, `resources/read` MCP i `prompts/get` MCP konsumują z tej samej puli. Darmowy plan: 500 zapytań/dzień, burst 10 zapytań na 10 sekund. Nagłówki rate-limit IETF (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`) pojawiają się przy każdej odpowiedzi, w tym odpowiedziach MCP - Twój klient może wyprzedzająco dławić ruch.

Czy mogę podłączyć QuizBase do agenta LangChain / LlamaIndex / Autogen?

Tak, na trzy sposoby. Albo użyj adaptera MCP specyficznego dla frameworka (LangChain ma `langchain-mcp-adapters`, Vercel AI SDK ma wbudowanego klienta MCP - sprawdź https://ai-sdk.dev po aktualny import, zmieniał się między wersjami, LlamaIndex ma `llama-index-tools-mcp`) i pozwól frameworkowi konsumować 12 narzędzi QuizBase natywnie. Albo opakuj REST we własny `BaseTool`, jeśli potrzebujesz tylko jednego czy dwóch endpointów, a narzut MCP nie jest tego wart. Albo zbuduj cienki wrapper serwera MCP (Python lub TS), który ponownie wystawia QuizBase pod nazwami narzędzi specyficznymi dla domeny - przykład w sekcji "Zbuduj własny serwer MCP" powyżej.

Czy potrzebuję OAuth, czy statyczny token Bearer wystarczy?

Statyczny klucz publishable `qb_pk_*` w nagłówku `Authorization: Bearer ...` wystarczy już dziś. Serwer publikuje RFC 9728 Protected Resource Metadata pod `/.well-known/oauth-protected-resource`, żeby klienci MCP mogli wykryć schemat auth. Dla budujących agentów wdrażających do nietechnicznych użytkowników końcowych: generuj klucze po stronie serwera i wstrzykuj je do konfiguracji MCP klienta przy provisioningu - użytkownik nigdy nie widzi tokenu.

Jak zdebugować nieudane wywołanie narzędzia?

Trzy warstwy. (1) **Warstwa HTTP** - odpowiedź 401/429/500 zawiera `X-Request-Id` i pełne RFC 9457 Problem Details (`type`, `title`, `status`, `detail`). Przegrepuj logi serwera po request id, jeśli masz dostęp (możesz poprosić o CSV zużycia z dashboardu). (2) **Warstwa MCP** - błędy narzędzi zwracają `isError: true` z `structuredContent.error: <code>` (`not_found`, `invalid_input`, `rate_limit_exceeded`, `internal_error`). (3) **Warstwa schematu** - błędy walidacji wejścia zawierają `details.path`, więc wiesz, które pole zawiodło. Większość klientów MCP pokazuje wszystkie trzy; jeśli Twój nie, przełącz się na MCP Inspector na czas debugowania.

Czy mój Custom GPT może wywoływać QuizBase, skoro ChatGPT nie wspiera MCP?

Tak - przez akcje OpenAPI, które Custom GPT wspierają natywnie. QuizBase publikuje specyfikację OpenAPI 3.1 pod `https://quizbase.runriva.com/openapi.json` z każdym endpointem, parametrem i schematem odpowiedzi. W kreatorze Custom GPT w ChatGPT: Configure → Actions → Import from URL → wklej URL OpenAPI → ustaw Auth na API Key, nagłówek `X-API-Key`, wartość `qb_pk_your_key_here`. Twój GPT wywołuje teraz QuizBase jak każde inne REST API - bez warstwy MCP.

Czy opisy narzędzi i inputSchema są tylko po angielsku, czy wielojęzyczne?

Opisy narzędzi są **wyłącznie po angielsku** - LLM-y (Claude, GPT, Gemini) najlepiej rozumieją schematy po angielsku, niezależnie od języka, w jakim produkują wynik. Żeby dostać treść trivia po polsku czy hiszpańsku, przekaż `lang: 'pl'` albo `lang: 'es'` jako argument narzędzia; tekst pytania i warianty odpowiedzi są wtedy w tym języku, ale sam schemat narzędzia pozostaje po angielsku. Ta sama konwencja dotyczy promptów (`build_quiz`, `explore_topic`, `warmup_round`) - instrukcje są po angielsku, a argument `lang` steruje językiem wyjścia.

Jaka jest różnica między `quizbase_random` a `quizbase_list`?

`quizbase_random` jest do "daj mi N pytań, ewentualnie przefiltrowanych, w dowolnej kolejności" - szybkie, przyjazne cache, bez stanu paginacji. `quizbase_list` jest do "daj mi stronę N pytań pasujących do tych filtrów" - wspiera paginację opartą na kursorze (`cursor`, `_links.next` w odpowiedzi), przydatne, gdy potrzebujesz spójnej kolejności między wywołaniami (np. wznowienie przerwanego quizu). Większość przypadków użycia agenta chce `random`. Użyj `list`, gdy potrzebujesz semantyki paginacji.

Czy mogę cache'ować odpowiedzi MCP po stronie agenta?

Tak, dla narzędzi zwracających dane referencyjne - `quizbase_categories`, `quizbase_languages`, `quizbase_stats`, `quizbase_topics` można bezpiecznie cache'ować na godziny lub dni. `quizbase_random` i `quizbase_question_by_id` nie powinny być cache'owane dłużej niż Twoja rozmowa (chcesz świeżej losowości). Trzy **zasoby** MCP (`mcp://quizbase/categories`, `mcp://quizbase/languages`, `mcp://quizbase/topics/top-100`) są wprost zaprojektowane pod cache po stronie klienta - przeczytaj je raz na starcie sesji i używaj do jej końca.

Jak zgłosić błędne pytanie albo złe tłumaczenie przez agenta?

Narzędzie `quizbase_report` istnieje dokładnie do tego. Argumenty: `questionId`, `category` (`wrong-answer`, `bad-translation`, `offensive`, `outdated`, `other`), `details` (string). Agent może wywołać je programowo, gdy użytkownik kwestionuje pytanie w rozmowie. Po stronie serwera raporty trafiają do kolejki moderacji i zasilają nasz przegląd treści. Bez wymaganych PII - tylko id pytania i powód podany przez użytkownika.

Czy serwer MCP jest wystarczająco stabilny dla agentów produkcyjnych?

Tak. Serwer działa na Railway z `adapter-node`, p95 poniżej 100 ms dla wywołań narzędzi, limitowanie zapytań oparte na Redis, bezstanowy transport (bez wymaganego księgowania sesji po stronie klienta), ochrona przed DNS rebinding, allowlista CORS, ustrukturyzowane mapowanie błędów, tracing w Sentry na wolnych wywołaniach narzędzi (>3s).

Dziesięć projektów agentów do wdrożenia - wybierz jeden, zbuduj w tym tygodniu

Masz zepięty serwer MCP. Oto dziesięć projektów agentów wykraczających poza czat-z-quizem - każdy na tyle mały, by wdrożyć go jako MVP na weekend, i na tyle inny, że powstały agent jest własnym produktem.

1. 1. Bot trivia na Slacku zasilany MCP Artykuł →

   Bot na Slacku, który codziennie o 10:00 wrzuca pytanie, punktuje odpowiedzi i prowadzi tygodniowe rankingi. Podłącz QuizBase MCP do środowiska uruchomieniowego agenta swojego bota (Claude Code, Vercel AI SDK albo LangChain) i pozwól agentowi dobierać kategorie na podstawie zainteresowań zespołu wywnioskowanych z historii wiadomości.

2. 2. Projekt Claude.ai: codzienny poranny quiz Artykuł →

   Osobisty Projekt Claude.ai z własnymi instrukcjami, który co rano pobiera trzy pytania przez `quizbase_random`, śledzi Twój wynik w czasie w artefakcie Projektu i podpowiada głębsze topiki z `quizbase_topics` na podstawie słabych punktów.

3. 3. Boczny panel Cursora: pomodoro kod-i-quiz Artykuł →

   Rozszerzenie do Cursora (albo po prostu przepływ sterowany composerem), które miesza uzupełnianie kodu z 25-minutowym blokiem skupienia zakończonym 5-minutową przerwą na trivia. Agent pobiera jedno pytanie quizbase na przerwę, żeby przełączyć Twój kontekst poznawczy.

4. 4. Custom GPT: korepetytor trivia dla dzieci Artykuł →

   ChatGPT Custom GPT podpięty do akcji OpenAPI QuizBase. Filtruje przez `?category=animals,sports` i `?difficulty=easy`, żeby pozostać dopasowanym do wieku. Przepływ rozmowy: zadaj pytanie, oceń odpowiedź, wyjaśnij temat przyjaznym językiem, jeśli była błędna.

5. 5. Agent agregujący wiele źródeł Artykuł →

   Twój agent łączy QuizBase MCP dla trivia z serwerem MCP Wikipedii dla kontekstu. Przychodzi pytanie, agent pobiera je z QuizBase, wywołuje Wikipedię po krótki przewodnik po temacie i prezentuje oba. Efekt: trivia z przełącznikiem trybu nauki, zero pracy nad datasetem od zera.

6. 6. Agent głosowy: skill trivia dla Alexa / Google Home

   Opakuj QuizBase REST w backend Alexa Skill albo Google Home Action. Agent czyta pytanie na głos, parsuje odpowiedź głosową, punktuje. Trudna część - parsowanie głosu - to problem Twojej platformy; treść trivia to jeden fetch.

7. 7. Wewnętrzny bot Discord dla społeczności uczącej się

   Bot Discord, który dołącza do kanałów i oferuje rundy trivia powiązane z tematem kanału. Kanał `#python` dostaje `?tags=python`, `#history` dostaje `?category=history`. Wyniki śledzone per użytkownik, tygodniowe podsumowanie. Robotą jest framework bota; dane to jeden serwer MCP.

8. 8. Mailowy digest trivia - codziennie 90 sekund

   Resend lub Postmark + środowisko uruchomieniowe Twojego agenta + QuizBase MCP. Subskrybent wybiera topiki przy zapisie, agent składa trzy pytania, wysyła mailem. Open rate bije newslettery 3-5x. Agent dobiera trudność na podstawie wcześniejszych sygnałów open/click.

9. 9. Ewaluator trivia do benchmarków LLM

   Użyj QuizBase jako zbioru testowego held-out do oceny pamięci faktograficznej własnego LLM. Agent pobiera N losowych pytań, ocenia odpowiedzi modelu, produkuje raport benchmarku. Atrybucja per rekord pozwala cytować źródło na potrzeby compliance - bez scrapowania, bez niejasności licencyjnych.

10. 10. Inteligentny agent programu nauczania dla aplikacji edukacyjnych dla dorosłych

    Agent przyjmuje cel użytkownika ("podszkolić się z historii Rzymu") i produkuje 30-dniowy plan, komponując `quizbase_topic_by_slug` dla istotnych topików, `quizbase_random` dla codziennych ćwiczeń i `quizbase_stats` do oszacowania pokrycia datasetu. Plan dostosowuje się na podstawie codziennego sygnału punktacji.

Co zbudować dalej

Masz agenta + MCP. Oto co dalej - każdy link to konkretny następny krok, nie mgliste "przejrzyj naszą dokumentację".

• Wypróbuj każde narzędzie w interaktywnym playgroundzie →

  Wklej swój klucz, zobacz wylistowane wszystkie 12 narzędzi, wypełnij argumenty przez formularz, obserwuj odpowiedź JSON. Zero lokalnej konfiguracji, zero CLI.

• Pełna referencja SDK MCP - narzędzia, zasoby, prompty →

  inputSchema per narzędzie, postać odpowiedzi, przykłady w TypeScript i Pythonie. Schemat URI zasobów. Tabele argumentów promptów.

• Deskryptor wykrywania MCP →

  Deskryptor JSON dla MCP Registry / automatycznego wykrywania przez agentów - protocolVersion, transport, endpoint, capabilities, schema auth, link do docs.

• Referencja REST API (dla akcji OpenAPI / Custom GPT) →

  Każdy endpoint REST z każdym parametrem i przykładem odpowiedzi - podstawa specyfikacji OpenAPI, którą konsumują ChatGPT Custom GPT.

• Cennik i limity →

  Darmowy plan (500 zapytań/dzień, bez karty). Plan Indie (9 USD/mc, 10 000/dzień), gdy wdrażasz. Plan Pro (29 USD/mc, 100 000/dzień), gdy Twój agent staje się wiralowy.