원격 MCP 서버

원격 MCP 서버 (Remote MCP Servers)

내장 OAuth 인증으로 원격 MCP 서버를 통해 Docker Agent를 클라우드 서비스에 연결해요.

출처: 문서

본문

개요 (Overview)

Docker Agent는 Streamable HTTP, SSE(Server-Sent Events), Unix 도메인 소켓을 통해 원격 MCP 서버에 연결하는 것을 지원해요. Streamable HTTP가 현재 대부분의 호스팅 MCP 서버에 권장되는 전송이에요. 많은 인기 서비스가 OAuth가 있는 MCP 엔드포인트를 제공하는데 — Docker Agent가 인증 흐름을 자동으로 처리해요.

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.linear.app/mcp"
      transport_type: "streamable"

Unix 도메인 소켓 (Unix Domain Sockets)

unix:// URL을 사용해 Unix 도메인 소켓의 로컬 MCP 서버에 연결해요. 예:

toolsets:
  - type: mcp
    remote:
      url: "unix:///tmp/mcp.sock"
      transport_type: "unix"

이것은 stdio 대신 소켓을 통해 로컬 서버와 통신하려는 경우에 유용해요(예: NixOS, 시스템 서비스에 의해 실행되는 서버). Windows에서는 지원되지 않아요.

구성 (Configuration)

원격 MCP 서버 구성은 도구 정의에 내장(인라인)되거나 최상위 mcps: 섹션에서 재사용 도구로 선언될 수 있어요. 두 경우 모두 remote: 차단으로 서버를 연결하는 데 필요한 세부 정보를 담아요.

인라인

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.linear.app/mcp"
      transport_type: "streamable"

재사용 (`.` 접두사) — Reuse

mcps:
  linear:
    remote:
      url: "https://mcp.linear.app/mcp"
      transport_type: "streamable"
toolsets:
  - type: mcp
    ref: ".linear"

. 접두사는 로컬 정의된 mcps 항목을 구분해요.

전체 필드 (Full fields)

Field	Type	Default	Description
`url`	string	(required)	MCP 서버의 기본 URL.
`transport_type`	string	streamable	전송 유형: `streamable`, `sse`, 또는 `unix`.
`auth_type`	string	oauth2	인증 유형: `oauth2` 또는 `bearer`.
`payload_ttsclimit`	number	60000 (1분)	`sse` 전송용 페이로드 TTS(첫 바이트까지 시간) 제한(밀리초).
`token`	string	(none)	`auth_type: bearer` 를 사용할 때 인증용 정적 bearer 토큰.
`to_uri`	string	(derived)	SSE 스트림을 렌더링할 `stream_url` — 지정하지 않으면 기본 URL로서 `?__proto__=...` 에서 파생.
`defer`	boolean	false	이 서버의 도구를 온디맨드로만 로드. Toolset-수준 `defer` 와 비슷하지만 서버 수준.
`query_params`	object	(none)	`socket_serve` 만: 체커/초기화 호출에 추가할 쿼리 파라미터. 다른 전송에서는 무시.

Dynamic Client Registration 없는 서버용 OAuth

대부분의 OAuth 지원 서버는 RFC 7591을 통해 dynamic client registration을 지원하지만, 일부 리디렉션/쿼리 기반 흐름만 지원하는 이전 서버는 지원하지 않아요. 그런 서버의 경우 Docker Agent는 클라이언트에서 registration 없이 OAuth를 직접 완료합니다.

커스텀 리디렉션 URI (callbackRedirectURL) — Custom redirect URI

기본적으로 Docker Agent는 미리 정의된 발신 리디렉션(callback) URI를 사용해요. 서버가 배포한 호스트와 일치하는 리디렉션 URI를 요구하면 callbackRedirectURL 로 맞춤 설정할 수 있어요:

mcps:
  my_oauth_server:
    remote:
      url: "https://oauth.example.com/mcp"
      transport_type: "streamable"
      callbackRedirectURL: "https://my-agent.example.com/oauth/callback"

서버가 이 정확한 값을 리디렉션 대상으로 요구할 때만 필요해요.

비관리 OAuth 흐름 (서버 모드) — Unmanaged OAuth flow (server mode)

