Remote MCP Servers

Connect docker-agent to cloud services via remote MCP servers with built-in OAuth authentication.

Overview

Docker Agent supports connecting to remote MCP servers over Streamable HTTP, SSE (Server-Sent Events), and Unix domain sockets. Streamable HTTP is the current recommended transport for most hosted MCP servers. Many popular services offer MCP endpoints with OAuth — docker-agent handles the authentication flow automatically.

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

Unix Domain Sockets

Use a unix:// URL to connect to an MCP server listening on a local Unix socket. This is useful when running docker-agent inside a container and exposing an MCP server from the host via a bind-mounted socket:

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

The path after unix:// is the absolute path to the socket file. Configured headers are forwarded over the socket connection. OAuth discovery is not supported for Unix socket URLs.

Configuration

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.example.com/mcp"
      transport_type: "streamable" # or "sse" for legacy servers
      headers:
        Authorization: "Bearer token" # optional: static auth
    # Optional: use only for trusted internal/private MCP or OAuth endpoints.
    allow_private_ips: true

For full configuration details, see the Tool Config page.

Set allow_private_ips: true on a remote MCP toolset only when the MCP server or its OAuth registration/token endpoints intentionally resolve to private, loopback, or link-local addresses. The default blocks those OAuth helper requests to reduce SSRF risk.

OAuth for servers without Dynamic Client Registration

Most remote MCP servers that require OAuth support Dynamic Client Registration (RFC 7591) — no configuration is needed, docker-agent handles the flow for you.

For servers that do not support DCR, provide explicit OAuth credentials with the oauth: block:

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.example.com/mcp"
      transport_type: "streamable"
      oauth:
        clientId: "my-app-client-id"
        clientSecret: "my-app-client-secret" # optional (public clients may omit)
        callbackPort: 8765                   # optional; picks a free port otherwise
        scopes:                              # optional; server-specific
          - read
          - write

Secrets should be stored in a credential helper or environment variable rather than committed — see Secrets for interpolation patterns.

Custom redirect URI (callbackRedirectURL)

Some authorization servers require the OAuth redirect_uri to be HTTPS or to match a URL that was pre-registered during app creation — neither of which plays nicely with a locally-bound loopback address such as http://127.0.0.1:8765/callback.

To work around this, set callbackRedirectURL to a public URL that redirects back to the local callback server. The literal placeholder ${callbackPort} is substituted with the actual port the local callback server is listening on (either callbackPort when set, or the randomly-assigned port otherwise).

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.example.com/mcp"
      transport_type: "streamable"
      oauth:
        clientId: "my-app-client-id"
        callbackPort: 8765
        # Advertise this URL to the authorization server. The external
        # service at redirect.example.com is expected to 302-redirect the
        # browser to http://127.0.0.1:8765/callback preserving the query
        # string (code, state, …).
        callbackRedirectURL: "https://redirect.example.com/cb?port=${callbackPort}"

The local callback server still listens on the loopback interface on callbackPort; only the redirect_uri advertised to the authorization server changes.

Validation rules:

• The URL must be absolute (scheme + host) once ${callbackPort} has been substituted.
• Only http and https schemes are accepted.
• http is only allowed when the host is a loopback address (127.0.0.1, ::1, localhost); any other host must use https to avoid exposing the authorization code on the wire (RFC 8252 §7.3).

Unmanaged OAuth flow (server mode)

When running docker-agent serve api (no local browser, no callback server), the runtime delegates the OAuth dance to the connected client via an MCP elicitation. There are two sub-behaviors, selected by the --mcp-oauth-redirect-uri flag:

• --mcp-oauth-redirect-uri=<URL> set (recommended for hosts like Docker Desktop): the runtime generates state + PKCE + (optional) Dynamic Client Registration in-process, builds the full authorize URL, and emits an elicitation whose Meta includes:

  Key	Value
  docker-agent/type	"oauth_flow"
  docker-agent/server_url	The MCP server URL (for display / favicon)
  docker-agent/authorize_url	The full URL the client should open in the user's browser
  docker-agent/state	The state value the client must echo back when replying
  auth_server	Issuer of the authorization server
  auth_server_metadata	RFC 8414 authorization-server metadata document
  resource_metadata	RFC 9728 protected-resource metadata document

  The client opens the browser at the URL provided in the docker-agent/authorize_url meta field, receives the OAuth callback at whatever endpoint the configured redirect_uri resolves to (typically a host-controlled bouncer that 302s into a deeplink), and replies to the elicitation with accept and Content = {"code": "...", "state": "..."}. The runtime verifies the state, exchanges the code at the token endpoint (using the same redirect_uri for RFC 6749 §4.1.3 binding), stores the token, and replays the original MCP request with Authorization: Bearer ....

• Flag not set (client-driven): the runtime emits the elicitation meta below and expects the client to drive the OAuth flow itself (PKCE, DCR, token exchange) and reply with Content = {"access_token": "...", "refresh_token": "...", ...}:

  Key	Value
  docker-agent/type	"oauth_flow"
  docker-agent/server_url	The MCP server URL (for display / favicon)
  auth_server	Issuer of the authorization server
  auth_server_metadata	RFC 8414 authorization-server metadata document
  resource_metadata	RFC 9728 protected-resource metadata document

The client-driven {access_token, ...} reply shape is still accepted on the --mcp-oauth-redirect-uri path too: a client that prefers to do the exchange itself can ignore the docker-agent/authorize_url/docker-agent/state keys.

A per-toolset callbackRedirectURL (in the YAML) overrides the runtime-wide --mcp-oauth-redirect-uri for that toolset.

Project Management & Collaboration

Development & Infrastructure

Content & Media

Communication & Voice

Storage & File Management

Business & Finance

Analytics & Data

Utilities & Tools

Example: Multi-Service Agent

Combine multiple remote MCP servers in a single agent:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    instruction: |
      You help manage projects and deployments.
    toolsets:
      - type: mcp
        remote:
          url: "https://mcp.linear.app/mcp"
          transport_type: "streamable"
        instruction: Use Linear for issue tracking.
      - type: mcp
        remote:
          url: "https://api.githubcopilot.com/mcp"
          transport_type: "sse"
        instruction: Use GitHub for code and PRs.
      - type: mcp
        remote:
          url: "https://mcp.vercel.com/"
          transport_type: "sse"
        instruction: Use Vercel for deployments.