MCP 서버

**Schift MCP 서버(Model Context Protocol 서버)**는 Claude Code, Cursor, ChatGPT, Gemini 등 MCP를 지원하는 모든 클라이언트에 Schift 지식 레이어(knowledge layer)를 노출합니다. 이 서버는 Schift Cloud REST API를 감싸는 가벼운 래퍼(wrapper)로, MCP 도구 호출을 버킷(bucket) 검색, 문서 업로드, 메모리 검색, 워크플로우(workflow) 작업으로 변환합니다.

설치

npm에서 전역으로 패키지를 설치합니다.

npm install -g @schift-io/mcp

설치된 바이너리는 schift-mcp이며, Node.js 18 이상이 필요합니다.

npx로 바로 실행할 수도 있습니다.

npx -y @schift-io/mcp

인증

모든 MCP 도구는 사용자를 대신해 Schift Cloud API를 호출하므로, 서버에 Schift API 키가 필요합니다.

변수	필수 여부	기본값	설명
SCHIFT_API_KEY	stdio 및 셀프 호스티드(self-hosted) static 모드에서 필수	—	{apiUrl} 호출에 사용하는 Schift API 키입니다.
SCHIFT_API_BASE_URL	아니오	{apiUrl}	Schift API 오리진입니다.
SCHIFT_USER_ID	아니오	API 키에서 추론	소스 목록 조회용 명시적 사용자 ID입니다.
SCHIFT_DEFAULT_BUCKET	아니오	—	search와 schift_search의 기본 버킷입니다.
SCHIFT_MEMORY_BUCKETS	아니오	인증된 사용자의 메모리 레이어(memory layer)	메모리 검색에 강제로 사용할 쉼표로 구분된 버킷 목록입니다.
SCHIFT_MCP_AUTH_MODE	아니오	로컬은 static, 호스티드 배포는 upstream-bearer	원격 클라이언트 인증 방식입니다.
SCHIFT_MCP_BEARER_TOKEN	HTTP static 모드	—	셀프 호스티드 HTTP 서버에 클라이언트가 인증할 때 사용하는 토큰입니다.
SCHIFT_MCP_ALLOW_UNAUTHENTICATED	아니오	—	로컬 전용 무인증 HTTP 테스트를 위해 1로 설정합니다.

참고: {mcpUrl}/mcp의 Schift 호스티드 엔드포인트를 사용할 때는 Schift API 키나 OAuth 액세스 토큰을 MCP 클라이언트 베어러 토큰(bearer token)으로 전송하세요. 이 모드에서는 공유 SCHIFT_API_KEY를 사용하지 않습니다.

명령어

인자 없이 schift-mcp를 실행하면 stdio MCP 서버가 시작됩니다.

SCHIFT_API_KEY=sk_... SCHIFT_DEFAULT_BUCKET=docs schift-mcp

schift-mcp --http

/mcp에서 Streamable HTTP 서버를 시작합니다.

SCHIFT_API_KEY=sk_... \
SCHIFT_DEFAULT_BUCKET=docs \
SCHIFT_MCP_BEARER_TOKEN=your-mcp-client-token \
schift-mcp --http

기본 포트는 8787입니다. PORT나 SCHIFT_MCP_PORT로 변경할 수 있습니다. GET /healthz에서 상태 확인을 할 수 있습니다.

호스티드 다중 사용자 모드에서는 다음과 같이 실행합니다.

SCHIFT_MCP_AUTH_MODE=upstream-bearer schift-mcp --http

이 모드에서는 각 MCP 클라이언트가 Authorization: Bearer ... 형식으로 사용자의 Schift 토큰을 전송하면, 서버가 해당 토큰으로 Schift API를 호출합니다.

schift-mcp token

셀프 호스티드 HTTP 모드용 무작위 베어러 토큰을 생성합니다.

schift-mcp token

schift-mcp init --client <target>

특정 MCP 클라이언트에 맞는 설정을 출력합니다. 지원 대상은 claude, cursor, remote, chatgpt입니다.

schift-mcp init --client cursor --bucket docs
schift-mcp init --client claude --bucket docs
schift-mcp init --client remote --bucket docs --server-url https://mcp.your-domain.com/mcp

클라이언트 연동

Claude Code

~/.claude/mcp_servers.json에 추가합니다.

{
  "schift": {
    "command": "schift-mcp",
    "env": {
      "SCHIFT_API_KEY": "sk_...",
      "SCHIFT_DEFAULT_BUCKET": "docs"
    }
  }
}

Cursor

~/.cursor/mcp.json에 추가합니다.

{
  "mcpServers": {
    "schift": {
      "command": "schift-mcp",
      "env": {
        "SCHIFT_API_KEY": "sk_...",
        "SCHIFT_DEFAULT_BUCKET": "docs"
      }
    }
  }
}

ChatGPT 및 원격 MCP 클라이언트

