Skip to main content

MCP

SessionConfig의 mcpServers에 MCP 서버를 지정하면 사용할 수 있습니다. Copilot CLI에서 Laravel Boost를 사용하는 경우 laravel-boost-copilot-cli도 함께 사용해 주세요. 'type' => 'stdio'(또는 'local')와 'tools' => ['*']가 필수라는 것이 확인되었습니다. 이것이 없으면 MCP 서버로 인식되지 않습니다. args는 선택 사항입니다.

MCP Apps(실험적 기능)

enableMcpApps를 활성화한 세션에서는 $session->rpc()->mcp()->apps()로 MCP Apps의 도구와 리소스를 다룰 수 있습니다. listTools()는 앱에서 호출할 수 있는 도구를 반환하고, callTool()은 도구를 실행하며, readResource()는 HTML 등의 ui:// 리소스를 가져옵니다. listTools()와 callTool()에는 호출 측 서버를 나타내는 originServerName이 필요합니다. getHostContext()와 setHostContext()로 테마나 로케일 같은 호스트 컨텍스트를 읽고 쓸 수 있습니다. diagnose()는 서버의 MCP Apps 지원 상태를 반환합니다.
callTool()은 자유 형식의 MCP 결과를 반환합니다. SDK는 데이터를 가져오고 설정하기 위한 RPC를 제공하지만, 가져온 HTML의 렌더링이나 iframe 관리는 하지 않습니다. 렌더링은 Livewire나 Inertia 등을 사용해 애플리케이션 쪽에서 구현해 주세요.

호스트에서 MCP OAuth 토큰 제공하기

MCP 서버가 OAuth 인증을 요구하는 경우 onMcpAuthRequest로 애플리케이션에서 인증을 처리할 수 있습니다. 콜백은 McpAuthRequest와 sessionId를 포함하는 컨텍스트 배열을 받습니다. McpAuthToken을 반환하면 토큰이 CLI 런타임에 전달됩니다. null 또는 kind: 'cancelled'인 McpAuthResult를 반환하면 인증이 취소됩니다.
McpAuthRequest에는 requestId, serverName, serverUrl, reason(initial, refresh, reauth, upscope)이 포함됩니다. 핸들러를 지정하면 SDK가 mcp.oauth_required 이벤트를 자동으로 구독합니다. 따라서 웹 요청, 큐, 배치처럼 브라우저를 열 수 없는 환경에서도 인증할 수 있습니다. 세션을 재개할 때도 ResumeSessionConfig에 같은 핸들러를 지정하세요.

MCP OAuth 지원 확인(Server RPC)

원격 MCP 서버가 OAuth 인증을 요청한 후, Server RPC로 Dynamic Client Registration(DCR) 지원 여부를 확인할 수 있습니다. authorizationServerUrl은 메타데이터에서 인가 서버를 발견할 수 있는 경우에 반환됩니다. supportsDcr가 false이면 동적 등록을 사용할 수 없습니다.
resourceMetadataText는 WWW-Authenticate 챌린지에서 얻은 보호 리소스 메타데이터입니다. 생략하면 서버 URL에서 인가 서버를 탐색합니다. sessionId를 지정하면 해당 로컬 세션의 대상 정책과 sandbox proxy가 적용됩니다. Microsoft Entra ID는 DCR을 지원하지 않습니다. 인가 서버가 Microsoft인 경우에는 사용자에게 클라이언트 자격 증명을 요구하는 대신 사전 등록된 클라이언트를 사용할 수 있습니다. 이들은 Server RPC(Copilot::client()->rpc())입니다. 로그인과 OAuth 요청을 처리하는 세션 RPC $session->rpc()->mcp()->oauth()와는 별개의 네임스페이스입니다.

MCP 서버의 상태

세션 내 MCP 서버의 상태는 다음 값을 가집니다. $session->rpc()->mcp()->listConfigured()가 반환하는 각 서버에는 실행 중에 관측된 상태가 live로 포함될 수 있습니다. McpConfiguredServerState::fromArray($server['live'])로 타입이 지정된 객체로 변환할 수 있습니다. McpConfiguredServerState의 선택적 bool 값인 toolsLoaded는 현재 연결에서 도구 목록이 로드되었는지를 나타냅니다. 런타임이 보고하지 않은 경우 toolsLoaded는 null이므로, 값이 없는 것을 false로 취급하지 마세요.
connected 상태만으로는 도구가 로드되었다는 의미가 아닙니다. 서버의 도구 목록을 사용할 수 있게 되는 시점은 session.mcp_server_tools_loaded 이벤트로 확인하세요. 이 임시(ephemeral) 이벤트는 연결마다 한 번 data.serverName과 data.toolCount와 함께 발생하며, 영구 저장되지 않습니다. 캐시된 도구를 사용하는 경우 connected보다 먼저 도착할 수 있습니다.

MCP 서버 설정 관리(Server RPC)

세션과 별개로, 서버 레벨에서 MCP 서버의 설정을 관리할 수 있습니다.

MCP 재로드 시 비활성화된 서버

reloadWithConfig()에 설정을 전달할 때 configuredDisabledServers는 애플리케이션에서 해석한 설정에 의해 비활성화된 서버 목록입니다. 세션 단위의 disabledServers나 CLI의 cliEnabledServers와는 별도로 지정하세요. 설정에 의한 비활성화는 CLI에 의한 활성화와 명시적인 세션 비활성화보다 우선순위가 낮으므로, configuredDisabledServers를 disabledServers에 합치지 마세요.
최신 정보는 GitHub 저장소를 참고하세요.
마지막 수정일 2026년 10월 19일