본문으로 건너뛰기

MCP 서버

MCP 서버는 에이전트가 호출할 수 있는 도구를 제공합니다. 여기는 그런 서버를 모아 두는 레지스트리입니다. 서버를 등록하면 해당 도구를 워크플로의 작업 템플릿에 연결할 수 있습니다. 자세한 내용은 작업용 MCP 도구를 참고하세요.

관리 사이드바에서 MCP 서버를 열어 레지스트리를 관리합니다. 각 레코드에는 고유한 이름, 선택 사항인 설명, 태그, 그리고 양식의 나머지 부분을 결정하는 전송 방식이 있습니다.

전송 방식​

전송 방식필드개요
Streamable HTTP (기본값)URL, HTTP 헤더원격 서버입니다. 헤더는 모든 요청과 함께 전송되며, 보통 Authorization: Bearer …를 사용합니다. SSE 전용 서버는 지원하지 않습니다.
stdio명령, 인수, 환경 변수백엔드의 자식 프로세스로 실행되는 서버입니다. 예를 들면 npx와 ["-y", "@modelcontextprotocol/server-everything"] 조합입니다. npx와 uvx 모두 사용할 수 있습니다.
스크립트언어, 소스, 패키지, 환경 변수직접 작성한 Python 또는 JavaScript 코드입니다. 공개 함수 하나하나가 도구가 됩니다. 스크립트 작성을 참고하세요.

기존 서버의 전송 방식을 바꾸면 이전 전송 방식의 필드는 지워집니다. stdio 서버에 URL을 넣거나, 원격 서버에 명령을 넣거나, 어느 쪽에든 소스 코드를 넣는 식으로 형태가 뒤섞인 레코드는 거부됩니다.

⚠️ stdio 서버를 등록한다는 것은 선택한 명령을 백엔드 컨테이너 안에서 실행한다는 뜻입니다. 실행 주체는 컨테이너의 비특권 사용자입니다. 다른 MCP 서버 쓰기 작업과 마찬가지로 개발자 역할이 있어야 합니다. 인수는 셸을 거치지 않고 목록 형태로 프로세스에 전달되며, 자식 프로세스는 안전한 소수의 환경 변수와 직접 설정한 환경 변수만 물려받습니다. 백엔드 자체의 API 키와 데이터베이스 URL은 자식 프로세스에서 볼 수 없습니다.

스크립트 작성​

스크립트 서버를 사용하면 패키지를 게시하지 않아도 직접 작성한 함수를 도구로 만들 수 있습니다. 전송 방식에서 스크립트를 선택하고 언어를 고른 다음 소스에 코드를 붙여 넣습니다.

소스는 코드 편집기입니다. 선택한 언어에 맞춰 코드에 색을 입히고 줄 번호를 표시하며, Tab 키로 들여쓰기를 합니다. Tab 키로 다음 필드로 넘어가려면 먼저 Esc 키를 누르세요. 입력하는 동안 문제가 있는 곳에 밑줄이 표시되며, 밑줄 위에 마우스를 올리면 무엇이 잘못되었는지 볼 수 있습니다.

밑줄의미예
빨간색 물결선구문 오류입니다. 스크립트를 실행할 수 없습니다닫히지 않은 괄호, 철자가 틀린 키워드
앰버색 물결선실수일 가능성이 있습니다도구가 될 함수가 없음, docstring이 없는 Python 함수 또는 타입 힌트가 없는 매개변수, 패키지가 비어 있는데 표준 라이브러리 외부에서 가져오는 import, description이 없는 JavaScript 함수
강조 색 물결선참고 사항입니다inputSchema가 없는 JavaScript 함수

밑줄은 조언일 뿐 저장을 막지 않습니다. 저장 시 수행되는 검사는 아래에서 설명합니다.

PythonJavaScript
도구가 되는 함수최상위에 정의된 함수 중 이름이 _로 시작하지 않는 모든 함수입니다. import한 함수는 노출되지 않습니다.내보낸 함수(export function, export async function) 중 이름이 _로 시작하지 않는 모든 함수입니다. 기본 내보내기(default export)는 노출되지 않습니다.
도구 이름함수 이름내보낸 이름
설명docstring함수의 description 속성
인수타입 힌트에서 읽습니다. 지원하는 타입은 str, int, float, bool, list, dict, Literal[...], X | None입니다. 그 밖의 타입이거나 타입 힌트가 없는 매개변수는 모든 값을 허용합니다.함수의 inputSchema 속성(JSON Schema)입니다. 없으면 도구가 모든 인수를 허용합니다.
도구 호출 방식인수를 이름으로 전달합니다인수를 담은 객체 하나를 전달합니다
에이전트가 받는 값반환값입니다. 문자열은 그대로, 그 밖의 값은 JSON으로 전달됩니다반환값입니다. 문자열은 그대로, 그 밖의 값은 JSON으로 전달됩니다
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
export function add({ a, b }) {
return a + b;
}
add.description = "Add two numbers.";
add.inputSchema = {
type: "object",
properties: { a: { type: "number" }, b: { type: "number" } },
required: ["a", "b"],
};

