MCP-Server

PollYou stellt einen Server für das Model Context Protocol (MCP) bereit. Damit greifen KI-Assistenten wie Claude (Claude Code, Claude Desktop) oder andere MCP-Clients direkt auf deine Organisation zu: Umfragen anlegen und veröffentlichen, Antworten lesen oder löschen, Kennzahlen abfragen.

Die Tools spiegeln die öffentliche API v1 und folgen demselben Stabilitätsversprechen: Felder und Tools kommen nur hinzu, nichts wird umbenannt, entfernt oder ändert seine Bedeutung.

Endpoint und Authentifizierung

Der Server spricht MCP über HTTP (Streamable-HTTP-Transport) unter:

https://api.pollyou.example/mcp

Authentifiziert wird mit denselben API-Schlüsseln wie die öffentliche API v1, als Bearer-Token im Authorization-Header. Ein Schlüssel gehört zu genau einer Organisation; alle Tools arbeiten auf dieser Organisation. Ohne gültigen Schlüssel antwortet der Server mit 401.

Beispiel für Claude Code (.mcp.json im Projekt oder claude mcp add):

{
  "mcpServers": {
    "pollyou": {
      "type": "http",
      "url": "https://api.pollyou.example/mcp",
      "headers": {
        "Authorization": "Bearer py_live_…"
      }
    }
  }
}

Schlüssel geheim halten

Der API-Schlüssel gehört nur in lokale Konfigurationsdateien oder Secret-Stores, nie in Repositories. Gib dem Schlüssel nur die Scopes, die der Assistent wirklich braucht – für reine Auswertungen reichen surveys:read und analytics:read.

Tools

Jedes Tool verlangt einen Scope des API-Schlüssels; ein Schreib-Scope schließt den passenden Lese-Scope ein. Fehlt der Scope, meldet das Tool einen Fehler („The API key lacks the scope …“). Umfragen und Antworten anderer Organisationen existieren aus Sicht des Schlüssels nicht.

Tool	Scope	Entspricht
list_surveys	surveys:read	GET /v1/surveys
get_survey	surveys:read	GET /v1/surveys/{id}
create_survey	surveys:write	POST /v1/surveys
update_survey	surveys:write	PATCH /v1/surveys/{id}
publish_survey	surveys:write	POST /v1/surveys/{id}/publish
close_survey	surveys:write	POST /v1/surveys/{id}/close
list_responses	responses:read	GET /v1/surveys/{surveyId}/responses
get_response	responses:read	GET /v1/responses/{id}
delete_response	responses:write	DELETE /v1/responses/{id}
get_survey_analytics	analytics:read	GET /v1/surveys/{id}/analytics

Parameter und Antwortfelder entsprechen der Referenz v1; die Tools liefern die Antwort als strukturierten Inhalt (JSON). Die genauen Ein- und Ausgabeschemata veröffentlicht der Server selbst über tools/list – MCP-Clients zeigen sie automatisch an.

Limits und Verhalten

• Es gilt dasselbe Rate-Limit wie für die öffentliche API: 600 Anfragen pro Minute und Schlüssel.
• Der Zugriff setzt wie die öffentliche API die Plan-Funktion API voraus; sie ist im Preis pro Umfrage enthalten (siehe Preise und Guthaben).
• Fehler kommen als MCP-Fehlermeldung mit derselben Aussage wie der entsprechende v1-Endpunkt (z. B. „Survey not found.“ oder Validierungsmeldungen).
• Jede Anfrage zählt im Audit-Log mit dem API-Schlüssel als Akteur, genau wie bei der öffentlichen API.