이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

MCP 통합

상태: 활성 범위: 현재 상태 최종 검토: 2026-10-09 담당: ax-code 런타임

AX Code는 외부 도구, 프롬프트, 자원을 위해 Model Context Protocol 서버에 연결할 수 있습니다. MCP는 강력하므로, AX Code는 MCP 구성과 MCP가 제공한 내용을 신뢰 경계로 취급합니다.

실험적인 브라우저 브리지는 별도의 경로입니다. 격리된 Chrome 창을 띄우고, 페이지가 WebMCP로 등록한 도구를 호출할 수 있습니다. 터미널 UI에서 켭니다. 단계와 승인 계층은 WebMCP 브라우저 브리지에 있습니다.

신뢰 모델

사용자가 제어하는 구성 출처의 MCP 항목은 기본적으로 신뢰됩니다.

전역 사용자 구성
관리 구성
명시적인 AX_CODE_CONFIG
인라인 AX_CODE_CONFIG_CONTENT
권한이 있는 로컬 런타임 경로를 통한 런타임 추가

공유되거나 네트워크에서 발견된 출처의 MCP 항목은 기본적으로 신뢰되지 않습니다.

프로젝트 ax-code.json
작업 트리 .ax-code 구성
원격 well-known 구성

신뢰되지 않은 MCP 항목은 needs_trust로 표시됩니다. 그 항목이 신뢰되기 전에는 AX Code가 로컬 MCP 명령을 띄우거나, 원격 MCP URL에 연결하거나, MCP 도구 스키마를 노출하거나, 프롬프트/자원을 나열하거나, OAuth를 시작하지 않습니다.

신뢰 명령

MCP 상태를 나열합니다.

ax-code mcp list

서버 지문 하나를 신뢰합니다.

ax-code mcp trust <name>

현재 서버 지문의 신뢰를 철회합니다.

ax-code mcp untrust <name>

현재 프로젝트 구성에서 구성된 서버를 제거합니다.

ax-code mcp remove <name> --force

전역 구성에서 제거하려면 --global를 추가합니다. 제거는 고른 범위 안에 머물며, 그 서버가 거기에 없으면 실패합니다. 확인하기 전에 대상 경로를 검토하려면 --force을 생략합니다.

신뢰는 저장소 밖에 저장되며, 현재 프로젝트와 서버 지문으로 범위가 정해집니다. 명령, URL, OAuth 모드, 헤더, 명시적인 환경 값처럼 중요한 MCP 구성이 바뀌면 이전 신뢰는 무효가 됩니다.

런타임 권한

신뢰는 MCP 서버가 런타임에 참여하는 것만 허용합니다. 개별 MCP 도구 호출은 여전히 AX Code 권한을 거칩니다.

MCP 도구 권한 키는 기존의 <server>_<tool> 형태를 유지합니다. AX Code가 도구 인수에서 안정적인 자원을 식별할 수 있으면, 더 좁은 패턴으로 묻습니다. 예를 들면 다음과 같습니다.

url:https://api.example.com/resource
uri:mcp-resource
path:src/index.ts
repo:owner/name
db:database.table

알 수 없는 인수 형태는 기본적으로 넓은 지속 승인을 제안하지 않고 묻습니다.

프롬프트, 자원, 내용

MCP 프롬프트와 자원은 신뢰하지 않는 컨텍스트입니다. AX Code는 권한으로 MCP 프롬프트 사용과 MCP 자원 읽기를 제한하고, 가져온 텍스트를 신뢰하지 않는 MCP 내용으로 표시하며, 큰 텍스트는 모델 컨텍스트에 들어가기 전에 자릅니다.

MCP 도구 메타데이터와 출력도 제한됩니다.

너무 큰 스키마는 도구를 노출하기 전에 거부됩니다.
긴 설명은 상한이 있습니다.
로컬 MCP stderr 로그는 줄이고, 분명한 비밀 패턴은 가립니다.
모델이 보는 MCP 도구 내용은 사용자에게 보이는 도구 출력과 같은 잘림 결과를 사용합니다.

HTML과 웹 개발을 위한 Playwright MCP

HTML 게임, 웹 앱, 또는 루트에 index.html이 있는 프로젝트에서 작업하면, AX Code는 그 프로젝트를 웹 프로젝트로 감지하고 에이전트가 브라우저를 자율적으로 열지 못하게 합니다. 대신 에이전트는 변경을 보고하고 사용자가 새로 고칠 때까지 기다립니다.

스크린샷 기반 검증에는 Playwright MCP 서버를 연결합니다.

ax-code mcp list --discover   # auto-suggests playwright in web projects

또는 ax-code.json에 수동으로 추가합니다.

{
  "mcp": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--cdp-url", "http://localhost:9222"]
    }
  }
}

CDP 붙이기 모드

