Implement Client ID Metadata Documents (CIMD) for MCP Authorization (SEP-991)

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

The MCP 2025-11-25 specification introduces URL-based client registration using OAuth Client ID Metadata Documents (CIMD) as a replacement for the problematic Dynamic Client Registration (DCR) approach.

What is CIMD?

  1. Clients can provide their own client ID that is a URL pointing to a JSON document the client manages, describing properties of the client.
  2. Authorization servers fetch and cache this document and use it as the source of truth for the client’s metadata (for example, name, redirect URIs, logo, documentation links).

This eliminates the need for:

  1. Public DCR APIs that require rate limiting and security measures.
  2. Unbounded database growth from client registrations.
  3. Complex OAuth proxy implementations.
  4. Manual client registration by users or IT teams.

Benefits

  1. No more Dynamic Client Registration complexity in the common path.
  2. Clients control their own metadata in a self-service way.
  3. Authorization Servers do not need to implement DCR endpoints for primary flows.
  4. Simpler integration path for new MCP clients and servers.
  5. Better enterprise adoption story through more predictable and governable client identities.

Implementation requirements

  1. Support URL-based client IDs.
  2. Implement client metadata document fetching, parsing, and caching.
  3. Update authorization flows to support CIMD-based registration.
  4. Maintain backward compatibility with pre-registered clients.
  5. Maintain backward compatibility with existing DCR-based clients as a fallback.
  6. Implement security measures for:
    1. SSRF risks when fetching client metadata documents.
    2. Localhost and loopback redirect URI handling.
  7. Make the client selection logic pluggable enough that different MCP client types (for example, editors, CLIs, agents) can be supported without reintroducing client sprawl.

Product requirements for MCP usage

To address operational and governance concerns for MCP, CIMD support should be paired with specific behavioral requirements:

  1. One logical client per tool

    1. For a given MCP tool (for example, a specific editor extension or agent implementation), GitLab should treat the CIMD URL as the stable identity for that tool.
    2. The authorization server should avoid creating a new OAuth client for every connection or user session.
    3. DCR should remain available only as a backward-compatibility mechanism, not as the primary path for MCP tooling.

  2. Reuse instead of proliferation

    1. When an MCP client connects and presents a known CIMD URL, GitLab should reuse the existing OAuth client associated with that CIMD URL.
    2. Subsequent users of the same MCP tool should authorize against the same logical client, rather than triggering the creation of additional instance-level OAuth applications.
    3. Where appropriate, pre-registered clients can be mapped to known CIMD URLs so that existing enterprise governance patterns continue to work.

  3. Clear admin control and visibility

    1. Instance administrators should have a way to see which MCP tools are known to the instance, including:
      1. The CIMD URL for each tool.
      2. The corresponding OAuth application entry or entries.
      3. Whether the client was introduced through pre-registration, CIMD, or DCR.
    2. Administrators should be able to:
      1. Enable or disable specific MCP tools at the instance level.
      2. Revoke or rotate a client used by an MCP tool without needing to inspect a large number of nearly identical applications.
    3. The design should make it easy to distinguish:
      1. A small, governed set of MCP-related clients that many users can connect to.
      2. Any legacy or fallback dynamic clients created via DCR.

Priority order (as per spec)

  1. Use pre-registration, if available.
  2. Use the CIMD-based approach.
  3. Use the DCR-based approach (backward compatibility).
  4. Ask the user to provide client details.

References

Related to

Epic: &20387

Edited by 🤖 GitLab Bot 🤖