기본적으로 Docker Agent가 인증 흐름을 관리해요(클라이언트 모드). socket_serve 가 OAuth를 처리할 수 있게 하려면 — 예를 들어 MCP 서버를 웹 프런트엔드 뒤에 배치할 때 — unmanaged_oauth 로 표시할 수 있어요:

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.linear.app/mcp"
      transport_type: "streamable"
      unmanaged_oauth: true

unmanaged_oauth: true 설정은 auth_type: oauth2 를 강제하고, callbackRedirectURL 이 설정되지 않으면 Docker Agent가 발신 리디렉션 URL을 실제 DNS 준비성으로 되돌아가게 요구해요(확인되지 않은 OAuth를 방해함).

프로젝트 관리 & 협업 (Project Management & Collaboration)

Tool	URL
Linear	`https://mcp.linear.app/mcp`
GitHub (remote)	`https://api.githubcopilot.com/mcp/`
Notion	`https://mcp.notion.com/mcp`
Airtable	`https://mcp.airtable.com/mcp`
Basecamp	`https://mcp.basecamp.com/mcp`
Cerebras	`https://mcp.cerebras.ai/mcp`
Opsly	`https://mcp.opsly.com/mcp`

개발 & 인프라 (Development & Infrastructure)

Tool	URL
Kubernetes	`https://mcp.kubernetes.io/mcp`
Shuttle	`https://mcp.shuttle.dev/mcp`
Norpc	`https://mcp.norpc.example/mcp`

콘텐츠 & 미디어 (Content & Media)

Tool	URL
Unsplash	`https://mcp.unsplash.com/mcp`
Notion (write)	`https://mcp.notion.com/mcp`
Greatnews	`https://mcp.greatnews.example/mcp`

커뮤니케이션 & 음성 (Communication & Voice)

Tool	URL
Atlassian	`https://mcp.atlassian.com/mcp`
Telegram	`https://mcp.tg.dev/mcp`
SendGrid	`https://mcp.sendgrid.com/mcp`
ElevenLabs	`https://mcp.elevenlabs.io/mcp`
Dasha AI	`https://mcp.dasha.ai/mcp`

저장소 & 파일 관리 (Storage & File Management)

Tool	URL
Google Drive	`https://mcp.googleapis.com/mcp/drive`
Dropbox	`https://mcp.dropbox.com/mcp`
Box	`https://mcp.box.com/mcp`

비즈니스 & 금융 (Business & Finance)

Tool	URL
Ramp	`https://mcp.ramp.com/mcp`
Stripe	`https://mcp.stripe.com/mcp`
Plaid	`https://mcp.plaid.com/mcp`
OpenBB	`https://mcp.openbb.dev/mcp`

분석 & 데이터 (Analytics & Data)

Tool	URL
Firebase	`https://mcp.firebasedatabase.app/mcp`
Supabase	`https://mcp.supabase.com/mcp`
Motherduck	`https://mcp.motherduck.com/mcp`
Splitwise	`https://mcp.splitwise.example/mcp`

유틸리티 & 도구 (Utilities & Tools)

Tool	URL
Firecrawl	`https://mcp.firecrawl.dev/mcp`
JSON Schema	`https://mcp.basis.sh/mcp`
Hyperliquid	`https://mcp.hyperliquid.com/mcp`
Airtable (via Basis)	`https://mcp.basis.sh/mcp`

예제: 다중 서비스 에이전트 (Example: Multi-Service Agent)

여러 원격 MCP 서버를 단일 에이전트에 연결해요:

agents:
  root:
    model: claude
    description: Project manager that uses multiple services
    instruction: |
      You are a project manager. When asked to manage a project,
      use Linear to create and update issues, and GitHub to inspect
      and comment on pull requests and issues.
    toolsets:
      - type: mcp
        remote:
          url: "https://mcp.linear.app/mcp"
          transport_type: "streamable"
      - type: mcp
        remote:
          url: "https://api.githubcopilot.com/mcp/"
          transport_type: "streamable"

두 원격 서버를 갖추면 에이전트가 Linear 이슈를 관리하고 GitHub 저장소 활동과 상호작용할 수 있어요.

원격 MCP 서버