agent MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

OAuth 2.1 + 스코프 기반 인증 기본 제공
핫 리로드: 설정을 수정하면 재시작 없이 새 업스트림이 나타남
모든 툴 호출에 감사 로깅
태그 기반 필터링으로 클라이언트마다 다른 툴 세트 노출
npx @1mcp/agent, 바이너리, Docker로 실행

라이브 데모

실제 사용 모습

agent.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "agent",
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "agent": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "agent"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add agent -- npx -y agent

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: agent

여러 팀을 위한 멀티 테넌트 MCP 게이트웨이 운영

👤 툴 요구가 다른 여러 스쿼드에 서비스를 제공하는 플랫폼 팀 ⏱ ~45 min advanced

언제 쓸까: 디자인과 엔지니어링이 다른 MCP를 필요로 하지만 게이트웨이 두 개를 운영하고 싶지 않을 때.

사전 조건

Node 20+ 또는 Docker가 있는 호스트 — 작은 VM이면 충분
OAuth IdP (로컬에서는 내장 사용 가능) — Dex, Auth0, Okta — OIDC를 지원하는 무엇이든

흐름

에이전트 설정에 스코프 정의

'design' 스코프는 figma와 davinci-resolve MCP를 노출하고, 'eng' 스코프는 github, sentry, postgres를 노출하는 에이전트 설정 초안을 만들어줘.✓ 복사됨

→ 스코프별 업스트림 매핑이 있는 설정
OAuth 연결

에이전트를 우리 Auth0 테넌트에 연결하고 그룹을 스코프에 매핑해줘.✓ 복사됨

→ 사용자가 자신의 스코프에 해당하는 툴만 보임
사용량 감사

지난 24시간의 툴 호출을 사용자별, 툴 이름별로 묶어서 보여줘.✓ 복사됨

→ 사용량 리포트

결과: 하나의 게이트웨이, 팀별 툴 뷰, 전체 감사 추적.

함정

스코프 설계가 금방 스파게티가 됨 — 툴별 스코프가 아닌 2-3개의 넓은 스코프(eng-read, eng-write, design)로 시작하세요
감사 로그가 디스크를 잠식 — 주 단위로 로테이트하거나 로그 애그리게이터로 전송하세요

함께 쓰기: github · sentry

핫 리로드로 커스텀 MCP 개발

👤 자체 MCP 서버를 반복 개발하는 빌더 ⏱ ~20 min intermediate

언제 쓸까: 새 MCP를 작성 중이고 변경할 때마다 IDE를 재시작하고 싶지 않을 때.

흐름

에이전트에 dev MCP 등록

에이전트 설정에 node ./my-mcp/dist/index.js를 로컬 dev MCP로 추가하고 'dev' 태그를 붙여줘.✓ 복사됨

→ 클라이언트에 툴이 나타남
편집, 저장, 재시도

툴을 변경했어. 재시작 없이 새 버전이 적용됐는지 알려줘.✓ 복사됨

→ 핫 리로드 확인

결과: MCP 개발의 빠른 이너 루프.

함정

클라이언트가 캐시하면 핫 리로드가 이전 툴 핸들을 남길 수 있음 — 큰 인터페이스 변경에서는 클라이언트를 재시작하세요

신뢰할 수 없는 업스트림 MCP 앞에 새니타이제이션 배치

👤 커뮤니티 MCP를 운영하는 보안 지향 관리자 ⏱ ~15 min intermediate

언제 쓸까: 커뮤니티 MCP를 시도하면서도 이중 입력 가드를 원할 때.

흐름

새니타이제이션 활성화

1mcp 에이전트에서 'community-x' 업스트림의 입력 새니타이제이션을 켜고, 과도한 페이로드를 반환하는 툴은 차단하도록 설정해줘.✓ 복사됨

→ 제한이 적용됨
검증

해당 업스트림의 툴을 호출해서 새니타이제이션 로그 항목을 확인해줘.✓ 복사됨

→ 로그에 새니타이즈된 호출 표시

결과: 커뮤니티 툴을 실험할 때 더 안전한 폭발 반경.

조합

다른 MCP와 조합해 10배 효율

agent + proxy-2

기능이 풍부한 1mcp와 최소한의 tbxark/mcp-proxy 비교

같은 호스트에서 1mcp/agent와 tbxark/mcp-proxy를 모두 실행하고 각각을 통한 툴 호출 지연을 비교해줘.✓ 복사됨

agent + jetski

1mcp 위에 분석 스택 구성

OAuth와 프롬프트 수준 분석을 모두 얻기 위해 1mcp/agent를 Jetski 뒤에서 실행해줘.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_tools	(none)	핸드셰이크 — 클라이언트가 처리	free
call_tool	name, args	모든 호출	1 upstream call
mcp_add	name, command, args	새 업스트림을 동적으로 추가 (관리자 전용)	free

비용 및 제한

운영 비용

API 쿼터: 자체 쿼터는 없음; 업스트림 쿼터에 종속
호출당 토큰: 작은 프록시 오버헤드
금액: 무료, MIT
팁: 쓰기 가능한 업스트림에서만 감사 로그를 활성화하세요 — 읽기 전용 로그는 이익 없이 디스크만 잠식합니다.

보안

권한, 시크릿, 파급범위

최소 스코프: OAuth 클라이언트 설정 + 업스트림 서버 자격증명

자격 증명 저장: 환경 변수와 설정 파일; 프로덕션에서는 시크릿 매니저 사용

데이터 외부 송신: 에이전트는 설정된 업스트림으로만 전달

절대 부여 금지: 최종 사용자에게 admin 스코프 — 플랫폼 팀 전용으로 유지

감사 로그를 로테이트하세요 — 장기 실행 에이전트는 GB 단위의 툴 호출 기록을 쌓습니다.
OAuth 스코프는 IdP 그룹 매핑만큼만 안전합니다; 누가 어느 그룹에 있는지 분기마다 감사하세요.

문제 해결

자주 발생하는 오류와 해결

Hot reload didn't pick up my config change

파일 워처가 마운트된 디렉터리에 권한이 있는지 확인(macOS의 Docker 바인드 마운트는 이벤트를 놓칠 수 있음). SIGHUP으로 폴백하세요.

확인: docker exec agent kill -HUP 1

OAuth token rejected

스코프 클레임이 설정된 스코프와 맞지 않음. 에이전트 로그의 클레임을 확인하고 설정을 맞추세요.

확인: jwt.io에서 JWT 디코드

Upstream MCP fails health check

업스트림 명령을 수동으로 실행해 stderr를 확인하세요. 에이전트 로그는 종료 코드만 보고합니다.

확인: docker exec agent sh -c '<upstream command>'

Tool list empty for a user

해당 사용자의 스코프가 어떤 툴의 필수 스코프 태그와도 맞지 않음.

확인: 설정의 스코프 매핑과 JWT 클레임 비교

대안

agent 다른 것과 비교

대안	언제 쓰나	단점/장점
tbxark/mcp-proxy	OAuth 없는 최소한의 Go 바이너리를 원할 때	인증, 핫 리로드, 스코프 없음
Jetski	풀 분석 대시보드와 DCR이 필요할 때	K8s + Postgres 인프라 필요

agent