Pi는 Model Context Protocol 서버를 stdio 또는 streamable HTTP로 연결해 그 서버들의 도구와 리소스를 모델이 사용할 수 있게 합니다. 이 글은 공식 MCP 문서를 바탕으로 실제 설정과 운용에 필요한 내용을 정리합니다.

빠르게 추가하기

로컬 stdio 서버는 다음 한 줄로 추가합니다.

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list
pi

원격 서버는 URL과 토큰으로 추가합니다.

pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN

기본으로는 사용자 전역 설정에 추가됩니다. --local(또는 -l)을 붙이면 프로젝트 설정에 씁니다. 대화 중에는 /mcp로 연결 상태 확인, 로그인, 재연결, 활성화·비활성화, 노출 변경을 할 수 있습니다. 세션 밖에서 서버를 바꾸었다면 /reload를 실행합니다.

설정 파일

사용자 전역은 ~/.pi/agent/mcp.json, 프로젝트는 .pi/mcp.json을 읽습니다. 프로젝트 설정은 프로젝트 신뢰가 허용된 뒤에만 읽히며, 같은 이름의 프로젝트 항목이 전역 항목을 대체합니다. command/url/type 없이 enabled·exposure만 덮어써서 전역 서버를 특정 프로젝트에서만 끄는 것도 가능합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "docs": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
      "description": "제품 문서를 검색하고 읽습니다"
    }
  }
}

stdio 서버는 command·args·env·cwd, HTTP 서버는 url·headers·oauth를 사용합니다. 레거시 SSE 전송은 지원하지 않습니다. timeout(초, 기본 60), enabled: false, 서버가 무언지 한 줄로 적는 description 같은 공통 필드가 있습니다. 개인 서버나 자격 증명이 필요한 서버는 전역 파일에, 프로젝트가 실제로 요구하는 서버만 프로젝트 파일에 두라는 안내입니다.

규칙 몇 가지를기억해 두면 좋습니다.

• 서버 이름은 문자·숫자·_·-만 허용. 도구는 mcp__<서버>__<도구>로 등록됩니다.
• command는 실행 파일 하나이며 셸 명령 문자열이 아닙니다.
• env·headers 값에는 ${GITHUB_TOKEN} 같은 환경변수나, 값 전체가 명령이어야 하는 !command를 쓸 수 있습니다.
• 잘못된 항목은 보고하고 건너뛰며 다른 서버 연결을 막지 않습니다.

다른 클라이언트(Claude Desktop, VS Code, Codex, OpenCode)에서의 마이그레이션 변환표도 공식 문서에 있습니다.

OAuth 로그인

Sentry처럼 OAuth를 쓰는 원격 서버에는 자격 증명을 적지 않습니다.

{
  "mcpServers": {
    "sentry": { "url": "https://mcp.sentry.dev/mcp" }
  }
}

비로그인 연결이 거부되면 /mcp가 로그인이 필요하다고 표시하고, 화면 선택이나 pi mcp login sentry로 인증할 수 있습니다. Pi가 인증 페이지를 열고 승인을 기다립니다. SSH처럼 브라우저가 브라우저가 다른 기계에 있으면 리디렉션된 URL을 로그인 화면에 붙여넣습니다. 토큰은 ~/.pi/agent/mcp-auth.json에 저장되고 만료 시 갱신됩니다. 동적 클라이언트 등록 대신 clientId/clientSecret/callbackPort를 직접 설정하거나 clientName으로 등록 이름을 바꿔 보내는 등 세부 옵션도 제공됩니다.

도구 노출 제어

각 서버 도구가 모델에게 도달하는 방식은 노출(exposure)로 결정됩니다.

노출	동작	일반적인 용도
codemode (기본)	codemode 스크립트에서만 호출 가능. 스크립트는 searchTools() 등으로 도구를 찾음	일반적인 MCP 서버
deferred	tool_search가 검색해 찾기 전까지 모델에 선언되지 않음	큰 서버를 검색 후 직접 호출
direct	내장 도구처럼 모델에 바로 선언	작고 자주 쓰는 도구 세트
hidden	등록되지만 도달 불가	잠가야 할 서버·도구

서버 단위 노출을 toolExposure로 도구 단위로 덮어쓸 수도 있습니다.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "exposure": "deferred",
      "toolExposure": {
        "search_code": "direct",
        "get_*": "codemode",
        "delete_*": "hidden"
      }
    }
  }
}

진단

• pi mcp list: 활성화된 모든 서버에 연결해 상태·도구·오류를 출력. 유효하지 않은 항목이나 미연결 서버가 있으면 종료 코드 1.
• /mcp: 실패한 stdio 서버의 stderr 꼬리말까지 전체 연결 오류 표시.
• 서버 로그는 ~/.pi/agent/mcp.log에 기록되며 5MB가 넘으면 mcp.log.1로 회전합니다.
• HTTP 네트워크 오류와 일시적 상태(408, 429, 5xx)는 두 번 재시도합니다.

리소스와 권한

서버가 리소스를 제공하면 list_mcp_resources, list_mcp_resource_templates, read_mcp_resource 도구가 추가됩니다. MCP 호출은 Pi의 도구 파이프라인을 그대로 통과하므로 확장의 tool_call·tool_result 핸들러와 권한 게이트가 MCP 도구에도 적용됩니다. 서버가 선언하는 readOnlyHint·destructiveHint 같은 어노테이션은 권한 확장 판단에 활용할 수 있습니다.

확장으로는 pi.registerMcpServer(name, config)를 사용해 현재 세션에만 서버를 추가할 수 있고, SDK 세션에서는 내장 확장을 직접 추가해야 합니다. 이런 세부 사항은 공식 문서의 Extensions·SDK 절을 참고하세요.