Schift 호스티드 엔드포인트({mcpUrl}/mcp)를 사용합니다.

<your-mcp-host>/mcp
Authorization: Bearer <your-schift-api-key>

OpenAI Responses API 스타일 설정은 다음과 같습니다.

{
  "type": "mcp",
  "server_label": "schift",
  "server_url": "<your-mcp-host>/mcp",
  "headers": {
    "Authorization": "Bearer <your-schift-api-key>"
  },
  "allowed_tools": ["search", "fetch", "schift_search", "schift_memory_search"],
  "require_approval": "never"
}

셀프 호스티드 원격 서버의 경우 배포한 URL과 SCHIFT_MCP_BEARER_TOKEN 값을 사용합니다.

https://mcp.your-domain.com/mcp
Authorization: Bearer <your-mcp-client-token>

도구

search(query)

ChatGPT 호환 검색 별칭(alias)입니다. SCHIFT_DEFAULT_BUCKET 또는 사용자의 default 버킷을 검색하고 결과 ID, 제목, URL을 반환합니다. 공개 웹이 아닌 Schift 지식을 검색합니다.

fetch(id)

ChatGPT 호환 조회 별칭(alias)입니다. 같은 MCP 세션에서 search가 반환한 ID에 대해 캐시된 콘텐츠를 반환합니다.

schift_search(query, ...)

POST /v2/buckets/{bucket}/search를 통한 Schift 네이티브 버킷 검색입니다.

매개변수	타입	필수 여부	설명
query	string	예	검색어입니다.
bucket	string	아니오	버킷 ID 또는 이름입니다. 기본값은 SCHIFT_DEFAULT_BUCKET, 다음으로 default입니다.
collection	string	아니오	더 이상 사용하지 않는 bucket의 별칭입니다.
top_k	number	아니오	결과 개수입니다. 기본값은 10입니다.
filter	object	아니오	Schift 검색에 전달할 메타데이터(metadata) 필터입니다.
task	string	아니오	question_answering 같은 검색 지시 프리셋입니다.
rerank	boolean	아니오	재순위(reranking)를 활성화합니다.
rerank_top_k	number	아니오	재순위 결과 한도입니다.

schift_list_buckets()

API 키로 접근할 수 있는 버킷을 나열합니다. 사용자가 버킷 이름을 지정하지 않았을 때 검색 전에 사용하세요.

schift_list_bucket_collections(bucket)

버킷 내부의 하위 컬렉션(collection)을 나열합니다.

매개변수	타입	필수 여부	설명
bucket	string	예	버킷 ID 또는 이름입니다.

schift_upload_document(...)

텍스트 또는 base64 인코딩된 파일을 버킷에 업로드하고 비동기 수집을 큐에 넣습니다.

매개변수	타입	필수 여부	설명
bucket	string	아니오	버킷 ID 또는 이름입니다. 기본값은 SCHIFT_DEFAULT_BUCKET, 다음으로 default입니다.
filename	string	예	파일 이름입니다.
text / content	string	둘 중 하나 필수	UTF-8 텍스트 콘텐츠입니다.
content_base64	string	둘 중 하나 필수	바이너리 파일용 Base64 인코딩 콘텐츠입니다.
content_type	string	아니오	MIME 타입(MIME type)입니다. 예를 들어 text/plain 또는 application/pdf입니다.
metadata	object	아니오	문서 메타데이터입니다.
collection_id	string	아니오	선택적 하위 컬렉션 ID입니다.
ocr_strategy	string	아니오	Schift 업로드에 전달할 OCR 전략(OCR strategy)입니다.
chunk_size	number	아니오	청크 크기(chunk size) 오버라이드입니다.
chunk_overlap	number	아니오	청크 오버랩(chunk overlap) 오버라이드입니다.

참고: text와 content_base64를 동시에 전달하지 마세요. 둘 중 하나만 사용하세요.

메모리 도구

메모리 도구는 인증된 사용자의 메모리 레이어(memory layer)를 검색하며, Gmail, Notion, Slack, Linear, GitHub, Calendar, Drive 등 연결된 소스(source)를 포함합니다.

schift_memory_search(query, ...)

사용자의 메모리 버킷을 검색합니다.

매개변수	타입	필수 여부	설명
query	string	예	검색어입니다.
bucket	string	아니오	선택적 버킷 오버라이드입니다.
sources	string[]	아니오	gmail, notion, slack 등 소스 유형으로 필터링합니다.
tags	string[]	아니오	AND로 결합된 key:value 태그(tag) 필터입니다.
top_k	number	아니오	결과 개수입니다. 기본값은 20입니다.
temporal	string	아니오	before, after, between, as_of, latest 중 하나입니다.
temporal_start	number	아니오	시간적 시작 타임스탬프(timestamp)입니다.
temporal_end	number	아니오	시간적 종료 타임스탬프입니다.