두 언어 모두에 다음 규칙이 적용됩니다.

  • 표준 라이브러리(Python 자체 모듈 또는 Node.js 내장 node: 모듈)는 항상 사용할 수 있습니다. 그 밖의 라이브러리는 패키지에 등록해야 합니다.
  • 함수에서 발생한 오류는 실패한 도구 호출로 에이전트에 전달되며, 오류 메시지도 함께 전달됩니다.
  • print() 또는 console.log()의 출력은 에이전트가 아니라 서버 로그로 전송됩니다.
  • 환경 변수는 os.environ["NAME"] 또는 process.env.NAME으로 읽을 수 있으며, 자격 증명을 레코드에 남기지 않기에서 설명하는 자리 표시자를 사용할 수 있습니다.
  • 소스에는 최대 30,000자까지 입력할 수 있습니다.
  • Python 코드에 구문 오류가 있으면 저장할 때 줄 번호와 함께 거부됩니다. JavaScript는 저장할 때 검사하지 않으므로, 불러올 수 없는 스크립트를 찾아내려면 저장하기 전에 테스트하세요.
  • 불러오기에 실패한 스크립트(설치되지 않는 패키지, 구문 오류, 최상위에서 발생한 오류)도 시작은 됩니다. 이 스크립트에 대한 모든 도구 호출은 불러오기를 막은 오류로 실패하며, 도구를 확인하면 사용할 수 없는 서버로 표시됩니다.

⚠️ 스크립트는 stdio 서버와 같은 곳에서 같은 제한을 받으며 실행됩니다.

패키지 추가​

다른 서비스와 통신하는 스크립트에는 대개 해당 서비스의 클라이언트 라이브러리가 필요합니다. 예를 들어 AWS라면 boto3입니다. 패키지에 한 행에 하나씩 등록하고, 소스에서 평소처럼 import합니다.

언어패키지 작성 방법예
PythonPyPI의 패키지 이름입니다. 버전을 함께 지정할 수도 있습니다boto3, boto3==1.40.0, requests>=2.32
JavaScriptnpm 레지스트리의 패키지 이름입니다. @버전을 함께 지정할 수도 있습니다is-number, @aws-sdk/client-s3@3
import boto3


def list_buckets() -> list[str]:
"""List the S3 buckets the configured credentials can see."""
return [b["Name"] for b in boto3.client("s3").list_buckets()["Buckets"]]
  • 패키지는 해당 목록으로 스크립트가 처음 시작될 때 설치되며, 시간이 걸릴 수 있습니다. 이후 시작할 때는 설치된 사본을 재사용합니다. 정확히 같은 패키지를 등록한 스크립트끼리는 사본 하나를 공유합니다.
  • 설치할 수 없는 패키지(철자가 틀린 이름, 존재하지 않는 버전)가 있으면 스크립트를 불러올 수 없습니다. 도구 불러오기에 설치 프로그램의 오류가 표시됩니다.
  • 서버 하나에 패키지를 최대 20개까지 등록할 수 있으며, 각 패키지는 200자 이내이고 문자, 숫자 또는 @로 시작해야 합니다.
  • 설치하려면 스크립트가 실행되는 곳에서 패키지 레지스트리에 연결할 수 있어야 합니다. 대신 비공개 인덱스에서 설치하려면 설치 프로그램의 변수를 환경 변수에 설정하세요. Python은 UV_INDEX_URL, JavaScript는 NPM_CONFIG_REGISTRY입니다.

스크립트 테스트​

환경 변수 아래의 테스트 실행 패널은 양식에 입력된 그대로 스크립트를 저장하지 않고 실행합니다. 에이전트가 사용하려고 하기 전에 불러올 수 없는 스크립트를 찾아내는 데 사용하세요.

  1. 도구 불러오기를 클릭합니다. 현재 양식에 있는 소스, 패키지, 환경 변수로 스크립트가 시작됩니다.
  2. 도구에서 도구를 선택합니다. 인수에 도구가 선언한 모든 인수가 null로 채워집니다.
  3. JSON 객체인 인수를 편집하고 실행을 클릭합니다.
표시 내용의미
도구 목록스크립트를 불러왔습니다. 이 도구들이 노출됩니다
도구 목록 대신 빨간색 텍스트스크립트를 불러올 수 없습니다. 이 텍스트가 불러오기를 막은 오류입니다
이 스크립트는 도구를 제공하지 않습니다.스크립트를 불러왔지만 도구가 될 함수가 없습니다
출력에 도구의 출력호출에 성공했습니다
출력에 빨간색 텍스트도구에서 오류가 발생했습니다. 이 텍스트가 오류 메시지입니다
인수는 JSON 객체여야 합니다. 또는 잘못된 JSON: …인수가 JSON 객체가 아닙니다. 아무것도 실행되지 않았습니다

환경 변수의 자리 표시자는 저장된 서버와 똑같이 확장되므로, 테스트 실행은 같은 자격 증명으로 같은 서비스에 연결됩니다. 테스트 실행은 실제 호출입니다. 도구가 하는 일은 실제로 일어납니다.

