IMA 다중 사용자 MCP 서버

Tencent IMA OpenAPI(노트 + 지식 베이스)의 다중 사용자 MCP 프록시.

• 요청 헤더 자격 증명 전달: 각 요청에 사용자 자신의 Client ID + API Key 포함, 서버는 저장하지 않음

• 무상태 Streamable HTTP: 다중 사용자 동시성 자연 격리, 재시작 무감각, 수평 확장 가능

• client_id 화이트리스트 허용: 등록된 Client ID만 사용 가능; 파일 수정 즉시 적용, 재시작 불필요

• 17개 도구: 노트 6 + 지식 베이스 9 + raw_call 폴백 + 연결 확인

설계 배경

이 프로젝트는凭空 설계된 것이 아니라, 커뮤니티의 기존 방안을 "다중 사용자화 리팩터링"한 것으로, 설계 흐름은 다음과 같다.

해결하려는 문제: Tencent IMA의 노트/지식 베이스 기능은 원래 단일 사용자 단일 인스턴스로만 사용할 수 있었다. 목표는 이를 하나의 서버로 만들어 동시에 여러 사용자에게 서비스하는 것 — 각자 자신의 Tencent 계정 자격 증명으로 접속하고, 서버는 누구의 키도 보관하지 않으며, 기기 변경·사용자 변경 시 운영 부담이 없다.

조사한 세 가지 경로(다중 사용자 MCP Server의 주요 패턴):

세 가지 핵심 참조 자료:

1. amberpepper/ima-mcp(TypeScript) — 이 프로젝트의 15개 IMA OpenAPI 인터페이스 경로, 요청 본문 구조, 업스트림 요청 헤더 명명(ima-openapi-clientid / ima-openapi-apikey / ima-openapi-ctx)의 직접적인 청사진이며, 모두 하나씩 대조 확인했다. 이 프로젝트는 그 도구 설계를 복제하되, "단일 사용자 stdio + 환경 변수 자격 증명" 아키텍처를 "다중 사용자 Streamable HTTP + 요청 헤더 자격 증명"으로 교체했다. 서버 로컬 경로에 의존하는 파일 업로드 도구는 원격 사용자에게 의미가 없어 제거했다.

2. LRGEX/notion-mcp — "모든 도구의 첫 단계에서 요청 헤더로 자격 증명을 가져오고, 요청마다 새 클라이언트를 만들어 쓰고 버리는" 무상태 다중 사용자 패러다임의 출처.

3. github/github-mcp-server — 공식 MCP 서버의 컨테이너화, 도구 그룹화, 엔지니어링 형태 참고; 그 다중 사용자가 OAuth에 의존하는 방식은 의도적으로 버리고, "사용자가 Key를 직접 보유, 제로 스토리지"의 초간단 모드를 택했다.

인증 설계의 두 차례 진화:

• 초안은 2계층 인증(관리자 허용 토큰 + 사용자 IMA 자격 증명)이었으나, 이후 자격 증명이 곧 신원으로 단순화 — 사용자의 IMA 자격 증명 자체가 유일한 신원 자격이며, Tencent 인터페이스의 응답(401)이 곧 검증이므로 별도의 허용 토큰을 발급하지 않는다;

• 더 나아가 client_id 화이트리스트로 진화: 로컬에서 "자격"(허용 여부)을 판단하고, Tencent에서 "진위"(Key 유효 여부)를 판단하여 두 관문이 각자 역할을 한다. api_key 대신 client_id 화이트리스트를 선택한 이유는 IMA의 API Key는 만료/재설정될 수 있지만 client_id는 안정적인 신원 식별자이기 때문이다.

프로토콜 기반: MCP Streamable HTTP 전송 + 무상태 모드(stateless_http=True), 각 요청은 독립적이고 세션 테이블이 없어 동시성과 수평 확장을 자연스럽게 지원한다.

Related MCP server: Productboard MCP — Curve & Flex

빠른 배포(Docker Compose)

cd ~/ima-mcp-server
cp -n .env.example .env
# 编辑 config/allowed_clients.txt，把允许的 client_id 写进去（每行一个）
docker compose build
docker compose up -d
docker compose logs -f --tail=50   # 看到 "就绪" 与白名单条数即成功

서비스는 127.0.0.1:8044에서 수신 대기한다(같은 머신의 리버스 프록시/공개망 접근 계층만 접근 가능). 외부에 직접 노출해야 한다면 docker-compose.yml의 ports를 "0.0.0.0:8044:8044"로 변경한다(그리고 링크에 TLS가 있는지 확인).

화이트리스트 관리

• config/allowed_clients.txt 편집: 각 줄에 client_id 하나, # 뒤는 주석

• 수정 즉시 적용(파일 수정 시간 기준 핫 리로드), 컨테이너 재시작 불필요

• 파일이 존재하지만 유효한 항목이 없으면 → 모든 요청 거부(fail-closed)

• 파일을 삭제하고 IMA_ALLOWED_CLIENTS가 비어 있으면 → 개방 모드

스모크 테스트

bash tests/smoke.sh <你的client_id> <你的api_key>

예상: 1) initialize 성공; 2) tools/list가 17개 도구 반환; 3) 자격 증명 없이 호출하면 자격 증명 누락 오류 반환; 4) 실제 자격 증명이면 status ok 반환.

클라이언트 구성(Chatbox 예시)

• 유형: 원격 MCP / Streamable HTTP

• URL: http://<服务器IP>:8044/mcp(업스트림에 TLS가 연결되어 있으면 https 사용)

• 요청 헤더:

  • X-Ima-ClientId: 사용자 자신의 client_id

  • X-Ima-ApiKey: 사용자 자신의 api_key

참고: IMA API Key는 만료될 수 있습니다. 만료되면 https://ima.qq.com/agent-interface에서 재설정하고 클라이언트 요청 헤더를 업데이트하세요.

업그레이드

docker compose build && docker compose up -d

자주 묻는 질문

라이선스

MIT