Für KI kopieren

MCP-Server (Model Context Protocol)

Der offene Standard, um agentischer künstlicher Intelligenz Finanz-Tools bereitzustellen.

Was ist MCP?

Das Model Context Protocol (MCP) ist ein universeller Standard, mit dem sich KI-Assistenten mit sicheren Datenquellen verbinden können.

Wenn Sie den MCP-Server von Cord einrichten, können Agenten wie Claude oder in IDEs integrierte Assistenten (wie Cursor) ganz natürlich mit Ihrem Unternehmen interagieren.

Fragen, die Sie der KI nach der Verbindung stellen können:

• „Entnimm dem angehängten PDF die Anforderungen und erstelle in Cord ein Angebot für diesen Kunden.“
• „Prüfe die abgelaufenen Angebote der letzten 30 Tage und entwirf mir freundliche Zahlungserinnerungen per E-Mail.“
• „Suche den Kunden Distribuidora El Zarco und lege einen Entwurf mit diesen 3 Positionen an.“

So richten Sie die Verbindung ein

Ihr KI-Client authentifiziert sich mit Ihrem normalen API-Schlüssel von Cord (sk_live_… / sk_test_…) – demselben, den die REST-API verwendet.

1. Öffnen Sie in Cord Einstellungen › MCP. Die Seite liegt im Bereich Entwickler des Einstellungsverzeichnisses, der erscheint, sobald Sie den Entwicklermodus unter Ihr Konto › Präferenzen aktivieren.
2. Eine Statuskarte oben zeigt Ihnen, ob Sie bereits einen aktiven Schlüssel haben und, falls schon ein KI-Client verbunden ist, wann er zuletzt verwendet wurde. Haben Sie keinen, erstellt die Schaltfläche „Schlüssel für MCP erstellen“ einen Schlüssel mit Schreibberechtigung und den Gruppen Lesen und Entwürfe schreiben, ohne dass Sie die Seite verlassen – er wird automatisch in die Konfiguration darunter eingefügt. Kopieren Sie ihn sofort: Er wird nicht noch einmal angezeigt. Um Gruppen oder einzelne Tools zu wählen oder Aktionen mit externer Wirkung zu erlauben, erstellen oder bearbeiten Sie den Schlüssel im Tab Schlüssel der Cord Workbench (siehe Berechtigungen pro Tool).
3. Kopieren Sie die JSON-Konfiguration für den MCP-Client, die auf dem Bildschirm angezeigt wird.
4. Fügen Sie diese Konfiguration am entsprechenden lokalen Pfad Ihres Clients ein (zum Beispiel in die Datei claude_desktop_config.json, wenn Sie die App Claude for Desktop verwenden).

Zwei Verbindungsarten

Streamable HTTP (empfohlen) – POST https://cordhq.app/api/mcp mit dem Header Authorization: Bearer sk_live_…. Ohne Sitzung: Jede JSON-RPC-Nachricht ist eine eigenständige HTTP-Anfrage. Das erwarten die meisten modernen MCP-Clients.

HTTP + SSE (Legacy, für ältere Clients beibehalten) – GET https://cordhq.app/api/mcp/sse öffnet eine langlebige Verbindung und gibt zurück, wohin die Nachrichten zu senden sind (POST /api/mcp/message?sessionId=…). Jede POST-Nachricht muss denselben Authorization: Bearer tragen, mit dem die Sitzung geöffnet wurde – die sessionId in der URL allein genügt nicht (sie wird im Klartext übertragen und kann in Logs zwischengeschalteter Proxys offenliegen), und der Schlüssel muss zu derselben Organisation gehören, die die Sitzung geöffnet hat.

Berechtigungen pro Tool

Jedes Tool gehört zu einer Gruppe und einer Ressource, nach demselben Modell wie die eingeschränkten Schlüssel:

Gruppe	Tools	Schlüssel ohne Liste
Lesen	listar_cotizaciones, detalle_cotizacion, cartera_vencida, resumen_negocio, buscar_cliente, listar_productos, listar_facturas, detalle_factura, listar_workflows_manuales, listar_eventos, estado_configuracion, validar_datos_fiscales, validar_apariencia	Erlaubt
Entwürfe schreiben	crear_cotizacion_borrador, crear_factura_borrador, crear_cliente, crear_tarea, registrar_promesa_pago, proponer_configuracion	Erlaubt mit einem Schlüssel mit Schreibberechtigung
Aktionen mit externer Wirkung	enviar_cotizacion, aprobar_cotizacion, rechazar_cotizacion, registrar_pago_cotizacion, actualizar_cliente, correr_workflow, simular_evento	Gesperrt: nur mit ausdrücklicher Berechtigung, und jeder Aufruf wartet auf Freigabe

Wenn Sie im Tab Schlüssel der Workbench einen Schlüssel erstellen oder bearbeiten, wählen Sie ganze Gruppen oder innerhalb einer Gruppe einzelne Tools. Eine Gruppe umfasst auch Tools, die Cord ihr später hinzufügt; ein einzelnes Tool nur sich selbst. Ein Schlüssel ohne Liste, wie alle vor den Berechtigungen pro Tool erstellten, behält Lesen und Entwürfe gemäß seiner Stufe und kann keine Aktion mit externer Wirkung anfordern, bis jemand sie erlaubt.

• Die Stufe gilt weiter: Ein Schlüssel nur mit Leserecht nutzt keine Entwürfe, auch wenn sie auf seiner Liste stehen, und ein eingeschränkter Schlüssel (rk_) wendet die Stufe jeder Ressource auf jedes Tool an (listar_facturas braucht facturas: read; crear_cotizacion_borrador, cotizaciones: write).
• tools/list liefert nur, was der Schlüssel aufrufen darf. Ruft ein Client ein anderes auf, kommt ein Tool-Fehler, der sagt, welches fehlt und wo man es erlaubt.
• contexto_cuenta und buscar_documentacion sind immer verfügbar: Sie identifizieren das Konto und durchsuchen diese Dokumentation, ohne Kundendaten.

actualizar_cliente gehört zu den Aktionen mit externer Wirkung, obwohl es niemandem schreibt: Cord nutzt E-Mail und Steuerdaten des Kunden, um Erinnerungen, wiederkehrende Rechnungen und Forderungsmanagement ohne weitere Prüfung zu versenden; sie zu ändern wirkt also außerhalb von Cord.

Aktionen, die auf Freigabe warten

Eine Aktion mit externer Wirkung wird nicht ausgeführt, wenn der Agent sie aufruft, selbst wenn der Schlüssel sie erlaubt und der MCP-Client keine Bestätigung verlangt. Cord speichert eine Anfrage und antwortet:

{
  "estado": "pendiente_de_aprobacion",
  "aprobacion_id": "7c1e4b2a-5d3f-4a8e-9b6c-2f1d0e3a4b5c",
  "aprobacion_url": "https://cordhq.app/app/ajustes/mcp/solicitudes?modo=vivo#sol-7c1e4b2a-5d3f-4a8e-9b6c-2f1d0e3a4b5c",
  "vence": "2026-10-18T16:04:00.000Z",
  "mensaje": "No se ejecutó todavía: una persona con acceso a Cord tiene que aprobarla. …"
}

1. Der Agent teilt aprobacion_url mit dem Nutzer.
2. Unter Einstellungen › MCP › Anfragen sieht eine Person mit der Berechtigung Einstellungen und der Berechtigung für die Aktion in der App (Angebote zum Senden oder Erfassen einer Zahlung, Freigaben zum Bestätigen oder Ablehnen, Kunden zum Aktualisieren eines Kunden, Angebote oder Forderungsmanagement für einen Workflow je nach Objekt, Einstellungen zum Simulieren eines Webhooks) das Dokument, was sich ändern würde und die Daten des Agenten, und gibt frei oder lehnt ab.
3. Bei Freigabe führt Cord die Aktion genau einmal aus, mit demselben Handler wie immer. Zwei Personen, die gleichzeitig freigeben, führen sie nicht zweimal aus. Ablehnen führt nichts aus.
4. Für das Ergebnis wiederholt der Agent den Aufruf mit derselben idempotency_key: Die Antwort enthält estado ejecutada (mit dem Rückgabewert der Aktion in resultado), fallida (mit dem Grund in error), rechazada oder vencida.