기본적으로 이 도구는 POST /v1/memory/search를 호출하고 Schift가 사용자의 memory:{user_id}:* 버킷을 찾도록 합니다. 고정 버킷 목록이 필요할 때만 SCHIFT_MEMORY_BUCKETS를 설정하세요.

schift_memory_list_sources()

연결된 메모리 소스를 동기화 상태와 색인된 문서 수와 함께 나열합니다.

워크플로우 도구

워크플로우 도구는 설치된 Agent Workflow Protocol(AWP) 워크플로우를 Schift API를 통해 실행합니다.

schift_workflow_list()

조직에 설치된 워크플로우를 나열합니다. 상태가 published인 워크플로우만 실행할 수 있으며, draft 워크플로우는 Schift 콘솔에서 먼저 검토 및 게시되어야 합니다.

schift_workflow_dry_run(workflow_id, inputs?)

주어진 입력으로 워크플로우를 드라이런(dry-run)합니다. 부작용(side effects)은 발생하지 않고 블록 수준(block-level) 결과를 반환하여 검토할 수 있습니다.

schift_workflow_run(workflow_id, ...)

게시된 워크플로우를 실행합니다.

매개변수	타입	필수 여부	설명
workflow_id	string	예	워크플로우 ID입니다.
inputs	object	아니오	입력 이름을 키로 하는 워크플로우 입력값입니다.
mode	string	아니오	simulate(기본값)는 부작용을 준비만 하고, live는 실제 실행합니다.
approvals	object	아니오	블록별 인간 승인입니다. 예: {"review_issue": true}. 명시적 인간 승인 후에만 설정하세요.

워크플로우가 여전히 초안(draft)이면 도구는 status: "needs_review"와 함께 먼저 사람이 게시해야 한다는 메시지를 반환합니다.

예시

기본 버킷 검색

{
  "name": "schift_search",
  "arguments": {
    "query": "Q3 renewal terms",
    "top_k": 5
  }
}

소스와 태그로 메모리 검색

{
  "name": "schift_memory_search",
  "arguments": {
    "query": "acme renewal",
    "sources": ["gmail", "notion"],
    "tags": ["account:acme"],
    "top_k": 10
  }
}

문서 업로드

{
  "name": "schift_upload_document",
  "arguments": {
    "bucket": "docs",
    "filename": "notes.md",
    "text": "# Project notes\n\nKey decision: use v2 buckets.",
    "content_type": "text/markdown",
    "metadata": { "project": "migration" }
  }
}

워크플로우 실행

{
  "name": "schift_workflow_run",
  "arguments": {
    "workflow_id": "wf_abc123",
    "inputs": { "query": "Summarize latest Slack threads" },
    "mode": "simulate"
  }
}

보안 모델

• 로컬 stdio 모드: MCP 클라이언트가 환경에 SCHIFT_API_KEY를 담아 schift-mcp를 실행합니다. 별도의 MCP 베어러 토큰은 필요 없습니다.
• 셀프 호스티드 HTTP static 모드: SCHIFT_MCP_BEARER_TOKEN을 설정하고 클라이언트가 Authorization: Bearer <token>을 전송하도록 합니다. 서버는 Schift 호출에 고정 SCHIFT_API_KEY를 사용합니다.
• 호스티드 upstream-bearer 모드: MCP 클라이언트가 자체 Schift 토큰을 베어러로 전송합니다. 서버는 해당 토큰을 Schift API로 전달하며 공유 SCHIFT_API_KEY를 저장하지 않습니다.
• HTTP 모드는 SCHIFT_MCP_BEARER_TOKEN이 없으면 시작하지 않습니다. 단, SCHIFT_MCP_AUTH_MODE=upstream-bearer이거나 로컬 테스트용으로 SCHIFT_MCP_ALLOW_UNAUTHENTICATED=1을 설정한 경우는 예외입니다.

환경 변수(environment variable) 요약

변수	사용 모드	용도
SCHIFT_API_KEY	stdio, 셀프 호스티드 static	Schift API 인증입니다.
SCHIFT_API_BASE_URL	모든 모드	Schift API 오리진입니다.
SCHIFT_USER_ID	모든 모드	선택적 명시적 사용자 ID입니다.
SCHIFT_DEFAULT_BUCKET	모든 모드	검색 및 업로드용 기본 버킷입니다.
SCHIFT_MEMORY_BUCKETS	모든 모드	메모리 검색을 강제할 버킷입니다.
SCHIFT_MCP_AUTH_MODE	HTTP	static 또는 upstream-bearer입니다.
SCHIFT_MCP_BEARER_TOKEN	HTTP static	클라이언트-서버 간 베어러 토큰입니다.
SCHIFT_MCP_ALLOW_UNAUTHENTICATED	HTTP 로컬 테스트	베어러 토큰 검사를 건습니다.
PORT / SCHIFT_MCP_PORT	HTTP	서버 포트입니다. 기본값은 8787입니다.

참고

• Buckets
• Memory
• User Guide