`createMCPClient()`
createMCPClient()
MCP(Model Context Protocol) 서버에 연결하는 경량 MCP 클라이언트를 만듭니다. 이 클라이언트는 다음을 제공합니다.
- Tools (툴): MCP 툴과 AI SDK 툴 간의 자동 변환
- Resources (리소스): MCP 서버에서 리소스 템플릿을 나열, 읽기, 발견하는 메서드
- Prompts (프롬프트): 사용 가능한 프롬프트를 나열하고 프롬프트 메시지를 가져오는 메서드
- Completions (자동완성): 프롬프트 인자와 리소스 템플릿 변수에 대한 자동완성 제안을 요청하는 메서드
- Elicitation: 툴 실행 중 서버의 추가 입력 요청을 처리하는 기능
현재 MCP 서버로부터의 알림 수신과 클라이언트의 커스텀 구성은 지원하지 않습니다.
출처: 문서
본문
Import
import { createMCPClient } from "@ai-sdk/mcp"
API Signature
Parameters (파라미터)
config:MCPClientConfig— MCP 클라이언트의 구성입니다.transport:MCPTransportConfig | MCPTransport— 메시지 전송 계층의 구성입니다.MCPTransport— stdio 또는 커스텀 전송에 명시적으로 사용되는 클라이언트 전송 인스턴스입니다.start:() => Promise<void>— 전송을 시작하는 메서드입니다.send:(message: JSONRPCMessage) => Promise<void>— 전송을 통해 메시지를 보내는 메서드입니다.close:() => Promise<void>— 전송을 닫는 메서드입니다.onclose:() => void— 전송이 닫힐 때 호출되는 메서드입니다.onerror:(error: Error) => void— 전송에 오류가 발생할 때 호출되는 메서드입니다.onmessage:(message: JSONRPCMessage) => void— 전송이 메시지를 받을 때 호출되는 메서드입니다.
MCPTransportConfig— 전송 구성 객체입니다.type:'sse' | 'http'— 통신에 Server-Sent Events를 사용하려면 지정합니다.url:string— MCP 서버의 URL입니다.headers:Record<string, string>(선택) — 요청과 함께 보낼 추가 HTTP 헤더입니다.authProvider:OAuthClientProvider(선택) — 보호된 원격 MCP 서버에 접근하기 위한 선택적 OAuth 프로바이더입니다. 메타데이터를 가져오기 전에 발견된 OAuth 인증 서버 URL을 허용 목록에 추가하려면 프로바이더에validateAuthorizationServerURL을 구현하세요.redirect:'follow' | 'error'(선택) — 전송 요청에 대한 HTTP 리다이렉트 처리 방식을 제어합니다. 리다이렉트 응답을 허용하려면'follow'로 설정하세요. 기본값은'error'로, 모든 리다이렉트 응답을 거부하여 서버가 요청을 의도하지 않은 호스트로 리다이렉트하는 것을 방지합니다.initialSessionId:string(선택) — 초기화 후 재개된 Streamable HTTP 요청과 함께 보낼 이전 레거시 MCP 세션 id입니다.createMCPClient와 함께 사용할 때는initialInitializeResult와 짝을 이룹니다. HTTP 전송 및 초기화 기반 프로토콜 버전에서만 사용됩니다.initialProtocolVersion:string(선택) — initialize가 하나를 협상하기 전에 보낼 이전 레거시 MCP 프로토콜 버전입니다. HTTP 전송에서만 사용됩니다.onSessionIdChange:(sessionId: string | undefined) => void(선택) — Streamable HTTP 서버가 MCP 세션 id를 생성, 변경 또는 제거할 때 호출되는 콜백입니다. HTTP 전송에서만 사용됩니다.onSessionExpired:(sessionId: string) => void(선택) — Streamable HTTP 요청이 기존 MCP 세션 id에 대해 404를 반환할 때 호출되는 콜백입니다. 전송은 기본 HTTP 오류를 보고하기 전에 세션 id를 지웁니다. HTTP 전송에서만 사용됩니다.terminateSessionOnClose:boolean(선택) —close()가 현재 MCP 세션 id에 대해 DELETE를 보낼지 여부입니다. 애플리케이션이 나중에 세션에 다시 연결하려 할 때false로 설정하세요. 기본값은true입니다. HTTP 전송에서만 사용됩니다.fetch:FetchFunction(선택) — HTTP 요청에 사용할 선택적 커스텀 fetch 구현입니다. 요청 로컬 fetch가 필요한 런타임에 유용합니다.
initializationOptions:RequestOptions(선택) — 전송 시작과 프로토콜 협상을 제한하는 선택적 신호(signal) 및 타임아웃 설정입니다. 타임아웃 또는 abort는 전송을 닫고createMCPClient를 거부합니다.clientName:string(선택) — 클라이언트 이름입니다. 기본값은 "ai-sdk-mcp-client"입니다.name:string(선택) — deprecated 되었습니다.clientName을 사용하세요. 기본값은 "ai-sdk-mcp-client"입니다.version:string(선택) — 클라이언트 버전입니다. 기본값은 "1.0.0"입니다.onUncaughtError:(error: unknown) => void(선택) — 잡히지 않은 오류의 처리기입니다.maxRetries:number(선택) — 일시적인 MCP 툴 호출 실패에 대한 최대 재시도 횟수입니다. 재시도를 비활성화하려면 0으로 설정하세요. 기본값은 0입니다. 재시도는 opt-in이며 tools/call 요청에 적용됩니다.initialInitializeResult:InitializeResult(선택) — 이전 레거시 MCP 세션의 initialize 결과입니다. 제공되면 클라이언트는 전송을 시작하고 새 initialize 요청을 보내지 않고 이 메타데이터를 재사용합니다.capabilities:ClientCapabilities(선택) — 레거시 초기화 중 또는 각 무상태 현대 요청에서 알릴 선택적 클라이언트 능력입니다. 예를 들어 서버의 elicitation 요청 처리를 활성화하려면{ elicitation: {} }를 설정하세요.
Returns (반환값)
다음 속성과 메서드를 가진 MCPClient로 해석되는 Promise를 반환합니다.
initializeResult:InitializeResult— 이 클라이언트가 사용하는 연결 메타데이터입니다. 레거시 서버의 경우 이는 initialize 결과이고, 현대 서버의 경우 프로토콜 발견에서 파생된 동등한 값입니다.serverInfo:Configuration— 연결된 MCP 서버에 대한 정보입니다 (이름, 버전, 선택적 제목). 초기화 또는 프로토콜 발견 중에 보고됩니다.instructions:string(선택) — initialize 핸드셰이크 중 서버가 제공한 선택적 지시문입니다. 서버와 그 기능을 사용하는 방법을 설명합니다. LLM 시스템 프롬프트에 포함하기에 유용합니다.tools:async (options?: { schemas?: TOOL_SCHEMAS }) => Promise<McpToolSet<TOOL_SCHEMAS>>— MCP 서버에서 사용 가능한 툴을 가져옵니다.schemas:TOOL_SCHEMAS(선택) — 컴파일 타임 타입 검사를 위한 스키마 정의입니다. 제공되지 않으면 스키마는 서버에서 추론됩니다. 각 툴 스키마는 타입이 지정된 입력을 위한inputSchema를, 서버가structuredContent를 반환할 때 타입이 지정된 출력을 위한 선택적outputSchema를 포함할 수 있습니다.inputSchema:FlexibleSchema— 툴의 예상 입력 파라미터를 정의하는 Zod 스키마 또는 JSON 스키마입니다.outputSchema:FlexibleSchema(선택) — 예상 출력 구조를 정의하는 Zod 스키마 또는 JSON 스키마입니다. 제공되면 클라이언트는 툴 결과에서structuredContent를 추출하고 검증하여 타입이 지정된 출력을 제공합니다.
listTools:async (options?: { params?: PaginatedRequest['params']; options?: RequestOptions }) => Promise<ListToolsResult>— AI SDK 툴로 변환하지 않고 MCP 서버에서 사용 가능한 툴 정의를 나열합니다.params:PaginatedRequest['params'](선택) — cursor를 포함한 선택적 페이지네이션 파라미터입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
callTool:async (args: { name: string; arguments?: Record<string, unknown>; options?: RequestOptions }) => Promise<CallToolResult>— MCP 서버에서 툴을 호출합니다. 이는 호스트 매개 호출(MCP Apps iframe 요청 등)에 유용합니다.name:string— 호출할 MCP 툴의 이름입니다.arguments:Record<string, unknown>(선택) — MCP 툴에 전달할 인자입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
toolsFromDefinitions:(definitions: ListToolsResult, options?: { schemas?: TOOL_SCHEMAS }) => McpToolSet<TOOL_SCHEMAS>— 툴을 다시 나열하지 않고 기존 MCP 툴 정의를 AI SDK 툴로 변환합니다.definitions:ListToolsResult— 일반적으로listTools가 반환한 툴 정의입니다.schemas:TOOL_SCHEMAS(선택) — 컴파일 타임 타입 검사와 타입이 지정된 출력을 위한 선택적 스키마 정의입니다.
listResources:async (options?: { params?: PaginatedRequest['params']; options?: RequestOptions }) => Promise<ListResourcesResult>— MCP 서버에서 사용 가능한 모든 리소스를 나열합니다.params:PaginatedRequest['params'](선택) — cursor를 포함한 선택적 페이지네이션 파라미터입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
readResource:async (args: { uri: string; options?: RequestOptions }) => Promise<ReadResourceResult>— URI로 특정 리소스의 내용을 읽습니다.uri:string— 읽을 리소스의 URI입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
listResourceTemplates:async (options?: { options?: RequestOptions }) => Promise<ListResourceTemplatesResult>— MCP 서버에서 사용 가능한 모든 리소스 템플릿을 나열합니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
complete:async (args: CompleteRequestParams & { options?: RequestOptions }) => Promise<CompleteResult>— 프롬프트 인자 또는 리소스 템플릿 변수에 대한 자동완성 제안을 요청합니다. 서버는 completions 능력을 광고해야 합니다.ref:{ type: 'ref/prompt'; name: string } | { type: 'ref/resource'; uri: string }— 완성 중인 프롬프트 또는 리소스 템플릿에 대한 참조입니다.argument:{ name: string; value: string }— 완성할 인자 이름과 현재 부분 값입니다.context:{ arguments: Record<string, string> }(선택) — 다중 인자 프롬프트 또는 리소스 템플릿에 컨텍스트를 제공하는 데 사용되는 이전에 해결된 인자 값입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
experimental_listPrompts:async (options?: { params?: PaginatedRequest['params']; options?: RequestOptions }) => Promise<ListPromptsResult>— MCP 서버에서 사용 가능한 프롬프트를 나열합니다. 이 메서드는 실험적이며 향후 변경될 수 있습니다.params:PaginatedRequest['params'](선택) — cursor를 포함한 선택적 페이지네이션 파라미터입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
experimental_getPrompt:async (args: { name: string; arguments?: Record<string, unknown>; options?: RequestOptions }) => Promise<GetPromptResult>— 선택적으로 인자를 전달해 이름으로 프롬프트를 가져옵니다. 이 메서드는 실험적이며 향후 변경될 수 있습니다.name:string— 가져올 프롬프트 이름입니다.arguments:Record<string, unknown>(선택) — 프롬프트에 채울 선택적 인자입니다.options:RequestOptions(선택) — signal과 timeout을 포함한 선택적 요청 옵션입니다.
onElicitationRequest:(schema: typeof ElicitationRequestSchema, handler: (request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult) => void— MCP 서버의 elicitation 요청에 대한 처리기를 등록합니다. 서버가 툴 실행 중 추가 입력이 필요할 때 처리기가 요청을 받습니다.schema:typeof ElicitationRequestSchema— 요청을 검증할 스키마입니다. 반드시ElicitationRequestSchema여야 합니다.handler:(request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult— elicitation 요청을 처리하는 함수입니다. 요청에는 메시지와requestedSchema가 포함됩니다. 핸들러는action("accept", "decline", 또는 "cancel")과, 수락 시 선택적으로 content를 가진 객체를 반환해야 합니다.
close:() => Promise<void>— MCP 서버에 대한 연결을 닫고 리소스를 정리합니다.
Example (예제)
import { createMCPClient } from '@ai-sdk/mcp';
import { generateText } from 'ai';
import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';
let client;
try {
client = await createMCPClient({
transport: new Experimental_StdioMCPTransport({
command: 'node server.js',
}),
});
const tools = await client.tools();
const response = await generateText({
model: __MODEL__,
tools,
messages: [{ role: 'user', content: 'Query the data' }],
});
console.log(response);
} catch (error) {
console.error('Error:', error);
} finally {
// ensure the client is closed even if an error occurs
if (client) {
await client.close();
}
}
Error Handling (오류 처리)
클라이언트는 다음 경우에 MCPClientError를 발생시킵니다.
- 클라이언트 초기화 실패
- 프로토콜 버전 불일치
- 서버 능력 부족
- 연결 실패
툴 실행의 경우 오류는 CallToolError 오류로 전파됩니다. 알 수 없는 오류의 경우 클라이언트는 알려진 오류 유형에 포함되지 않는 오류를 수동으로 기록하거나 처리하는 데 사용할 수 있는 onUncaughtError 콜백을 노출합니다.