AI 외부 연동 : PHP MCP 구현과 API 연동

Step 1. PHP MCP 개발 환경 준비

PHP를 이용해 MCP를 구현하기 위해서는 개발에 필요한 패키지를 설치해 주어야 한다. PHP에도 데비안 리눅스의 APT와 유사한 패키지 관리 도구가 있는데, 바로 Composer라는 놈이다. 우선 Composer를 설치하고 MCP 패키지를 설치해 준다.

1. PHP Composer 설치

   apt-get을 이용해 Composer를 설치한다. 본 필자의 경우, 설치는 정상적으로 진행되었지만 기본 CLI PHP로 Composer를 실행하자 Composer와 관련 라이브러리에서 Deprecated 경고가 발생했다. 이후 작업은 PHP 8.3을 기준으로 진행하기로 결정하고, PHP 8.3을 명시해 다시 실행하니 경고 없이 버전 정보가 출력되었다.

   debian@eqmaker:~$ sudo apt-get install composer
   Reading package lists... Done
   Building dependency tree... Done
   (... 중략 ...)
   
   debian@eqmaker:~$ composer --version
   PHP Deprecated:  Composer\Pcre\Preg::replace(): Implicitly marking parameter $count as nullable is deprecated, the explicit nullable type must be used instead in /usr/share/php/Composer/Pcre/Preg.php on line 150
   Deprecated: Composer\Pcre\Preg::replace(): Implicitly marking parameter $count as nullable is deprecated, the explicit nullable type must be used instead in /usr/share/php/Composer/Pcre/Preg.php on line 150
   PHP Deprecated:  Composer\Pcre\Preg::replaceCallback(): Implicitly marking parameter $count as nullable is deprecated, the explicit nullable type must be used instead in /usr/share/php/Composer/Pcre/Preg.php on line 177
   Deprecated: Composer\Pcre\Preg::replaceCallback(): Implicitly marking parameter $count as nullable is deprecated, the explicit nullable type must be used instead in /usr/share/php/Composer/Pcre/Preg.php on line 177
   (... 중략 ...)
   Deprecation Notice: Constant E_STRICT is deprecated in /usr/share/php/Composer/Util/Silencer.php:36
   Composer version 2.5.5 2023-03-21 11:50:05
   
   debian@eqmaker:~$ /usr/bin/php8.3 /usr/bin/composer --version
   Composer version 2.5.5 2023-03-21 11:50:05

2. PHP MCP SDK 설치

   MCP 서버를 구현할 프로젝트 디렉토리를 생성하고 권한을 준 다음, Composer를 이용해 PHP MCP SDK를 설치한다. /opt 아래에 stdtbank-mcp디렉토리를 만들어 사용했다.

   PHP 8.3으로 Composer를 실행해 당시 최신 버전인 mcp/sdk 0.8.1로 지정했다. (설치하고 5일 만에 0.9.0 업데이트가 나왔다.;;)

   설치 중에는 의존 패키지인 php-http/discovery의 실행 여부를 확인한다.

   debian@eqmaker:~$ sudo mkdir -p /opt/stdtbank-mcp
   debian@eqmaker:~$ sudo chown debian /opt/stdtbank-mcp
   debian@eqmaker:~$ sudo chmod 750 /opt/stdtbank-mcp
   debian@eqmaker:~$ cd /opt/stdtbank-mcp
   debian@eqmaker:/opt/stdtbank-mcp$ /usr/bin/php8.3 /usr/bin/composer require mcp/sdk:0.8.1
   ./composer.json has been created
   Running composer update mcp/sdk
   Loading composer repositories with package information
   Updating dependencies
   Lock file operations: 23 installs, 0 updates, 0 removals
   Locking doctrine/deprecations (1.1.6)
   Locking mcp/sdk (v0.8.1)
   (... 중략 ...)
   Downloading mcp/sdk (v0.8.1)
   php-http/discovery contains a Composer plugin which is currently not in your allow-plugins config. See https://getcomposer.org/allow-plugins
   Do you trust "php-http/discovery" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?] y
   (... 중략 ...)
   3 packages you are using are looking for funding.
   Use the composer fund command to find out more!
   No security vulnerability advisories found

