MCP Server

Externe MCP-Server stellen Agenten zusätzliche Tools bereit. Die Konfiguration umfasst Streamable HTTP, Authentifizierungsheader, Tool-Filter, Erkennung und Bridge-Routing.

MCP-Server stellen Tools bereit, die Agenten neben lokalen Tools verwenden können. Konfiguriere sie im Agent YAML. Alle MCP-Tool-Aufrufe werden als Traces erfasst und sind in den Run-Details sichtbar. Vergleiche die Rollen von MCP-Server, Verbindung und Client, bevor die zu konfigurierende Seite ausgewählt wird.

Grundlegende Verwendung

version: "1.0"

name: docs-assistant
type: llm
model: connic/kimi-k2.7-code-fast
description: "An assistant with access to library documentation via MCP"
system_prompt: |
  You are a helpful coding assistant with access to up-to-date
  library documentation through MCP tools.

# Connect to an MCP server
mcp_servers:
  - name: context7
    url: https://mcp.context7.com/mcp

Konfigurationsreferenz

mcp_servers:
  - name: github
    url: https://mcp.example.com/github
    headers:
      Authorization: "Bearer ${GITHUB_TOKEN}"
      X-User-Id: "${context.user_id}"

Verwende die Syntax ${VAR_NAME} für Secrets. Konfiguriere Variablen unter Settings → Variables. Für Server, bei denen sich jeder Endnutzer mit seinem eigenen Konto anmelden muss, nutze die Anmeldung pro Nutzer.

Anmeldung pro Nutzer

Manche MCP-Server handeln für eine einzelne Person und akzeptieren nur deren OAuth-Token, ohne gemeinsamen API-Schlüssel. Eine OAuth-App enthält die Einstellungen des Anbieters für eine Umgebung. Jeder Endnutzer meldet sich einmal an, connic speichert seine Tokens, und jeder Run für diesen Nutzer sendet sein aktuelles Access Token an den Server.

1. Registriere beim Anbieter einen OAuth-Client mit der Redirect-URL aus Settings → OAuth Apps.
2. Lege dort die OAuth-App mit Autorisierungs-URL, Token-URL, Client-ID, Client-Secret, Scopes und den Rücksprung-URLs deiner Anwendung an. Ist die Token-URL nur in deinem Netzwerk erreichbar, wähle eine Bridge.
3. Verweise im MCP-Server auf die App und gib den Kontextpfad an, der den Endnutzer identifiziert. Setze diesen Pfad in der Middleware, nachdem du den Nutzer geprüft hast.

mcp_servers:
  - name: sisense
    url: https://bi.example.com/mcp
    oauth:
      app: sisense            # OAuth-App unter Settings → OAuth Apps
      user: context.user_id   # setzt die Middleware in jedem Run
      connect_tool: true      # fügt connect_sisense für Konversationsagenten hinzu

Nutzer verbinden

Aus deiner Anwendung: Erstelle einen Anmeldelink über die REST API, zum Beispiel hinter einem Verbinden-Button in deinen Einstellungen. Verwende dieselbe Nutzer-ID, die deine Middleware setzt. Der Nutzer meldet sich beim Anbieter an und kehrt zu return_url zurück, mit connic_oauth=connected, denied oder failed in der Query. Über dieselbe API listest du verbundene Nutzer und trennst sie.

curl -X POST "https://api.connic.co/v1/projects/{project_id}/oauth-apps/{app_id}/connect-links" \
  -H "Authorization: Bearer cnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "emp_42", "return_url": "https://app.example.com/settings/integrations"}'

# {"url": "https://api.connic.co/v1/oauth/start/...", "expires_at": "2026-10-12T10:10:00Z"}

Aus einer Unterhaltung: Mit connect_tool: true erhält ein Nutzer ohne Token statt der Tools des Servers ein Tool connect_<Servername>. Der Agent teilt den gelieferten Link, und nach der Anmeldung kann die nächste Nachricht des Nutzers den Server verwenden. Sprachagenten stellen dieses Tool nicht bereit. Lass es bei Agenten aus, die ohne eine Person laufen, die den Link öffnen könnte. Sie nutzen die Tokens von Nutzern, die sich bereits angemeldet haben.

Zur Laufzeit

• Ein Run ohne Wert im Pfad user oder für einen Nutzer, der sich nicht angemeldet hat, lässt den Server weg.
• Tokens, die innerhalb von fünf Minuten ablaufen, werden vorher erneuert, wenn der Anbieter ein Refresh Token ausgestellt hat.
• Antwortet der Server mit 401, erneuert connic das Token einmal und wiederholt den Aufruf. Ohne Refresh Token wird das gespeicherte Token gelöscht, und der Nutzer meldet sich erneut an.
• Anmeldelinks funktionieren einmal und laufen nach 10 Minuten ab.
• Das Deployment schlägt fehl, wenn eine referenzierte OAuth-App in der Umgebung nicht existiert.
• connic erkennt Autorisierungsserver nicht automatisch und registriert keine Clients. Registriere den Client zuerst beim Anbieter.

