4. MCP tool server 붙이기

내용 검토: 2026. 08. 21.검토 필요

결론부터

Agent의 능력은 model 이름이 아니라 MCP server가 제공한 기능과 Agent가 명시적으로 허용한 tool의 교집합에서 생긴다

이 장에서 처음 나오는 말3개

MCPServerModel Context Protocol Server Resource: kmcp가 container workload로 실행하고 kagent가 tool을 발견하게 하는 resource다.
discoveryTool Discovery: server가 제공하는 tool 이름과 입력 schema를 client가 조회하는 과정이다.
stdio transportStandard Input/Output Transport: tool process와 MCP proxy가 표준 입출력으로 message를 주고받는 방식이다.

이번 실습의 연결

질문이 simple-fetch-agent와 allowlist의 fetch tool을 거쳐 MCPServer·uvx process·외부 HTTPS URL까지 갔다가 요약 응답으로 돌아오는 흐름

공식 입문 예제의 fetch server는 package를 받아 code로 실행하고 외부 URL에 접근한다. 격리된 전용 cluster에서 MCP 연결을 관찰하는 용도로만 쓴다. 운영에서는 image digest, egress allowlist, ServiceAccount, resource limit, package 공급망을 먼저 고정한다.

MCPServer 만들기

확인 당시 kmcp MCPServer API는 kagent.dev/v1alpha1이다. Agent의 v1alpha2와 번호가 다른 것이 오타가 아니다.

kubectl apply -f - <<'EOF'
apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: mcp-website-fetcher
  namespace: kagent
spec:
  deployment:
    args:
      - mcp-server-fetch
    cmd: uvx
    port: 3000
  stdioTransport: {}
  transportType: stdio
EOF

생성된 resource와 workload를 함께 본다.

kubectl -n kagent get mcpserver mcp-website-fetcher -o yaml
kubectl -n kagent get pods

Pod가 바로 ready가 되지 않으면 MCPServer status와 새 Pod의 Events·log를 읽는다. resource 이름과 생성된 workload 이름이 완전히 같다고 가정하지 말고 creation timestamp와 owner reference로 연결한다.

fetch Agent 만들기

kubectl apply -f - <<'EOF'
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: simple-fetch-agent
  namespace: kagent
spec:
  description: Fetch one explicitly supplied HTTPS page and summarize it.
  type: Declarative
  declarative:
    runtime: go
    modelConfig: default-model-config
    systemMessage: |-
      You summarize a webpage only after calling the fetch tool.
      Accept only an explicit HTTPS URL from the user.
      Do not fetch localhost, link-local, cluster-local, or private-network addresses.
      State which URL was fetched and separate retrieved facts from your inference.
    tools:
      - type: McpServer
        mcpServer:
          kind: MCPServer
          name: mcp-website-fetcher
          toolNames:
            - fetch
EOF

kubectl -n kagent wait \
  --for=condition=Ready agent/simple-fetch-agent --timeout=3m

Tool 하나를 호출하기

dashboard의 Agent 목록에서 simple-fetch-agent를 열고, 작고 공개된 문서 URL 하나를 명시해 질문한다.
```
https://example.com/ 을 fetch해서 페이지 제목과 목적만 요약해 줘.
```
tool arguments와 result를 펼쳐, arguments의 URL이 사용자가 준 값과 같은지와 실제 tool 이름이 fetch인지 확인한다.

같은 호출을 CLI로 재현한다. controller port-forward가 살아 있는지 먼저 확인한다.

kagent invoke -n kagent -a simple-fetch-agent -S \
  -t "Fetch https://example.com/ and summarize only the page title and purpose."

Tool을 붙였다는 네 단계 증거

MCPServer resource가 accepted되었다.
MCP workload가 ready이고 tool discovery에 fetch가 보인다.
Agent spec의 toolNames가 fetch만 허용한다.
실제 호출 event에 fetch arguments와 result가 남는다.

답변만 보고 4번부터 확인하면 tool이 실패했는데 model이 추측으로 답한 경우를 놓칠 수 있다.

안 될 때 먼저 볼 것

증상	확인
MCP Pod가 ready가 아님	Pod Events와 log — `uvx`의 package 다운로드는 외부 egress·프록시가 열려 있어야 한다
discovery에 `fetch`가 없음	`MCPServer` status와 MCP Pod log
Agent가 `Ready=False`	Agent conditions의 `mcpServer` 참조 이름·kind와 MCPServer 상태
fetch 호출이 실패	tool result의 오류 메시지, 대상 URL 접근성, cluster egress
요약은 그럴듯한데 tool event가 없음	dashboard의 tool arguments·result — model이 추측으로 답했는지

완료 체크

MCPServer와 생성된 workload를 연결해 봤다.
Agent가 server 전체가 아니라 fetch 하나만 allowlist로 참조한다.
tool arguments·result와 최종 요약을 구분해 확인했다.
resource는 6장의 관찰 실습까지 남겨 둔다.

참고 자료

첫 MCP tool — kmcp MCPServer와 fetch Agent 공식 예제
kagent Tools — built-in·MCP·HTTP tool과 보안 주의
kagent tools ecosystem — 기본 server와 tool catalog

5. CLI와 A2A로 Agent 호출하기호출 UI를 벗어나 Agent card와 protocol endpoint를 직접 확인한다.