3. PHP MCP SDK 설치 결과 검증

   설치된 PHP MCP SDK의 버전과 설치 경로, 의존성 패키지 정상 여부, 보안 감사 결과를 확인한다.

   debian@eqmaker:/opt/stdtbank-mcp$ /usr/bin/php8.3 /usr/bin/composer show mcp/sdk
   name     : mcp/sdk
   (... 중략 ...)
   versions : * v0.8.1
   (... 중략 ...)
   path     : /opt/stdtbank-mcp/vendor/mcp/sdk
   names    : mcp/sdk
   (... 중략 ...)
   suggests
   symfony/finder Required for file-based discovery.
   debian@eqmaker:/opt/stdtbank-mcp$ /usr/bin/php8.3 /usr/bin/composer check-platform-reqs
   Checking platform requirements for packages in the vendor dir
   composer-plugin-api 2.3.0    success
   (... 중략 ...)
   debian@eqmaker:/opt/stdtbank-mcp$ /usr/bin/php8.3 /usr/bin/composer audit
   No security vulnerability advisories found
   

Step 2. PHP-FPM을 이용한 MCP 실행 환경 분리

MCP 실행을 위한 별도의 로컬 계정을 만들어 권한을 분리한다. 이를 위해 PHP 실행 프로세스를 관리하는 서비스인 PHP-FPM을 설치하고 MCP가 사용할 풀(Pool)을 구성한다.

1. PHP-FPM 설치

   본 필자는 설치 과정 중 Sury PGP 키 관련 에러가 발생해 키 업데이트를 진행해야만 했다.

   sudo apt-get install php8.3-fpm

   (...전략...)
   Created symlink /etc/systemd/system/multi-user.target.wants/php8.3-fpm.service → /lib/systemd/system/php8.3-fpm.service.
   Setting up php8.3 (8.3.35-1+0~20260925.87+debian12~1.gbp19383d) ...
   (... 중략 ...)
   Processing triggers for php8.3-fpm (8.3.35-1+0~20260925.87+debian12~1.gbp19383d) ...
   NOTICE: Not enabling PHP 8.3 FPM by default.

   설치를 완료하고 PHP-FPM 서비스가 동작하고 있나 확인한다. 이어서, 아파치에서 사용하는 모듈에 변경이 없었는지도 함께 확인한다.

   debian@eqmaker:~$ sudo systemctl status php8.3-fpm
   ● php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager
        Loaded: loaded (/lib/systemd/system/php8.3-fpm.service; enabled; preset: enabled)
        Active: active (running) (... 중략 ...)
   	 debian@eqmaker:~$ sudo apache2ctl -M 2>/dev/null | grep -Ei 'mpm|php|proxy_fcgi'
    mpm_prefork_module (shared)
    php_module (shared)