Bedingte und optionale Server

Zugangsdaten pro Nutzer gibt es oft nur für einen Teil der Nutzer. Mit condition wird ein Server nur verbunden, wenn ein Ausdruck wahr ist. Er wird zu Beginn jedes Runs nach der Middleware ausgewertet und nutzt dieselbe Syntax wie bedingte Tools. Ist er falsch oder verweist er auf einen fehlenden Schlüssel, bleiben der Server und seine Tools in diesem Run außen vor, und seine ${context.*}-Header werden nicht aufgelöst.

mcp_servers:
  - name: analytics
    url: https://analytics.example.com/mcp
    headers:
      Authorization: "Bearer ${context.analytics_token}"
    condition: context.analytics_token != null
    optional: true

tools:
  - analytics.get_connect_link: context.analytics_token == null

Mit optional: true läuft der Run weiter, wenn die Verbindung zum Server oder das Abrufen seiner Tools fehlschlägt, etwa mit einem 401, weil ein gespeichertes Token widerrufen wurde. Ohne diese Einstellung schlägt der Run in diesem Fall fehl.

connic erfasst MCP-Fehler in context["mcp_errors"], geordnet nach Servername. stage ist discovery oder call, und status ist 401, wenn der Server die Zugangsdaten abgelehnt hat. Lies den Wert im after-Hook der Middleware, um widerrufene Zugangsdaten zu entfernen, damit der nächste Run den Weg zur erneuten Verbindung anbietet.

async def after(response, context):
    if context.get("mcp_errors", {}).get("analytics", {}).get("status") == 401:
        await delete_analytics_token(context["user_id"])
    return response

mcp_servers:
  - name: filesystem
    url: https://mcp.example.com/filesystem
    # Only allow specific tools
    tools:
      - read_file
      - list_directory

Beschränke die verfügbaren Tools, um Agenten auf schreibgeschützte Operationen zu begrenzen oder die Verwendung gefährlicher Tools zu verhindern.

Mehrere Server

mcp_servers:
  - name: docs
    url: https://mcp.context7.com/mcp

  - name: search
    url: https://mcp.example.com/search
    headers:
      X-API-Key: "${SEARCH_API_KEY}"

  - name: database
    url: https://mcp.internal.company.com/db
    headers:
      Authorization: "Bearer ${DB_TOKEN}"
    tools:
      - query
      - list_tables

Verbinde mehrere MCP-Server gleichzeitig. Die Tools jedes Servers werden für den Agenten verfügbar.

Läuft ein MCP-Server in einem privaten Netzwerk – etwa in einer VPC, On-Premises oder hinter einer Unternehmensfirewall – und ist nicht aus dem öffentlichen Internet erreichbar, setze das Feld bridge auf die ID einer connic Bridge. connic routet die MCP-Verbindung durch diese Bridge.

mcp_servers:
  - name: internal-mcp
    url: http://mcp.internal:8080/mcp
    bridge: ${INTERNAL_BRIDGE_ID}

url ist die Adresse, die die Bridge aus dem privaten Netzwerk sieht. Typischerweise ist das ein Hostname, der nur dort aufgelöst wird, zum Beispiel mcp.internal:8080. Kopiere die Bridge-ID aus Projekt-Settings > Bridge. Sowohl URL als auch Bridge-ID unterstützen die Ersetzung mit ${VAR}. So bleiben sie außerhalb der YAML-Datei und lassen sich als Variablen speichern.

Ist für den Bridge-Agenten ALLOWED_HOSTS konfiguriert, muss die Liste Host und Port des MCP-Servers enthalten. Ist die Variable nicht gesetzt oder leer, ist jedes Ziel erlaubt, das aus dem Netzwerk der Bridge erreichbar ist.

Auffindbare MCP Server

Manche MCP-Server stellen sehr viele Tools bereit. Werden alle davon in den LLM-Kontext geladen, steigt der Token-Verbrauch und die Genauigkeit kann sinken. Mit discoverable: true werden die Tools des Servers zunächst nicht in den LLM-Kontext geladen und werden stattdessen für die bedarfsgesteuerte Suche indexiert.

Ist ein MCP-Server als discoverable markiert, indexiert connic seine Tools und lässt den Agenten sie bei Bedarf mit einer natürlichsprachlichen Anfrage finden und aufrufen. Nur die passenden Tools werden geladen, sodass der LLM-Kontext schlank bleibt.

version: "1.0"

name: research-agent
type: llm
model: connic/gpt-5.6-sol
description: "Agent with a large MCP toolset available on demand"
system_prompt: |
  You have access to many research tools. When you need one,
  search for it by describing what you need.

mcp_servers:
  - name: research-hub
    url: https://mcp.example.com/research
    discoverable: true   # all tools indexed for search, not loaded upfront
    headers:
      Authorization: "Bearer ${RESEARCH_TOKEN}"

Fehlerbehandlung