Die Anfrage läuft nach 72 Stunden ohne Entscheidung ab. Derselbe Aufruf mit denselben Argumenten liefert die offene Anfrage, statt eine neue anzulegen, und eine Organisation erhält höchstens 30 Anfragen pro Stunde. Wird der Schlüssel widerrufen, läuft er ab oder verliert er das Tool vor der Entscheidung, kann die Anfrage nicht mehr freigegeben werden. Mit einem Testschlüssel liegt die Anfrage in der Testumgebung, und der Link zeigt das mit ?modo=prueba.

Verfügbare Tools

Tool	Was es tut	Berechtigung
listar_cotizaciones	Listet Angebote auf, optional nach Status gefiltert.	Lesen
detalle_cotizacion	Vollständige Details eines Angebots: Positionen, Gesamtbeträge, Zeitleiste.	Lesen
cartera_vencida	ÜBERFÄLLIGE offene Forderungen: Betrag, Altersstruktur, Detail pro Kunde.	Lesen
resumen_negocio	KPIs, Conversion-Funnel, Pipeline-Prognose, Tarifnutzung.	Lesen
buscar_cliente	Durchsucht das Verzeichnis nach Unternehmen/Kontakt/RFC/E-Mail. Jeder Kunde enthält language, seine Dokumentsprache (null = die der Organisation). Paginiert.	Lesen
listar_productos	Produktkatalog (ID, SKU, Name, Einheit, Listenpreis). Paginiert.	Lesen
crear_cotizacion_borrador	Erstellt ein Angebot als ENTWURF (ohne es zu senden). Idempotent, wenn Sie idempotency_key übergeben.	Entwürfe
listar_facturas	Listet die Rechnungen von Cord Invoicing mit offenem Betrag und Status auf (draft|open|paid|void|uncollectible|overdue). Filtert nach Status, Kunde oder Freitext. Paginiert.	Lesen
detalle_factura	Vollständige Details EINER Rechnung: Positionen, Aussteller, Empfänger, Steuern, angegebener Wechselkurs, offener Betrag und erhaltene Zahlungen.	Lesen
crear_factura_borrador	Erstellt eine Rechnung als ENTWURF für einen Kunden, ohne dass ein vorheriges Angebot nötig ist. In allen Tarifen verfügbar, auch im kostenlosen.	Entwürfe
enviar_cotizacion	Fordert an, ein Angebot im Entwurf an den Kunden zu senden (E-Mail mit dem Link), in der Dokumentsprache des Kunden. Wartet auf Freigabe. Im kostenlosen Tarif verbraucht das einen der monatlichen Versände.	mit Freigabe
aprobar_cotizacion	Fordert an, ein gesendetes oder angesehenes Angebot als bestätigt zu markieren. Wartet auf Freigabe.	mit Freigabe
rechazar_cotizacion	Fordert an, ein gesendetes oder angesehenes Angebot als abgelehnt zu markieren. Wartet auf Freigabe.	mit Freigabe
registrar_pago_cotizacion	Fordert an, zu erfassen, dass ein bestätigtes Angebot außerhalb von Cord bezahlt wurde; bei Ausführung storniert es seine offenen Online-Zahlungen. Akzeptiert metodo_pago. Wartet auf Freigabe.	mit Freigabe
crear_cliente	Legt einen Kunden an (Unternehmen, Kontakt, E-Mail, Telefon, Steuernummer, Bedingungen, Land und Dokumentsprache: es, en, pt, fr, de oder null).	Entwürfe
actualizar_cliente	Fordert an, die Kontaktdaten eines Kunden zu ändern, auch language. Ändert nur, was Sie senden; Kredit, Stufe und Rabatt bleiben immer unberührt. Bereits Versendetes behält seine Sprache. Wartet auf Freigabe.	mit Freigabe
crear_tarea	Erstellt eine Folgeaufgabe: titulo (Pflicht), optional fecha als Fälligkeitsdatum YYYY-MM-DD, cotizacion_id und factura_id. Sie entsteht ohne zuständige Person und mit normaler Priorität; beides ändern Sie in der App.	Entwürfe
registrar_promesa_pago	Erfasst das Datum, an dem der Kunde zugesagt hat, ein Angebot zu bezahlen. Es wird nichts eingezogen.	Entwürfe
listar_workflows_manuales	Listet die aktiven Workflows „Sie starten ihn“ nach Objekt (quote oder invoice).	Lesen
correr_workflow	Fordert an, einen Workflow „Sie starten ihn“ für bis zu 50 Angebote oder Rechnungen auszuführen, mit der veröffentlichten Version und ihren Regeln. Wartet auf Freigabe; bei Ausführung meldet es, wie viele Ausführungen gestartet wurden.	mit Freigabe
listar_eventos	Verlauf des Unternehmens (Angebote, Rechnungen, Kunden, Aufgaben, Zahlungszusagen), filterbar nach Typ oder Objekt. Paginiert.	Lesen
contexto_cuenta	Unternehmen, Land, Währung, Sprache, Zeitzone, Tarif und ob der Schlüssel ein Test- oder Live-Schlüssel ist. Rufen Sie es zuerst auf.	Lesen
proponer_configuracion	Schlägt Profil, Marke, Steuern, Katalog und Vorlagen auf Basis der Website, einer Beschreibung oder der Preisliste vor (Base64, bis zu 3 MB). Übernimmt nichts: gibt review_url zurück, damit eine Person den Vorschlag freigibt.	Entwürfe
estado_configuracion	Status eines Vorschlags (propuesto, aplicado, descartado, fallido) und das Ergebnis pro Abschnitt.	Lesen
validar_datos_fiscales	Validiert RFC, Steuerregime, CFDI-Verwendung und Postleitzahl (Mexiko), NIF/NIE/CIF (Spanien) oder EIN (USA) mit denselben Regeln wie bei der Ausstellung.	Lesen
validar_apariencia	Validiert ein appearance-Objekt von Elements und meldet, welche Schlüssel Cord verwerfen würde.	Lesen
simular_evento	Fordert an, einen Test-Webhook über die echte Zustelllogik auszulösen. Nur mit Testschlüssel. Wartet auf Freigabe.	mit Freigabe
buscar_documentacion	Durchsucht diese Dokumentation und gibt die relevantesten Seiten mit Auszug und URL zurück.	Lesen

