> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# Laravel AI 에이전트가 MCP 서버 지원
> Laravel AI SDK와 Laravel MCP에 추가된 MCP 클라이언트 기능을 설명합니다. 에이전트의 tools()에 MCP 서버의 도구를 그대로 통합할 수 있게 되었습니다.
## 개요
2026년 6월, [Laravel 공식 블로그](https://laravel.com/blog/laravel-ai-agents-now-support-mcp-servers)에서 Laravel AI SDK로 구축한 AI 에이전트가 **MCP(Model Context Protocol) 서버**에 연결할 수 있게 되었다고 발표했습니다.
지금까지 Laravel MCP는 "Laravel 앱을 **MCP 서버로서**" 공개하는 기능을 제공했지만, 이번에 추가된 것은 그 반대 방향, 즉 "Laravel 앱이 **MCP 클라이언트로서** 다른 MCP 서버에 연결하는" 기능입니다.
MCP 자체의 자세한 구조는 [Laravel MCP 문서](https://laravel.com/docs/mcp)를 참조하세요. 이 페이지에서는 클라이언트 기능에 좁혀 설명합니다.
## 왜 AI SDK 본체가 아닌 Laravel MCP에 구현되었는가
MCP는 전송 계층 협상, 핸드셰이크, 인증 흐름 등 다루는 범위가 넓은 프로토콜입니다. 이를 AI SDK 내에 직접 구현하면, 에이전트 없이 MCP 서버와 통신하고 싶은 상황(큐 잡이나 콘솔 명령 등)에서 재사용할 수 없습니다.
그래서 Laravel 팀은 기능을 두 가지로 나누었습니다.
```mermaid theme={null}
graph LR
A["laravel/mcp
MCP 클라이언트"] --> B["연결·인증·핸드셰이크"]
C["laravel/ai
얇은 통합 계층"] --> D["에이전트의 tools()에
MCP 도구를 그대로 추가"]
A --> C
```
* **`laravel/mcp`**: 연결·협상·인증·도구 호출을 담당하는 MCP 클라이언트 본체
* **`laravel/ai`**: 에이전트가 그 클라이언트를 `tools()`에서 위화감 없이 사용할 수 있게 하는 얇은 통합 계층
각각 단독으로도 사용할 수 있으며, 조합하면 에이전트에서 MCP 서버의 도구를 직접 작성한 도구와 동일하게 다룰 수 있습니다.
## MCP 서버로 연결
로컬 프로세스로 시작하는 STDIO 서버와 HTTP 경유의 원격 서버 양쪽을 지원합니다.
```php theme={null}
use Laravel\Mcp\Client;
// 로컬 서버 (STDIO)
$client = Client::local('npx', ['-y', '@modelcontextprotocol/puppeteer']);
$tools = $client->tools();
// 원격 서버 (Streamable HTTP)
$client = Client::web('https://nightwatch.laravel.com/mcp');
$tools = $client->tools();
```
연결, 핸드셰이크, 프로토콜 버전 협상은 모두 클라이언트가 처리하므로 앱 측은 `tools()`를 호출하기만 하면 됩니다.
## 인증
### Bearer 토큰
```php theme={null}
$tools = Client::web('https://mcp.example.com')
->withToken($token)
->tools();
```
### OAuth
Nightwatch 등 많은 호스팅 MCP 서버는 OAuth를 요구합니다. 서비스 프로바이더에서 이름 있는 클라이언트를 등록합니다.
```php theme={null}
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;
Mcp::registerClient('nightwatch', fn () =>
Client::web('https://nightwatch.laravel.com/mcp')->withOAuth()
);
```
OAuth 라우트와 콜백 처리를 연결합니다.
```php theme={null}
use Laravel\Mcp\Facades\Mcp;
use Laravel\Mcp\Client\OAuth\TokenSet;
Mcp::oAuthRoutesFor('nightwatch', function (string $provider, TokenSet $token) {
auth()->user()->update([
'mcp_nightwatch_token' => encrypt($token->accessToken),
'mcp_nightwatch_refresh' => encrypt($token->refreshToken),
]);
return redirect('/dashboard');
}, middleware: 'auth');
```
이로써 `mcp.oauth.nightwatch.connect`와 이에 대응하는 콜백 라우트가 생성됩니다. Blade 측에서는 연결 버튼을 놓기만 하면 됩니다.
```blade theme={null}
Connect Nightwatch
```
사용자가 로그인해서 승인하면 콜백 클로저가 토큰을 받습니다. 리다이렉트 URL이나 PKCE의 상세 내용을 스스로 다룰 필요가 없습니다.
사용자 개입이 없는 백그라운드 처리용으로 클라이언트 자격 증명 부여도 준비되어 있습니다.
```php theme={null}
$token = Mcp::client('billing')->oAuthClient()->clientCredentials();
```
## 에이전트에 통합
가장 중요한 포인트는 에이전트의 `tools()` 메서드를 변경하지 않고도 MCP 도구를 섞을 수 있다는 것입니다.
```php theme={null}
use Laravel\Mcp\Facades\Mcp;
use App\Tools\SendSlackMessage;
class SupportAgent extends Agent
{
public function instructions(): string
{
return 'You help triage production issues.';
}
public function tools(): array
{
return [
...Mcp::client('nightwatch')
->withToken(auth()->user()->mcp_nightwatch_token)
->tools(),
new SendSlackMessage,
];
}
}
```
Laravel AI는 `tools()` 배열의 내용이 MCP 도구임을 감지하여 에이전트의 도구 계약에 맞도록 래핑합니다. MCP의 입력 스키마를 Laravel의 JSON 스키마로 변환하고, 모델이 도구를 호출했을 때 원격 호출을 실행하며, 결과를 정규화하여 반환합니다. 오류·구조화 데이터·플레인 텍스트·스트리밍 업데이트 모두 자동으로 처리되므로, 에이전트 측 코드에 MCP의 세부 사항이 새어 나오지 않습니다.
여러 전송 계층을 하나의 에이전트에 혼재시킬 수도 있습니다.
```php theme={null}
public function tools(): array
{
return [
...Mcp::client('nightwatch')->tools(),
...Client::local('npx', ['-y', '@modelcontextprotocol/server-puppeteer'])->tools(),
new SendSlackMessage,
];
}
```
또한, 자신의 Laravel MCP 서버용으로 작성한 도구 클래스는 클라이언트 연결 없이 그대로 에이전트에 전달할 수 있습니다. 같은 도구를 외부 공개용과 에이전트용 양쪽에서 재사용할 수 있다는 뜻입니다.
```php theme={null}
use App\Mcp\Tools\CurrentWeatherTool;
public function tools(): array
{
return [
new CurrentWeatherTool,
new SendSlackMessage,
];
}
```
## 도구 목록 캐싱
도구 목록의 가져오기에는 서버로의 왕복이 발생합니다. 특히 OAuth 경유의 원격 서버에서는 프롬프트마다 호출하는 것은 낭비입니다. 도구 목록은 자주 바뀌지 않으므로 캐시 대상으로 적합합니다.
```php theme={null}
public function tools(): array
{
$tools = Cache::remember('mcp.nightwatch.tools', now()->addHour(), fn () =>
Mcp::client('nightwatch')->tools()
);
return [...$tools, new SendSlackMessage];
}
```
MCP 도구는 플레인 데이터로 반환되므로 캐시에서 복원해도 그대로 동작합니다.
## 테스트
실제로 가동 중인 MCP 서버가 없어도 Laravel AI의 페이크 기능으로 에이전트를 테스트할 수 있습니다. MCP 도구명은 `mcp_tools_`이라는 명명 규약을 따르므로, `search`라는 도구는 `mcp_tools_search`로 나타납니다.
```php theme={null}
use Laravel\Ai\Responses\Data\ToolCall;
SupportAgent::fake([
new ToolCall('call_1', 'mcp_tools_search', ['query' => 'laravel']),
'Found the issue.',
]);
$response = (new SupportAgent)->prompt('Find the latest error');
expect($response->toolCalls)->toHaveCount(1);
expect($response->toolResults->first()->result)->toContain('Found');
```
에이전트의 통상 루프는 그대로 동작하며, 모델의 발언만을 페이크가 결정합니다. 도구 호출 자체는 MCP 계층을 실제로 통과하므로 네트워크 없이 프로덕션과 같은 경로를 테스트할 수 있습니다.
## 현재 지원 범위
이 첫 릴리스에서는 STDIO와 Streamable HTTP 양쪽 전송 계층에서 도구와 프롬프트를 지원합니다. 인증은 Bearer 토큰과 OAuth를 지원합니다. MCP 자체의 발전에 맞춰 앞으로도 지원 범위가 확대될 전망입니다.
## 관련 페이지
표준으로 지원되지 않는 AI 서비스에 대응하는 커스텀 프로바이더 구현 방법
이 기사에서 예로 사용된 호스팅 모니터링 서비스 Nightwatch 설명
## Related topics
- [laravel/agent-skills — Laravel 공식 AI 에이전트 스킬 모음](/ko/blog/agent-skills-introduction.md)
- [Laravel Agent Detector — AI 에이전트 감지 패키지](/ko/blog/agent-detector-introduction.md)
- [2026년 5월 Laravel 업데이트](/ko/blog/changelog/202605.md)
- [Laravel PAO — AI 에이전트용 출력 최적화 도구](/ko/blog/pao-introduction.md)
- [AI 에이전트는 '올바른' 코드에서 'Laravel다운' 코드로 - Boost Benchmarks의 다음 한 수](/ko/blog/boost-benchmarks-idiomatic-laravel.md)