MCP API Referenz

Beta

Model Context Protocol Schnittstelle fuer AI-Agenten, die sicher auf Audience-Suite-Projekte, Zielgruppenprofile, Content-Plaene und die semantische Wissensbasis zugreifen sollen.

Was ist MCP?

Das Model Context Protocol ist ein Standard, mit dem AI-Clients Tools und Datenquellen ueber eine einheitliche Schnittstelle nutzen koennen.

Authentifizierung

Der zentrale MCP-Server ist ueber nutzerspezifische API-Tokens geschuetzt. Jeder Token ist an ein Konto gebunden und trennt Daten mandantenspezifisch.

Authorization: Bearer YOUR_API_TOKEN

API Token / Key erstellen

Einen API Token oder Key koennen Sie hier erstellen: suite.audience-experts.de/api-tokens

Verbindungsdaten

Production Base URL

https://api.audience-suite.de/mcp

SSE Endpoint

/sse

Message Endpoint

/messages?sessionId=<SESSION_ID>

Integration

Claude Desktop nutzt lokale MCP-Server per stdio. Ein Bridge-Adapter kann die Cloud-API anbinden.

Konfigurationsdatei

claude_desktop_config.json bearbeiten:

{
  "mcpServers": {
    "audience-suite": {
      "command": "npx",
      "args": ["-y", "@audience-suite/mcp-bridge"],
      "env": {
        "AUDIENCE_SUITE_API_TOKEN": "YOUR_API_TOKEN",
        "AUDIENCE_SUITE_API_URL": "https://api.audience-suite.de/mcp"
      }
    }
  }
}

Claude Desktop nach Aenderungen an der Konfiguration neu starten.

Direkte Verbindung zum SSE-Stream ueber ein MCP-kompatibles SDK oder eine eigene Client-Implementierung.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("https://api.audience-suite.de/mcp/sse"),
  {
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN"
    }
  }
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

Projekte

TOOL list_projects

Authorization required

Liefert alle Projekte des authentifizierten Kontos.

Request-Parameter	Typ	Erlaeuterung
`Keine`	--	Der Tool-Aufruf erwartet keine Parameter.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks, meist `text`.
`text`	string	JSON-kodierte Projektliste.

Beispiel-Request

{}

Beispiel-Antwort

[
  {
    "projectId": "proj_demo123",
    "type": "Project",
    "projectType": "files",
    "state": "Finished",
    "name": "Demo Analyseprojekt",
    "description": "Auswertung von Interviews und Frageboegen",
    "createdAt": "2026-01-08T14:44:35.026Z",
    "data": {
      "iconColor": "bg-blue-500",
      "iconName": "Briefcase"
    },
    "options": {
      "profileCount": 1,
      "files": [
        {
          "name": "Interview 01.docx",
          "lastModified": 1766161526004,
          "size": 18159359,
          "type": "einzelinterview"
        }
      ]
    }
  }
]

Profile

TOOL list_profiles

Authorization required

Liefert alle Zielgruppenprofile eines Projekts. Die Antwort ist ein Array aus Profil-Objekten.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID, z. B. `proj_demo123`.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodierte Profil-Liste.

Beispiel-Request

{"projectId": "proj_demo123"}

Beispiel-Antwort

[
  {
    "projectId": "proj_demo123",
    "profileId": "prof_demo456",
    "name": "Alex Beispiel",
    "beschreibung": "",
    "createdAt": "2026-01-08T15:15:55.876Z",
    "userNeeds": {
      "Keep me engaged": 5,
      "Educate me": 4,
      "Connect me": 5
    },
    "categories": [
      {
        "name": "Person und Kontext",
        "sources": ["Interview 01.docx"],
        "items": [
          {
            "typ": "aussage",
            "text": "Legt grossen Wert auf vertraulichen Austausch."
          }
        ]
      }
    ]
  }
]

TOOL get_profile

Authorization required

Liefert ein einzelnes Profil inklusive Kategorien, Quellen, Kernaussagen, Eigenschaften, Werten und User-Needs.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`profileId`	string	Profil-ID.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodiertes Profil-Objekt.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "profileId": "prof_demo456"
}

Beispiel-Antwort

{
    "projectId": "proj_demo123",
    "profileId": "prof_demo456",
  "name": "Alex Beispiel",
  "beschreibung": "",
  "schwartz_values": {
    "Macht": 3,
    "Universalismus": 2,
    "Wohltätigkeit": 5
  },
  "eigenschaften": [
    {
      "name": "Anpassungsfähigkeit",
      "description": "Reagiert flexibel auf neue Anforderungen."
    }
  ],
  "kernwerte": [
    {
      "name": "Innovation",
      "description": "Sucht nach neuen und besseren Loesungen."
    }
  ],
  "categories": []
}

Feeds & Plaene

TOOL list_feeds

Authorization required

Listet Content-Feeds eines Profils. Wenn noch keine Feeds existieren, wird ein leeres Array geliefert.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`profileId`	string	Profil-ID.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodierte Feed-Liste.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "profileId": "prof_demo456"
}