Jedes Tool deklariert die Standard-Annotationen von MCP (readOnlyHint, idempotentHint, destructiveHint) in tools/list. Lesende Tools sind readOnlyHint: true, und solche, die den Status eines Angebots ändern, sind destructiveHint: true. Die Bestätigung hängt nicht mehr davon ab, dass der MCP-Client diese Annotationen beachtet: Cord führt keine Aktion mit externer Wirkung aus, bevor eine Person sie freigibt (siehe Aktionen, die auf Freigabe warten). Kein Tool stellt Rechnungen aus oder versieht sie mit einem Stempel: Das bleibt eine Aktion, die eine Person in der App oder über die API auslöst.

Kein Tool ändert die Kontoeinstellungen direkt: proponer_configuracion hinterlässt einen Vorschlag, den eine Person mit der Berechtigung „Einstellungen“ in Cord prüft und freigibt, genau wie den Vorschlag aus dem Onboarding oder aus cord setup.

Jedes Tool deklariert ein outputSchema und antwortet zusätzlich zum Text mit structuredContent (dem validierbaren JSON). Beträge werden mit ihrer Währung in moneda übertragen: Gehen Sie nie von Pesos aus.

Paginierung

listar_cotizaciones, buscar_cliente, listar_productos, listar_facturas und listar_eventos geben Seiten zurück, nicht die ganze Tabelle. Es gibt zwei Antwortformen.

buscar_cliente und listar_productos geben die Liste in items zurück, mit total, has_more, next_cursor und der Währung in moneda; listar_cotizaciones gibt total, has_more und next_cursor mit der Liste in cotizaciones zurück, und die Währung steht bei jedem Angebot:

{
  "items": [ { "id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e", "empresa": "Distribuidora El Zarco" } ],
  "total": 47,
  "moneda": "MXN",
  "has_more": true,
  "next_cursor": "20"
}

listar_facturas und listar_eventos geben nur die Liste (in facturas oder eventos) und next_cursor zurück, ohne total und has_more:

{
  "eventos": [ { "id": "6b0e2f4a-8c1d-4e3b-9a5f-7d2c0e8b1a46", "type": "quote.approved" } ],
  "next_cursor": "MjAyNi0wOS0xNFQxODozMjowNC4xMjMwMDBafDZiMGUyZjRhLThjMWQtNGUzYi05YTVmLTdkMmMwZThiMWE0Ng"
}

Rufen Sie in jedem Fall dasselbe Tool erneut mit cursor: next_cursor auf, um die nächste Seite zu erhalten. next_cursor ist null, sobald es keine weiteren Ergebnisse gibt.

Sicher wiederholbare Aufrufe (Idempotenz)

crear_cotizacion_borrador, crear_cliente, crear_tarea, registrar_promesa_pago und die sieben Aktionen mit externer Wirkung akzeptieren eine optionale idempotency_key – eine eindeutige Kennung, die Sie erzeugen (zum Beispiel eine UUID). Muss Ihr MCP-Client den Aufruf wiederholen, weil keine Antwort rechtzeitig kam (Netzwerk-Timeout), wiederholen Sie DIESELBE idempotency_key: Cord liefert das Ergebnis des ersten Aufrufs, statt die Aktion zu wiederholen. Bei einer Aktion mit externer Wirkung liefert derselbe Schlüssel den aktuellen Stand ihrer Anfrage (offen, ausgeführt, abgelehnt…). Derselbe Schlüssel mit anderen Argumenten ergibt einen Fehler, und bei den übrigen Tools läuft der Schlüssel nach 24 Stunden ab.

{
  "name": "crear_cotizacion_borrador",
  "arguments": {
    "idempotency_key": "a1b2c3d4-…",
    "cliente_id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e",
    "items": [{ "descripcion": "Installation", "cantidad": 1, "precio_unitario": 4500 }]
  }
}

Ohne idempotency_key funktioniert das Tool ganz normal – jeder Aufruf erstellt einen neuen Entwurf (das Feld ist keine Pflicht, wird aber empfohlen, wenn Ihr Client automatisch wiederholt).

Sichere Tools

Cord stellt der KI „Tools“ kontrolliert bereit. Die KI hat also keinen rohen, unbegrenzten Zugriff auf Ihre Datenbank; sie kann nur die Endpoints aufrufen, die Cord freigegeben und eingeordnet hat, und übernimmt dabei die Berechtigungen des API-Schlüssels.

Limits, Messung und Aktivität

Jeder echte Aufruf (keine Protokollbenachrichtigungen wie notifications/initialized) zählt genauso wie ein Aufruf der REST-API gegen das Nutzungskontingent Ihres Tarifs. Jede HTTP-Anfrage an den MCP-Server, Benachrichtigungen eingeschlossen, zählt gegen die Minutenlimits der API (600 pro geheimem Schlüssel und 120 pro Quell-IP), und die Tools, die den Status eines Angebots ändern, teilen sich zusätzlich das Limit von 120 pro Minute und Organisation; siehe die Tabelle der Limits. Jeder Aufruf erscheint im Tab Protokolle der Cord Workbench mit dem aufgerufenen Tool (z. B. /mcp/tools/call:listar_productos) – so sehen Sie genau, was Ihr Agent tut, mit welchem Schlüssel und wann. Sie können dieses Protokoll nach Methode oder Status filtern oder in der Route nach mcp suchen, um nur das zu sehen, was die KI getan hat.

Aktionen mit externer Wirkung hinterlassen eine vollständige Spur: Jeder Aufruf erscheint unter Protokolle mit dem Schlüssel, der ihn gemacht hat, die Entscheidung erscheint unter Einstellungen › Audit-Log mit der Person, die freigegeben oder abgelehnt hat, und die ausgeführte Aktion wird als von diesem Schlüssel ausgeführt protokolliert.