Integrasi MCP (Model Context Protocol) pada AI Agent PHP

Terakhir diperbarui: 22 Agustus 2026

Konsep Dasar Model Context Protocol (MCP) di PHP

Dalam roadmap belajar ai-agent-php tingkat lanjut, salah satu tantangan terbesar adalah menghubungkan logika agen dengan ekosistem tools eksternal secara modular tanpa mengikat (*hardcoding*) logika database atau API pihak ketiga langsung ke dalam satu file aplikasi.

Model Context Protocol (MCP) diperkenalkan oleh Anthropic sebagai standar industri terbuka (*open standard*) yang memecahkan masalah fragmentasi ini. MCP bertindak layaknya arsitektur Client-Server universal bagi ekosistem AI: MCP Server mengekspos kapabilitas (*tools, resources, prompts*), sedangkan MCP Client (aplikasi PHP Anda) bertindak sebagai jembatan yang menghubungkan instruksi LLM dengan server tersebut.

Diagram Arsitektur Model Context Protocol (MCP) PHP: Dual Transport stdio & SSE

WebP Lossless • 82 KB

Standardisasi Anthropic MCP & Mekanisme Protokol JSON-RPC 2.0

Di balik kesederhanaan antarmukanya, standardisasi Anthropic MCP beroperasi di atas spesifikasi protokol JSON-RPC 2.0 yang teruji, stateless, dan sangat efisien. Dalam spesifikasi MCP resmi, komunikasi pertukaran konteks terbagi ke dalam 3 primitif utama:

• Tools: Fungsi yang dapat dipanggil AI untuk melakukan aksi nyata (contoh: tools/list dan tools/call).
• Resources: Data kontekstual pasif yang dapat dibaca AI (file lokal, schema database, log sistem).
• Prompts: Template instruksi siap pakai yang diekspos oleh server untuk mengarahkan perilaku agent.

Diagram Sekuens: Lifecycle Transport Protokol MCP pada PHP

WebP Lossless • 49 KB • Interactive Sequence

Implementasi Transport MCP PHP: Loop Stream php://stdin & Endpoint SSE Murni

Dua mode transport utama yang digunakan dalam produksi adalah Standard I/O (stdio) untuk eksekusi CLI lokal super cepat dan Server-Sent Events (SSE) untuk integrasi microservices jarak jauh:

1. Loop Stream Transport Standard I/O (php://stdin & php://stdout)

Mode transport ini digunakan ketika aplikasi induk (seperti Claude Desktop atau runner CLI) mengeksekusi skrip PHP sebagai sub-proses. Skrip membaca payload JSON-RPC baris demi baris secara non-blocking:

<?php
// mcp-stdio-server.php

require_once __DIR__ . '/vendor/autoload.php';

use App\MCP\McpServer;
use App\Tools\WeatherTool;

$server = new McpServer();
$server->register('get_weather', new WeatherTool());

// Loop stream stdin: baca input JSON-RPC baris demi baris
$stdin = fopen('php://stdin', 'r');
while (($line = fgets($stdin)) !== false) {
    $line = trim($line);
    if (empty($line)) continue;

    $request = json_decode($line, true);
    $id      = $request['id'] ?? null;
    $method  = $request['method'] ?? '';
    $params  = $request['params'] ?? [];

    $response = ['jsonrpc' => '2.0', 'id' => $id];

    try {
        if ($method === 'tools/list') {
            $response['result'] = ['tools' => $server->listTools()];
        } elseif ($method === 'tools/call') {
            $name   = $params['name'] ?? '';
            $args   = $params['arguments'] ?? [];
            $result = $server->callTool($name, $args);
            $response['result'] = ['content' => [['type' => 'text', 'text' => json_encode($result)]]];
        } else {
            $response['error'] = ['code' => -32601, 'message' => "Method '{$method}' tidak ditemukan."];
        }
    } catch (\Throwable $e) {
        $response['error'] = ['code' => -32000, 'message' => $e->getMessage()];
    }

    // Tulis balasan ke stdout diakhiri newline
    fwrite(STDOUT, json_encode($response, JSON_UNESCAPED_UNICODE) . "\n");
    fflush(STDOUT);
}
fclose($stdin);

One-line Takeaway: php://stdin memungkinkan proses eksekusi langsung dalam milidetik tanpa overhead soket TCP.

2. Endpoint Server-Sent Events (SSE) Murni untuk Remote MCP Server

Jika MCP Server berada di VPS terpisah dan diakses via HTTP, gunakan streaming header text/event-stream native PHP:

<?php
// mcp-sse-endpoint.php (Dijalankan di Nginx / FrankenPHP)

header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');
header('Connection: keep-alive');
header('X-Accel-Buffering: no'); // Nonaktifkan buffer proxy Nginx

// Kirim event endpoint URI untuk inisialisasi sesi MCP
$sessionId = bin2hex(random_bytes(16));
$postUri   = "https://panel.infokoding.com/mcp/messages?session={$sessionId}";

echo "event: endpoint\n";
echo "data: {$postUri}\n\n";
flush();

// Keep-alive heartbeat ping loop
while (true) {
    if (connection_aborted()) break;

    echo ": ping\n\n";
    flush();
    sleep(15);
}

One-line Takeaway: X-Accel-Buffering: no wajib dipasang di Nginx agar event stream tidak tertahan di buffer web server.

Membuat Class McpServer & McpClient di PHP

Berikut adalah implementasi class McpServer dan McpClient terstruktur:

<?php

namespace App\MCP;

use App\Tools\ToolInterface;

class McpServer
{
    private array $tools = [];

    public function register(string $name, ToolInterface $tool): self
    {
        $this->tools[$name] = $tool;
        return $this;
    }

    public function listTools(): array
    {
        $definitions = [];
        foreach ($this->tools as $name => $tool) {
            $def = $tool->getDefinition();
            $definitions[] = $def['function'] ?? $def;
        }
        return $definitions;
    }

    public function callTool(string $name, array $args): mixed
    {
        if (!isset($this->tools[$name])) {
            throw new \InvalidArgumentException("Tool '{$name}' tidak terdaftar.");
        }
        return $this->tools[$name]->execute($args);
    }
}

class McpClient
{
    private McpServer $server;

    public function __construct(McpServer $server)
    {
        $this->server = $server;
    }

    public function getToolDefinitions(): array
    {
        return array_map(fn($tool) => [
            'type'     => 'function',
            'function' => $tool,
        ], $this->server->listTools());
    }

    public function executeToolCall(array $toolCall): array
    {
        $name   = $toolCall['function']['name'];
        $args   = json_decode($toolCall['function']['arguments'], true) ?? [];
        $callId = $toolCall['id'];

        try {
            $result = $this->server->callTool($name, $args);
            return [
                'role'         => 'tool',
                'tool_call_id' => $callId,
                'content'      => json_encode($result, JSON_UNESCAPED_UNICODE),
            ];
        } catch (\Throwable $e) {
            return [
                'role'         => 'tool',
                'tool_call_id' => $callId,
                'content'      => json_encode(['error' => $e->getMessage()], JSON_UNESCAPED_UNICODE),
            ];
        }
    }
}

{
  "mcpServers": {
    "php-weather-server": {
      "command": "php",
      "args": [
        "/home/infokoding/projects/mcp-stdio-server.php"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-api-key-here",
        "APP_ENV": "production"
      }
    },
    "php-remote-sse-server": {
      "url": "https://panel.infokoding.com/mcp-sse-endpoint.php",
      "transport": "sse"
    }
  }
}

FAQ: Pertanyaan Seputar Integrasi Model Context Protocol (MCP) di PHP