MCP & Tool-Integration

Das Model Context Protocol (MCP) ist das Nervensystem agentischer Systeme: Es verbindet LLMs mit Datenbanken, APIs, Dateisystemen und internen Services über ein standardisiertes Tool-Interface. Ohne MCP halluziniert ein Agent Schema-Namen; mit MCP ruft er echte Queries ab. Agenticode in Köln baut MCP-Server und Tool-Integrationen, die in produktiven PHP-Umgebungen sicher und auditierbar laufen.

MCP als Brücke zwischen Agent und Realität

Ein Agent ohne Tools arbeitet nur mit seinem Trainingswissen und dem Editor-Kontext. Sobald er auf Live-Daten, interne APIs oder Legacy-Systeme zugreifen muss, braucht er definierte, versionierte Tools mit klaren Input/Output-Schemas. MCP standardisiert genau diese Schnittstelle: Server exponieren Resources und Tools, Clients (Cursor, Claude Desktop, eigene Orchestratoren) rufen sie auf.

Der Sicherheitsvorteil liegt in der Explizitheit. Jedes Tool hat ein JSON-Schema für Parameter, Berechtigungen und Rate Limits. Der Agent kann nicht „einfach mal“ in die Produktionsdatenbank schreiben – er muss ein registriertes Tool mit Audit-Log nutzen.

Bei Agenticode implementieren wir MCP-Server oft als dünne PHP- oder Node-Wrapper um bestehende Services: Billing-API, CRM-Connector, interne Wissensdatenbank. So bleibt die Domänenlogik in PHP, während der Agent über MCP konsistenten Zugriff erhält.

MCP-Tool-Definition: striktes Input-Schema verhindert Injection.
{
  "name": "billing_get_invoice",
  "description": "Lädt eine Rechnung anhand der ID aus dem Billing-Service",
  "inputSchema": {
    "type": "object",
    "properties": {
      "invoice_id": { "type": "string", "pattern": "^inv_[a-z0-9]{8}$" },
      "include_line_items": { "type": "boolean", "default": true }
    },
    "required": ["invoice_id"]
  }
}

PHP-MCP-Server: Architektur und Patterns

Ein produktionsreifer MCP-Server trennt Transport (stdio, HTTP/SSE), Tool-Registry und Domain-Adapter. Der Adapter spricht Ihre bestehenden Services an – Repositories, HTTP-Clients, Message Queues. Der Agent sieht nur die Tool-Oberfläche.

Wichtig ist Fail-Fast bei Tool-Fehlern: Strukturierte Error-Responses statt Stack Traces an das LLM. Agenticode loggt jeden Tool-Call mit Correlation-ID, damit Debugging und Compliance möglich sind.

Für Multi-Tenant-Systeme setzen wir Tenant-Context als Pflichtparameter jedes Tools. Der Agent kann nicht versehentlich Daten eines anderen Mandanten lesen – das Schema erzwingt tenant_id.

PHP-Tool-Implementierung: Definition und Execute getrennt, Tenant-Pflicht.
<?php

declare(strict_types=1);

namespace App\Mcp\Tools;

use App\Services\Billing\InvoiceLoaderService;

final class BillingGetInvoiceTool
{
    public function __construct(
        private readonly InvoiceLoaderService $loader,
    ) {}

    public function getDefinition(): array
    {
        return [
            'name' => 'billing_get_invoice',
            'description' => 'Lädt Rechnung inkl. Positionen',
            'inputSchema' => [
                'type' => 'object',
                'properties' => [
                    'tenant_id' => ['type' => 'string'],
                    'invoice_id' => ['type' => 'string'],
                ],
                'required' => ['tenant_id', 'invoice_id'],
            ],
        ];
    }

    public function execute(array $input): array
    {
        $invoice = $this->loader->loadForTenant(
            $input['tenant_id'],
            $input['invoice_id']
        );

        return [
            'content' => [
                ['type' => 'text', 'text' => json_encode($invoice->toArray(), JSON_THROW_ON_ERROR)],
            ],
        ];
    }
}

Integration in Cursor und agentische Pipelines

In Cursor konfigurieren wir MCP-Server in mcp.json – typischerweise stdio-basiert für lokale Entwicklung, HTTP für Team-weite Server. Der Agent nutzt Tools automatisch, wenn die Rule-Datei explizit vorschreibt: „Vor jeder Billing-Änderung billing_get_invoice aufrufen“.

In CI-Pipelines können MCP-Tools headless laufen: Ein Orchestrator-Agent ruft deploy_status oder run_smoke_test auf, bevor er den nächsten Loop-Schritt freigibt. Das verbindet MCP mit agentischer CI/CD.

Agenticode liefert aus Köln nicht nur Server-Code, sondern Tool-Kataloge, Berechtigungsmatrizen und Onboarding-Docs für Ihr Team. MCP wird Teil Ihrer Engineering-Plattform – nicht ein Experiment am Rand.

Cursor mcp.json: lokaler stdio-Server plus interner HTTP-MCP.
{
  "mcpServers": {
    "agenticode-billing": {
      "command": "php",
      "args": ["bin/mcp-server.php", "--transport=stdio"],
      "env": {
        "APP_ENV": "development",
        "MCP_AUDIT_LOG": "/var/log/mcp-audit.log"
      }
    },
    "agenticode-deploy": {
      "url": "https://mcp.internal.example.com/deploy",
      "headers": {
        "Authorization": "Bearer ${MCP_DEPLOY_TOKEN}"
      }
    }
  }
}