MCP 서버

모든 Agent-Lab 애플리케이션에는 Model Context Protocol 서버가 포함되어 있습니다. 이 서버는 FastMCP로 구축되었으며 /mcp 경로에 마운트됩니다(Streamable HTTP, 무상태). Claude Desktop, IDE, 직접 만든 에이전트 등의 MCP 클라이언트는 앱의 에이전트를 검색하고, 대화 기록을 읽고, 에이전트와 직접 대화할 수 있습니다. 서버와 서버의 도구/프롬프트 등록자는 에이전트와 동일한 검색 메커니즘, 즉 scan_packages와 agent_lab.agents 엔트리 포인트 그룹을 사용합니다.

서버가 노출하는 항목

이 프롬프트 3종 세트는 각 에이전트 유형의 기본 시스템 프롬프트를 제공하며, agent_type + setting_key를 통해 테넌트별로 재정의할 수 있습니다.

MCP Inspector로 사용해 보기

MCP Inspector를 시작하고 앱에 연결하세요(예: http://localhost:18000/mcp, 전송 방식: Streamable HTTP).

npx @modelcontextprotocol/inspector

웹 콘솔에 접속하세요(콘솔에 출력된 프록시 링크를 사용합니다).

Claude Desktop 연결

참고: 여기서 Claude Desktop은 시연 목적으로만 사용합니다. 이 프로젝트는 Anthropic AI와 관련이 없습니다.

1. Claude Desktop이 원격 HTTP 서버에 접근할 때 사용하는 mcp-proxy 브리지를 설치합니다.

   pip install mcp-proxy

2. Settings → Developer → Edit Config를 열고 claude_desktop_config.json을 편집합니다(엔드포인트는 설치 환경에 맞게 수정하세요. Python 환경에 mcp-proxy가 설치되어 있어야 합니다).

3. Claude Desktop을 다시 시작한 후 Settings → Developer로 다시 이동하면 Agent-Lab이 표시됩니다.

4. 사용해 보세요. Claude에게 에이전트 목록을 조회하거나, 감독형 코더 에이전트 인스턴스의 대화 기록을 가져오거나, 에이전트가 이전에 생성한 코드 스니펫을 보여 달라고 요청해 보세요.

OpenAI Responses API

Responses API의 호스팅된 Model Context Protocol(MCP) 도구를 사용하면 외부 서비스에 더 쉽게 연결할 수 있습니다. 모델이 MCP 서버를 가리키도록 한 번만 구성하면, MCP 서버가 중앙 집중식 도구 호스트 역할을 합니다. (출처: MCP Tool Guide)

OpenAI Responses API와 Agent-Lab MCP 서버의 통합을 보여 주는 노트북은 notebooks/11_mcp_client-openai-responses.ipynb에서 확인할 수 있습니다.

사용자 정의 도구와 프롬프트 추가

모든 항목은 에이전트와 같은 방식으로 검색됩니다. 데코레이터를 적용하고, (라이브러리 사용자라면) 패키지가 scan_packages에 포함되어 있거나 agent_lab.agents 엔트리 포인트 그룹을 통해 게시되어 있는지 확인하세요.

도구 — 일반 비동기 함수입니다. 첫 번째 container 파라미터는 DI 컨테이너에서 주입되며 클라이언트에는 노출되지 않습니다.

from agent_lab import discoverable_mcp_tool


@discoverable_mcp_tool(
    "my_hello_tool",
    description="Returns a friendly greeting.",
    annotations={"readOnlyHint": True},
)
async def hello_tool(container, name: str) -> str:
    return f"Hello, {name}!"

프롬프트 — 프롬프트 3종 세트 전체(도구 / prompts/get / prompt:// 리소스)로 노출됩니다.

from agent_lab import discoverable_mcp_prompt


@discoverable_mcp_prompt("my_greeting_prompt")
def greeting_prompt() -> str:
    return "Greet the user warmly and briefly."

고급 — 사용자 정의 도구/프롬프트/리소스 세트가 필요하면 @discoverable_mcp_registrar(extra_deps=(...))를 통해 McpRegistrar(또는 PromptSetRegistrar) 하위 클래스를 직접 작성합니다. 클라이언트를 위한 MCP 지침을 추가하려면 앱을 조립할 때 지침 조각을 전달하세요.

app = create_app(mcp_instructions=["Extra guidance for MCP clients."])

스캐폴드에 동작하는 예제(mcp/tools.py, mcp/prompts.py)가 포함되어 있습니다. 첫 번째 에이전트를 참고하세요.

인증

인증이 활성화되면 MCP 클라이언트는 Keycloak 기반의 OAuth 프록시를 통해 인증합니다. JWT는 렐름 JWKS(openid, profile, email 스코프)를 기준으로 검증되며, OAuth 클라이언트 정보는 Redis에 (암호화되어) 저장됩니다. 앱은 표준 메타데이터 엔드포인트 (/.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server/mcp)를 게시하므로, 표준을 준수하는 클라이언트는 스스로 구성할 수 있습니다.