2. MCP 전용 계정 생성과 권한 부여 : MCP 서버를 실행할 리눅스 계정을 생성하고 위에서 생성한 프로젝트 디렉토리에 대한 실행 권한을 부여한다.
3. MCP 전용 PHP-FPM 풀 구성

   코드를 실행할 FPM 풀을 구성했다. 풀 이름은 계정과 동일한 mcpman으로 정하고, 아파치가 연결할 소켓도 /run/php/mcpman.sock으로 분리했다.

   /etc/php/8.3/fpm/pool.d/에 새로운 풀의 설정 파일을 생성한 후 PHP-FPM을 재시작해 적용시켜 준다.

   [mcpman]
   user = mcpman
   group = mcpman
   listen = /run/php/mcpman.sock
   listen.owner = www-data
   listen.group = www-data
   listen.mode = 0660
   pm = ondemand
   pm.max_children = 3
   pm.process_idle_timeout = 30s
   pm.max_requests = 200
   security.limit_extensions = .php
   php_admin_flag[display_errors] = off
   php_admin_flag[log_errors] = on
   php_admin_value[error_log] = /var/log/php8.3-fpm.log
   php_admin_value[session.save_path] = /var/lib/php/sessions

   전용 소켓이 생성되었는지 확인하고 소켓과 라이브러리, 프로젝트 설정 파일에 대해 계정 접근 권한을 확인한다.

   debian@eqmaker:~$ ls -l /run/php/mcpman.sock
   srw-rw---- 1 www-data www-data 0 Oct 13 10:59 /run/php/mcpman.sock
   debian@eqmaker:~$ sudo -u www-data test -w /run/php/mcpman.sock && echo 'O' || echo 'X'
   O
   debian@eqmaker:~$ sudo -u mcpman test -r /opt/stdtbank-mcp/vendor/autoload.php && echo 'O' || echo 'X'
   O
   debian@eqmaker:~$ sudo -u mcpman test -w /opt/stdtbank-mcp/composer.json && echo 'O' || echo 'X'
   X

Step 3. MCP 인터페이스 구현

이제 MCP 인터페이스를 구현한다. 먼저 STDIO를 이용해 연동 상태를 확인한 후, 로컬 호스트에서 Streamable HTTP로 연동되는지 확인한다. 기능별 역할을 구분하기 위해 API 호출, MCP 서버 구성, 실행 진입점을 각각 별도의 파일로 나누고 curl을 이용해 요청을 보낸다.

• ServerFactory.php : MCP 서버와 도구 정의

  build()는 MCP 서버의 기본 정보와 도구를 등록하고 서버 객체를 반환한다. 다음은 엔티티 상세 조회 도구를 중심으로 발췌한 코드이다.

  public static function build(RestClient $api, ?string $sessionDirectory = null): Server
  {
      // MCP 서버의 이름과 버전을 설정한다.
      $builder = Server::builder()
          ->setServerInfo('STDTBank Read-Only', '0.1.0')
  
          ->addTool(
              // 도구가 호출되면 REST 클라이언트의 상세 조회를 실행한다.
              handler: static fn (int $id): array => $api->entityDetails($id),
  
              // 도구 이름
              name: 'get_entity_details',
  
              // 도구 설명, 한글로 입력하는 것도 가능
              description: 'Read one existing STDTBank entity by positive integer ID.',
  
              // 필수 입력값, id는 1 이상의 정수
              inputSchema: ['type' => 'object',
  							'properties' => [
  							'id' => ['type' => 'integer',
  										'minimum' => 1,],],
  							'required' => ['id'],
  							'additionalProperties' => false,],);
  
      // HTTP 요청 사이에 사용할 파일 기반 세션 저장소
      if ($sessionDirectory !== null) {
          $builder->setSession(new FileSessionStore($sessionDirectory));
      }
      return $builder->build();
  }

• server-http-local.php : HTTP 요청 접수와 MCP 응답 전달

  fromGlobals()를 이용해 PHP가 받은 HTTP 요청을 SDK에 전달할 수 있는 PSR-7 요청 객체로 변환한다.

  // HTTP 메시지 객체를 생성할 팩토리를 준비한다.
  $factory = new Psr17Factory();
  
  // PSR-7 처리
  $request = (new ServerRequestCreator($factory, $factory, $factory, $factory))->fromGlobals();
  
  // 워드프레스 REST API 호출 객체
  $api = new RestClient(getenv('STDT_REST_BASE_URL') ?: 'https://www.eqmaker.kr', $username, $password);
  
  // 도구가 등록된 MCP 서버를 생성
  $server = ServerFactory::build($api, $sessionDirectory);
  
  // HTTP 요청을 처리할 객체
  $transport = new StreamableHttpTransport($request);
  
  // SDK의 결과를 HTTP 응답 객체로 반환
  $response = $server->run($transport);
  
  // 완성된 HTTP 응답을 클라이언트에 전송한다.
  (new SapiEmitter())->emit($response);

