MCP API Referenz

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

Verbindungsdaten

Production Base URL

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

Staging Base URL

https://api-staging.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

Liefert alle Projekte des authentifizierten Kontos.

Parameter

Keine Parameter erforderlich.

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

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

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID, z. B. `proj_demo123`.	Ja

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

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

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja
`profileId`	string	Profil-ID.	Ja

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

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

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja
`profileId`	string	Profil-ID.	Ja

Beispiel-Request

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

Beispiel-Antwort

[]

TOOL list_schedules

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

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja
`profileId`	string	Profil-ID.	Ja

Beispiel-Request

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

Beispiel-Antwort

[]

Suche

TOOL search_knowledge

Durchsucht die ChromaDB-Wissensbasis eines Projekts. limit ist optional und wird serverseitig auf maximal 20 begrenzt.

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja
`query`	string	Suchbegriff.	Ja
`limit`	number	Maximale Trefferzahl, Standard 5, Maximum 20.	Nein

Beispiel-Request

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

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

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

Parameter

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

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

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

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja
`files`	string[]	S3-Keys der zu analysierenden Dateien.	Nein
`config`	object	Weitere Job-Konfiguration.	Nein

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

Listet alle Analyse-Jobs eines Projekts.

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja

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

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

Parameter

Parameter	Typ	Beschreibung	Pflicht
`projectId`	string	Projekt-ID.	Ja
`jobId`	string	Job-ID.	Ja

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).