Chrome이 --remote-debugging-port=9222와 함께 실행 중이면 AX Code가 자동으로 감지하고 CDP 붙이기 모드로 연결합니다. 에이전트는 새 창을 열거나 초점을 빼앗지 않고 browser_screenshot으로 실시간 탭을 캡처할 수 있습니다.

CDP를 켠 채 Chrome을 실행하려면 다음을 사용합니다.

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

헤드리스 폴백

열린 Chrome CDP 포트가 없으면 @playwright/mcp이 헤드리스 Chromium 인스턴스를 띄웁니다. 스크린샷은 여전히 TUI 안에 인라인으로 렌더링됩니다.

전역 설치

@playwright/mcp이 전역으로 설치되어 있으면(npm install -g @playwright/mcp), AX Code는 playwright-mcp 바이너리를 직접 사용하며, npx을 통해 실행하지 않습니다. 처음 사용할 때 더 빠릅니다.

보안 참고

Playwright MCP 서버는 브라우저에 대해 상당한 능력을 얻습니다. 프로젝트 구성(ax-code.json)에서 오면, ax-code mcp trust playwright으로 신뢰를 명시적으로 부여하기 전에는 신뢰되지 않습니다. 전역 사용자 구성 항목은 첫 승인 뒤에 자동으로 연결됩니다.

서버 모드

변경하는 MCP HTTP 경로에는 일반적인 서버 보호에 더해 프로세스 로컬 런타임 권한 헤더가 필요합니다. 이것은 MCP 서버를 추가, 연결, 연결 해제, 인증하는 것 같은 로컬 런타임 제어 동작을 보호합니다. 읽기 전용 MCP 상태는 GET /mcp를 통해 계속 사용할 수 있습니다.

Figma MCP

Figma Desktop

Figma 데스크톱 앱에서 디자인 파일을 열고, Dev Mode로 전환한 다음, 검사 패널에서 데스크톱 MCP 서버를 켭니다. 앱만 연다고 서버가 켜지지는 않습니다. Figma 데스크톱 설정 안내를 보십시오.

AX Code 구성에 이 항목을 추가합니다.

{
  "mcp": {
    "figma-desktop": {
      "type": "remote",
      "url": "http://127.0.0.1:3845/mcp",
      "allowLoopback": true,
      "oauth": false
    }
  }
}

프로젝트 구성이면 항목을 검토하고 신뢰를 부여합니다.

ax-code mcp trust figma-desktop

type: "remote"는 이 머신의 HTTP 서버를 포함해 HTTP/SSE 전송을 고릅니다. type: "local"은 stdio를 쓰는 서브프로세스를 고릅니다.

루프백 HTTP MCP 정책

allowLoopback의 기본값은 false입니다. true로 설정하면 구성된 스킴, 호스트 이름, 포트에서만 localhost, 127.0.0.1 또는 [::1]의 HTTP(S)를 허용합니다. 자격 증명이 들어 있지 않은 루프백 URL이 필요합니다. 공유 프로젝트 항목은 여전히 신뢰가 필요합니다. 이 옵션을 켜면 그것 없이 이전에 부여한 신뢰는 무효가 됩니다.

리디렉션, SSE 메시지 엔드포인트, OAuth 요청은 같은 오리진에 머물러야 합니다. 다른 포트, 공개 목적지, 사설 네트워크 주소, 클라우드 메타데이터 엔드포인트는 계속 차단됩니다. localhost에 대한 DNS 응답은 모두 루프백 주소여야 하며 연결마다 고정됩니다. 외부 OAuth 발급자에 의존하는 로컬 서비스는 이 옵션이 지원하지 않습니다. Figma Desktop에는 oauth: false를 사용합니다.

연결이 거부되면 데스크톱 MCP 서버가 켜져 있고 포트 3845에서 수신 중인지 확인합니다. localhost으로 바꾸거나 OAuth만 끄는 것은 루프백 접근을 켜지 않습니다.

Figma 원격 OAuth (mcp.figma.com)

Figma의 호스트된 엔드포인트는 https://mcp.figma.com/mcp입니다. Figma는 MCP Catalog의 승인된 클라이언트를 요구합니다. 클라이언트 개발자는 Figma의 원격 접근 등록 요구 사항을 따라야 합니다.

거부된 동적 등록은 일반적인 Figma OAuth 애플리케이션을 만들거나 그 클라이언트 ID와 비밀을 제공한다고 해결되지 않습니다. 사용할 수 있으면 승인된 MCP 통합을 위해 발급된 자격 증명을 사용합니다. 공식 엔드포인트가 등록을 거부하면 AX Code는 Catalog 요구 사항을 보고합니다. 루프백 접근이 호스트된 서버 승인을 부여하지는 않습니다.

토큰 기반 템플릿

내장 figma 템플릿은 별도의 figma-developer-mcp 패키지를 FIGMA_API_KEY과 함께 실행합니다. Figma의 공식 Desktop 및 호스트된 MCP 서버와는 다릅니다.