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 SSE (Server-Sent Events) and Streamable HTTP transports. Many popular services offer MCP endpoints with OAuth — docker-agent handles the authentication flow automatically.

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

Configuration

toolsets:
  - type: mcp
    remote:
      url: "https://mcp.example.com/sse"
      transport_type: "sse" # or "streamable"
      headers:
        Authorization: "Bearer token" # optional: static auth

For full configuration details, see the Tool Config page.

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).

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/sse"
          transport_type: "sse"
        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.