자격 증명을 레코드에 남기지 않기​

⚠️ 헤더와 환경 변수에 직접 입력한 값은 평문으로 저장되고 상세 페이지에 그대로 표시됩니다. 자격 증명을 직접 입력하는 대신 등록된 시크릿의 항목 하나를 참조하세요.

자리 표시자사용 위치예
${secret:name/key}모든 헤더 값 또는 환경 변수 값Authorization: Bearer ${secret:github/token}
AWS_ACCESS_KEY_ID: ${secret:aws-credentials/AWS_ACCESS_KEY_ID}
${gcp-token:name/key}${secret:…}와 같습니다. Google Cloud 자격 증명 JSON이 들어 있는 항목에 사용합니다Authorization: Bearer ${gcp-token:gcp-credentials/GOOGLE_CREDENTIALS_JSON}
${env:NAME}인수 항목에서 이 서버의 환경 변수를 이름으로 지정합니다--token ${env:API_KEY}

자리 표시자는 연결할 때만 확장되므로 자격 증명이 저장된 레코드에 나타나지 않습니다.

${env:NAME}은 해당 환경 변수 자체의 ${secret:…}가 확장된 다음에 확장됩니다. 덕분에 시크릿에서 가져온 값을 명령줄 플래그로 재사용할 수 있으며, 프로세스 환경에서 읽지 않고 인수로 받는 실행기에 유용합니다. NAME은 환경 변수의 키여야 합니다. 존재하지 않는 키에 대한 참조는 해당 키를 제거해서 남은 참조를 포함해 저장할 때 거부됩니다.

Google Cloud MCP 서버​

Google의 관리형 MCP 서버(GKE의 서버 등)는 API 키를 허용하지 않습니다. 모든 요청에 Google Cloud ID의 OAuth 2.0 액세스 토큰이 있어야 하는데, 토큰의 수명은 1시간뿐이라 시크릿에 붙여 넣어 둘 수도 없습니다. ${gcp-token:name/key}가 이 문제를 해결합니다. 항목의 값 대신 그 값으로 새로 발급한 액세스 토큰으로 확장되며, 토큰이 만료되면 자동으로 갱신됩니다. 항목에는 다음 두 형태 중 하나의 자격 증명 JSON을 넣습니다.

자격 증명얻는 방법토큰 범위
서비스 계정 키서비스 계정을 만들고 MCP Tool User와 도구에 필요한 권한을 부여한 다음 JSON 키를 다운로드합니다cloud-platform
OAuth 클라이언트 ID와 시크릿OAuth 클라이언트(데스크톱 앱)를 만들어 JSON을 다운로드한 다음, 자신의 컴퓨터에서 gcloud auth application-default login --client-id-file=<해당 JSON> --scopes=https://www.googleapis.com/auth/cloud-platform을 한 번 실행하고 로그인합니다. 생성된 application_default_credentials.json의 내용을 붙여 넣습니다동의한 범위

어느 쪽이든 JSON 전체를 시크릿의 항목 하나로 붙여 넣고, 위의 예처럼 서버의 Authorization 헤더에서 참조합니다. 워크플로를 누가 시작했든 모든 도구 호출은 그 하나의 ID로 실행됩니다. 형식이 잘못된 자격 증명이나 Google이 더 이상 허용하지 않는 자격 증명은 참조 대상이 없는 ${secret:…}와 마찬가지로 연결을 실패하게 합니다.

MCP 레지스트리에서 등록​

목록 페이지의 레지스트리 찾아보기 버튼을 누르면 공식 MCP 레지스트리를 검색하는 대화 상자가 열립니다.

  1. 이름으로 검색합니다. 결과에는 A2Flow가 등록할 수 있는 서버만 표시됩니다. 즉 Streamable HTTP 엔드포인트가 있는 서버와 stdio로 실행할 수 있는 npm 또는 PyPI 패키지로 게시된 서버입니다.
  2. 하나를 선택합니다. 연결 정보와 서버에 필요한 헤더 또는 환경 변수 키가 미리 채워진 상태로 만들기 양식이 열립니다.
  3. 시크릿 값을 입력하고 저장합니다.

패키지에서 실행 명령으로의 변환은 최선의 추정이므로 저장하기 전에 검토하세요. A2Flow가 검색할 레지스트리는 구성 참조에서 다른 곳으로 지정할 수 있습니다.

서버 도구 확인​

작업 템플릿 양식은 서버가 제공하는 도구(이름, 설명, 입력 스키마)를 서버에 조회합니다. 단, 선택한 서버 하나에만 조회하며 레지스트리 전체를 한꺼번에 조회하지는 않습니다. 연결하거나 실행할 수 없는 서버는 도구 목록 대신 그 사실을 표시합니다.

서버 삭제​

작업이나 작업 템플릿에 서버의 도구가 하나라도 연결되어 있으면 해당 서버를 삭제할 수 없습니다. 먼저 연결을 제거하세요.