Beispiel-Antwort

[]

TOOL list_schedules

Authorization required

Listet Redaktions- oder Veroeffentlichungsplaene eines Profils. Wenn noch keine Plaene existieren, wird ein leeres Array geliefert.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`profileId`	string	Profil-ID.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodierte Plan-Liste.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "profileId": "prof_demo456"
}

Beispiel-Antwort

[]

Suche

TOOL search_knowledge

Authorization required

Durchsucht die ChromaDB-Wissensbasis eines Projekts. limit ist optional und wird serverseitig auf maximal 20 begrenzt. Mit type kannst du die Suche auf both, insight oder chunk begrenzen.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`query`	string	Suchbegriff.
`limit`	number	Maximale Trefferzahl, Standard 5, Maximum 20.
`type`	string	Optionaler Suchumfang. Erlaubt sind `both`, `insight` und `chunk`.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodierte Trefferliste.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "query": "Community",
  "limit": 2,
  "type": "insight"
}

Beispiel-Antwort

[
  {
    "id": ["chunk_demo_001"],
    "text": ["Relevanter Ausschnitt aus Interview oder Fragebogen."],
    "metadata": [
      {
        "type": "insight",
        "projectId": "proj_demo123",
        "source": "Interview 01.docx"
      }
    ]
  }
]

Jobs

TOOL create_profile_job

Authorization required

Startet einen Hintergrundjob zur Profilgenerierung. Erfolgsaufrufe legen echte Jobs an und verbrauchen Credits.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`profileCount`	number	Anzahl zu erzeugender Profile.
`files`	string[]	S3-Keys der zu analysierenden Dateien.
`config`	object	Weitere Job-Konfiguration.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	Textmeldung mit Job-ID und Kreditkosten.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "profileCount": 2,
  "files": ["users/user_demo/projects/proj_demo123/inputs/interview.docx"]
}

Beispiel-Antwort

{
  "content": [
    {
      "type": "text",
      "text": "Profile creation job successfully created: job_demo002 (Cost: 10 credits)"
    }
  ]
}

TOOL create_analysis_job

Authorization required

Startet eine reine Analyse ohne Profilgenerierung. Erfolgsaufrufe legen echte Jobs an.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`files`	string[]	S3-Keys der zu analysierenden Dateien.
`config`	object	Weitere Job-Konfiguration.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	Textmeldung mit Job-ID und Kreditkosten.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "files": ["users/user_demo/projects/proj_demo123/inputs/interview.docx"]
}

Beispiel-Antwort

{
  "content": [
    {
      "type": "text",
      "text": "Analysis job successfully created: job_demo001 (Cost: 2 credits)"
    }
  ]
}

TOOL list_jobs

Authorization required

Listet alle Analyse-Jobs eines Projekts.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodierte Job-Liste.

Beispiel-Request

{
  "projectId": "proj_demo123"
}

Beispiel-Antwort

[
  {
    "type": "Job",
    "projectId": "proj_demo123",
    "jobId": "job_demo001",
    "jobType": "file",
    "jobMode": "analyze-only",
    "status": "Finished",
    "creditCost": 2,
    "createdAt": "2026-03-15T17:18:10.994Z",
    "updatedAt": "2026-03-15T17:30:26.578Z",
    "config": {
      "profileCount": 0,
      "projectContext": "Demo-Kontext",
      "files": [
        {
          "name": "Interview 01.docx",
          "s3Key": "users/user_demo/projects/proj_demo123/readonly/Interview 01.docx",
          "size": 22271,
          "type": "einzelinterview"
        }
      ],
      "categories": [],
      "imageStyle": "realistic"
    }
  }
]

TOOL get_job

Authorization required

Liefert einen einzelnen Job-Datensatz. Bei unbekannter ID wird eine Fehlerantwort als Textinhalt geliefert.

Request-Parameter	Typ	Erlaeuterung
`projectId`	string	Projekt-ID.
`jobId`	string	Job-ID.

Response-Attribut	Typ	Erlaeuterung
`content`	Array<object>	MCP-Antwort mit einem JSON-Textblock oder einer Fehlermeldung.
`type`	string	Inhaltstyp des Content-Blocks.
`text`	string	JSON-kodierter Job-Datensatz oder Fehltext.

Beispiel-Request

{
  "projectId": "proj_demo123",
  "jobId": "job_demo001"
}

Beispiel-Antwort

{
  "type": "Job",
  "projectId": "proj_demo123",
  "jobId": "job_demo001",
  "jobType": "file",
  "jobMode": "analyze-only",
  "status": "Finished",
  "creditCost": 2,
  "createdAt": "2026-03-15T17:18:10.994Z",
  "updatedAt": "2026-03-15T17:30:26.578Z",
  "config": {
    "profileCount": 0,
    "projectContext": "Demo-Kontext",
    "files": [],
    "categories": []
  }
}

External Resources

Official MCP Website

Learn more about the protocol standard.

MCP SDK (GitHub)

SDKs for Node.js, Python and more.

SSE Documentation

Details on Server-Sent Events (SSE).