# MCP 클라이언트

`huggingface_hub` 라이브러리는 이제 [Model Context Protocol](https://modelcontextprotocol.io)(MCP)을 통해 외부 Tools와 상호작용할 수 있는 기능을 Large Language Models(LLM)에 부여하도록 설계된 [MCPClient](/docs/huggingface_hub/main/ko/package_reference/mcp#huggingface_hub.MCPClient)를 포함합니다. 이 클라이언트는 [AsyncInferenceClient](/docs/huggingface_hub/main/ko/package_reference/inference_client#huggingface_hub.AsyncInferenceClient)를 확장하여 Tool 사용을 원활하게 통합합니다.

[MCPClient](/docs/huggingface_hub/main/ko/package_reference/mcp#huggingface_hub.MCPClient)는 도구를 노출하는 MCP 서버(로컬 `stdio` 스크립트 또는 원격 `http`/`sse` 서비스)에 연결합니다. 이 클라이언트는 이러한 도구를 LLM에 전달하며([AsyncInferenceClient](/docs/huggingface_hub/main/ko/package_reference/inference_client#huggingface_hub.AsyncInferenceClient)를 통해) LLM이 도구를 사용하기로 결정하면 [MCPClient](/docs/huggingface_hub/main/ko/package_reference/mcp#huggingface_hub.MCPClient)가 MCP 서버로의 실행 요청을 관리하고 Tool의 출력을 LLM으로 되돌려 전달합니다. 이 과정에서 결과를 실시간으로 스트리밍하는 경우가 많습니다.

더 높은 수준의 [Agent](/docs/huggingface_hub/main/ko/package_reference/mcp#huggingface_hub.Agent) 클래스도 제공합니다. 이 'Tiny Agent'는 채팅 루프와 상태를 관리하여 대화형 Agent 생성을 단순화하며, [MCPClient](/docs/huggingface_hub/main/ko/package_reference/mcp#huggingface_hub.MCPClient)를 감싸는 래퍼 역할을 합니다.

## MCP 클라이언트[[huggingface_hub.MCPClient]]

#### huggingface_hub.MCPClient[[huggingface_hub.MCPClient]]

```python
huggingface_hub.MCPClient(model: typing.Optional[str] = None, provider: typing.Union[typing.Literal['baseten', 'cerebras', 'cohere', 'deepinfra', 'fal-ai', 'featherless-ai', 'fireworks-ai', 'groq', 'hf-inference', 'novita', 'nscale', 'openai', 'ovhcloud', 'publicai', 'replicate', 'scaleway', 'together', 'wavespeed', 'zai-org'], typing.Literal['auto'], NoneType] = None, base_url: typing.Optional[str] = None, api_key: typing.Optional[str] = None)
```

[소스](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L55)

**매개변수:**

model (`str`, `optional`) : 추론을 실행할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID(예: `meta-llama/Meta-Llama-3-8B-Instruct`)이거나, 배포된 Inference Endpoint 또는 기타 로컬/원격 엔드포인트의 URL일 수 있습니다.

provider (`str`, *선택 사항*) : 추론에 사용할 프로바이더의 이름입니다. 기본값은 "auto"이며, 이는 모델에서 사용 가능한 프로바이더 중 https://hf.co/settings/inference-providers 에서 사용자가 지정한 순서대로 정렬된 첫 번째 프로바이더를 의미합니다. model이 URL이거나 `base_url`이 전달된 경우, `provider`는 사용되지 않습니다.

base_url (`str`, *선택 사항*) : 추론을 실행할 기본 URL입니다. 기본값은 None입니다.

api_key (`str`, `optional`) : 인증에 사용할 토큰입니다. 제공되지 않으면 로컬에 저장된 Hugging Face 토큰을 기본값으로 사용합니다. 직접 제공업체의 서비스와 상호작용하려면 자체 제공업체 API 키를 사용할 수도 있습니다.

하나 이상의 MCP 서버에 연결하고 도구를 사용하여 채팅 완성을 처리하는 클라이언트입니다.

> [!WARNING]
> 이 클래스는 실험적이며, 사전 통보 없이 향후 호환성이 깨지는 변경 사항이 발생할 수 있습니다.

#### add_mcp_server[[huggingface_hub.MCPClient.add_mcp_server]]

```python
add_mcp_server(type: typing.Literal['stdio', 'sse', 'http'], **params: typing.Any)
```

[소스](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L123)

**매개변수:**

type (`str`) : 연결할 서버의 유형입니다. 다음 중 하나여야 합니다: - "stdio": 표준 입력/출력 서버(로컬) - "sse": 서버 전송 이벤트(SSE) 서버 - "http": StreamableHTTP 서버

- ****params** (`dict[str, Any]`) : stdio 서버, SSE 서버, StreamableHTTP 서버 중 하나에 해당하는 서버 파라미터입니다. - stdio 서버의 경우: - command (str): MCP 서버를 실행할 명령어 - args (list[str], optional): 명령어에 전달할 인자 - env (dict[str, str], optional): 명령어에 사용할 환경 변수 - cwd (Union[str, Path, None], optional): 명령어의 작업 디렉터리 - allowed_tools (list[str], optional): 이 서버에서 허용할 도구 이름 목록 - SSE 서버의 경우: - url (str): SSE 서버의 URL - headers (dict[str, Any], optional): SSE 연결에 사용할 헤더 - timeout (float, optional): 연결 타임아웃 - sse_read_timeout (float, optional): SSE 읽기 타임아웃 - allowed_tools (list[str], optional): 이 서버에서 허용할 도구 이름 목록 - StreamableHTTP 서버의 경우: - url (str): StreamableHTTP 서버의 URL - headers (dict[str, Any], optional): StreamableHTTP 연결에 사용할 헤더 - timeout (timedelta, optional): 연결 타임아웃 - sse_read_timeout (timedelta, optional): SSE 읽기 타임아웃 - terminate_on_close (bool, optional): 닫을 때 종료할지 여부 - allowed_tools (list[str], optional): 이 서버에서 허용할 도구 이름 목록

MCP 서버에 연결

#### cleanup[[huggingface_hub.MCPClient.cleanup]]

```python
cleanup()
```

[소스](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L109)

리소스 정리

#### process_single_turn_with_tools[[huggingface_hub.MCPClient.process_single_turn_with_tools]]

```python
process_single_turn_with_tools(messages: list, exit_loop_tools: typing.Optional[list[huggingface_hub.inference._generated.types.chat_completion.ChatCompletionInputTool]] = None, exit_if_first_chunk_no_tool: bool = False)
```

[소스](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L252)

**매개변수:**

messages (`list[dict]`) : 대화 역사를 나타내는 메시지 객체의 목록

exit_loop_tools (`list[ChatCompletionInputTool]`, *선택 사항*) : 호출 시 생성기를 종료해야 하는 도구 목록

exit_if_first_chunk_no_tool (`bool`, *선택 사항*) : 첫 번째 청크에 도구가 없으면 종료합니다. 기본값은 False입니다.

**반환 값:**

[ChatCompletionStreamOutput](/docs/huggingface_hub/main/ko/package_reference/inference_types#huggingface_hub.ChatCompletionStreamOutput) 청크 또는 [ChatCompletionInputMessage](/docs/huggingface_hub/main/ko/package_reference/inference_types#huggingface_hub.ChatCompletionInputMessage) 객체

`self.model`과 사용 가능한 도구를 사용하여 쿼리를 처리하고, 청크와 도구 출력을 반환합니다.

## 에이전트[[huggingface_hub.Agent]]

#### huggingface_hub.Agent[[huggingface_hub.Agent]]

```python
huggingface_hub.Agent(model: Optional[str] = None, servers: Iterable[ServerConfig], provider: Optional[PROVIDER_OR_POLICY_T] = None, base_url: Optional[str] = None, api_key: Optional[str] = None, prompt: Optional[str] = None)
```

[소스](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/agent.py#L13)

**매개변수:**

model (`str`, *선택 사항*) : 추론을 실행할 모델입니다. Hugging Face Hub에 호스팅된 모델 ID(예: `meta-llama/Meta-Llama-3-8B-Instruct`)이거나, 배포된 Inference Endpoint 또는 기타 로컬/원격 엔드포인트의 URL일 수 있습니다.

servers (`Iterable[dict]`) : 연결할 MCP 서버들. 각 서버는 `type` 키와 `config` 키를 포함하는 딕셔너리입니다. `type` 키는 `"stdio"` 또는 `"sse"`일 수 있으며, `config` 키는 서버의 인수를 나타내는 딕셔너리입니다.

provider (`str`, *선택 사항*) : 추론에 사용할 프로바이더의 이름입니다. 기본값은 "auto"이며, 이는 모델에서 사용 가능한 프로바이더 중 https://hf.co/settings/inference-providers 에서 사용자가 지정한 순서대로 정렬된 첫 번째 프로바이더를 의미합니다. model이 URL이거나 `base_url`이 전달된 경우, `provider`는 사용되지 않습니다.

base_url (`str`, *선택 사항*) : 추론을 실행할 기본 URL입니다. 기본값은 None입니다.

api_key (`str`, *선택 사항*) : 인증에 사용할 토큰. 제공되지 않으면 로컬에 저장된 Hugging Face 토큰을 기본값으로 사용합니다. 직접 제공업체의 서비스와 상호작용하려면 자체 제공업체 API 키를 사용할 수도 있습니다.

prompt (`str`, *선택 사항*) : 에이전트에 사용할 시스템 프롬프트입니다. 기본값은 `constants.py`의 기본 시스템 프롬프트입니다.

[MCPClient](/docs/huggingface_hub/main/ko/package_reference/mcp#huggingface_hub.MCPClient) 바로 위에 구축된 단순한 while 루프인 Simple Agent의 구현입니다.

> [!WARNING]
> 이 클래스는 실험적이며, 사전 통보 없이 향후 호환성이 깨지는 변경 사항이 발생할 수 있습니다.

#### 실행[[huggingface_hub.Agent.run]]

```python
run(user_input: str, abort_event: Optional[asyncio.Event] = None)
```

[소스](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/agent.py#L57)

**매개변수:**

user_input (`str`) : 에이전트를 실행하기 위한 사용자 입력입니다.

abort_event (`asyncio.Event`, *선택 사항*) : 에이전트를 중단하는 데 사용할 수 있는 이벤트입니다. 이벤트가 설정되면 에이전트는 실행을 중단합니다.

주어진 사용자 입력으로 에이전트를 실행합니다.