• RestClient.php : 워드프레스 REST API 호출

  public function entityDetails(int $id): array	//	엔티티 ID 검사 상세 조회 경로 구성
  {
      // 유효하지 않은 ID는 API 요청 전에 거부한다.
      if ($id < 1) {
          throw new RuntimeException('Entity ID must be a positive integer.');
      }
  
      // 예를 들어 ID 453이면 entities/453을 조회한다.
      return $this->get('entities/' . $id);
  }

  private function get(string $path, array $query = []): array	//	HTTPS GET 인증, API의 JSON을 PHP 배열로 도구 실행 함수에 반환
  {
      // REST API 기본 주소와 요청 경로
      $base = rtrim($this->baseUrl, '/');
      $url = $base . '/wp-json/eqstdt/v1/' . $path;
  
      // 검색어 등 쿼리 매개변수가 있으면 URL에 추가한다.
      if ($query !== []) {
          $url .= '?' . http_build_query(
              $query, '', '&', PHP_QUERY_RFC3986
          );
      }
  
      $ch = curl_init($url);
      if ($ch === false) {
          throw new RuntimeException('Unable to initialize HTTP request.');
      }
  
      // GET 요청, 워드프레스 인증정보
      curl_setopt_array($ch, [
          CURLOPT_HTTPGET => true,
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
          CURLOPT_USERPWD => $this->username . ':' . $this->applicationPassword,
          CURLOPT_HTTPHEADER => ['Accept: application/json'],
          CURLOPT_CONNECTTIMEOUT => 5,
          CURLOPT_TIMEOUT => 15,
          CURLOPT_SSL_VERIFYPEER => true,
          CURLOPT_SSL_VERIFYHOST => 2,
          CURLOPT_FOLLOWLOCATION => false,
          CURLOPT_MAXREDIRS => 0,
          CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
          CURLOPT_MAXFILESIZE => 2 * 1024 * 1024,
      ]);
  
      try {
          // 요청 보내고 응답 상태 코드 확인
          $body = curl_exec($ch);
          $status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
  
          if (!is_string($body)) {throw new RuntimeException('REST API connection failed.');}
          if (strlen($body) > 2 * 1024 * 1024) {throw new RuntimeException('REST API response exceeds size limit.');}
          if ($status !== 200) {throw new RuntimeException('REST API returned HTTP ' . $status . '.');}
  
          // JSON 응답 PHP 배열 변환
          $data = json_decode($body, true, 64, JSON_THROW_ON_ERROR);
          if (!is_array($data)) { throw new RuntimeException('REST API returned a non-object JSON response.'); }
  
          return $data;
  		}
  		
  		catch (\JsonException $e) {throw new RuntimeException('REST API returned invalid JSON.', 0, $e);}
  		finally {curl_close($ch);}	//	CURL 정리
  }

클라이언트의 MCP 요청은 server-http-local.php를 통해 SDK에 전달된다. SDK는 ServerFactory.php의 도구 실행 함수를 호출하고, RestClient.php는 워드프레스 REST API를 통해 데이터를 조회한다. 반환된 PHP 배열은 SDK에서 MCP 응답으로 구성되며, HTTP 진입점에서 클라이언트로 전송된다.

Step 4. 로컬 HTTP 환경에서 MCP 동작 검증

구현한 MCP 인터페이스가 실제로 동작하는지 확인한다. PHP 내장 웹 서버를 로컬 주소에서 실행하고, 다른 터미널에서 curl로 요청을 보낸다. MCP 인터페이스와 REST API의 연동을 확인하는 과정이다. 세션 디렉토리는 프로젝트 디렉토리의 /var/sessions를 사용한다.

1. 로컬 HTTP 서버 실행

   debian@eqmaker:/opt/stdtbank-mcp$ sudo -u mcpman env STDT_MCP_LOCAL_TEST=1 STDT_MCP_SESSION_DIR=/opt/stdtbank-mcp/var/sessions STDT_REST_USERNAME=test-user STDT_REST_APPLICATION_PASSWORD=test-password /usr/bin/php8.3 -S 127.0.0.1:8765 server-http-local.php
   PHP 8.3.35 Development Server (http://127.0.0.1:8765) started
   127.0.0.1:45506 Accepted
   127.0.0.1:45506 Closing

2. 초기화 요청 전송

   새로운 콘솔 세션에서 로컬 HTTP 서버를 향해 초기화 요청을 전송한다. HTTP 200과 함께 MCP의 세션 ID와 문자열이 돌아와야 한다.

   debian@eqmaker:~$ curl -sS -i http://127.0.0.1:8765/ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"mcp-http-test","version":"1.0"}}}'
   HTTP/1.1 200 OK
   (... 중략 ...)
   Mcp-Session-Id: abcdefgh-ijkl-mnop-qrst-uvwxyz123456
   Access-Control-Expose-Headers: Mcp-Session-Id
   (...  중략 ...)
   {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26", (... 중략...) via API Tester."}}

3. 초기화 완료 알림 전송

   초기화가 완료되었다는 알림을 전송한다. 이후 요청에는 앞에서 반환받은 세션 ID를 사용한다.

   debian@eqmaker:~$ curl -sS -i http://127.0.0.1:8765/ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-03-26' -H 'Mcp-Session-Id: abcdefgh-ijkl-mnop-qrst-uvwxyz123456' -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
   HTTP/1.1 202 Accepted
   (... 중략 ...)

4. 등록된 도구 목록 요청

   같은 세션에서 tools/list를 요청한다.

   debian@eqmaker:~$ curl -sS -i http://127.0.0.1:8765/ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-03-26' -H 'Mcp-Session-Id: abcdefgh-ijkl-mnop-qrst-uvwxyz123456' -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
   HTTP/1.1 200 OK
   (... 중략 ...)
   Mcp-Session-Id: abcdefgh-ijkl-mnop-qrst-uvwxyz123456
   (... 중략 ...)
   {
     "jsonrpc": "2.0",
     "id": 2,
     "result": {
       "tools": [
         (... 중략 ...)
         {
           "name": "get_entity_details",
           "inputSchema": {
             "type": "object",
             "properties": {
               "id": {
                 "type": "integer",
                 "minimum": 1
               }
             },
             "required": ["id"],
             "additionalProperties": false
           },
           "description": "Read one existing STDTBank entity by positive integer ID."
         }
       ]
     }
   }

Step 5. 실제 데이터베이스의 내용 조회

로컬 HTTP 서버를 실제 워드프레스의 암호를 이용해 재실행하고 실제 데이터베이스에 등록된 내용을 조회한다. ID 453번 FFmpeg에 대한 엔티티 정보를 조회해 보았다.

debian@eqmaker:~$ curl -sS -i http://127.0.0.1:8765/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  -H 'Mcp-Session-Id: eqmakerd-ecte-ngeq-make-reqmakerdect' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_entity_details","arguments":{"id":453}}}'
HTTP/1.1 200 OK
Host: 127.0.0.1:8765
(...중략...)
Mcp-Session-Id: eqmakerd-ecte-ngeq-make-reqmakerdect
Access-Control-Expose-Headers: Mcp-Session-Id

{"jsonrpc":"2.0","id":3,"result":{"content":[ (... 실제 DB 내용 생략 ... ) ],"isError":false,"structuredContent":{ (...실제 DB 내용 생략 ...) }}}

응답 본문에서는 isError: false와 함께 FFmpeg의 상세 정보가 반환되었다.