<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Work on this issue](https://contributors.gitlab.com/manage-issue?action=work&projectId=278964&issueIid=595938) - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=595938) </details> <!--IssueSummary end--> ## Summary As noted in various user feedback ([1](https://gitlab.com/gitlab-org/gitlab/-/work_items/593219#note_3190963628), [2](https://gitlab.com/gitlab-org/gitlab/-/work_items/593219#note_3190934732)), we need to improve our product docs for MCP servers in the AI catalog to better explain how to configure MCPs. The current **MCP servers in the AI Catalog** docs explain UI locations and field meanings but don’t fully guide users through the end-to-end setup flow, especially across **GitLab.com vs self-managed**. We should enhance the docs to make it clear **who can do what on which platform**, and **what exact steps** are required to get from “I want my agent to talk to X” to a working configuration. **Target doc**: https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/ai_catalog_mcp_servers/ ## Problem to solve Today’s docs: - Describes the feature as **GitLab.com, Premium/Ultimate, experimental** and shows the MCP tab, Automate > MCP servers, and available servers list. - Mentions constraints (vetted/partner server, remote only, HTTP transport only, auth = None or OAuth 2.0). - Shows how to “Add an MCP server”, “Connect an MCP server to a custom agent”, and “Authenticate with an MCP server”. However, from the feedback issue: - Users are being explicitly asked whether “adding MCP servers to your instance catalog [was] clear and manageable, or did you hit friction?”, which implies the current docs are not sufficient as a **step-by-step setup guide**. - There is an important split between **GitLab.com** (curated, seeded list) and **self-managed** (admins can register servers under AI Catalog > MCP) that isn’t called out strongly in the doc, even though it’s central to how the feature actually behaves. - It’s not obvious from the docs **what “vetted or partner MCP server / arbitrary URLs are not allowed” actually means** in practice, or what a user should do if the server they want is not available. As a result, admins and users may: - Expect to be able to point GitLab at arbitrary MCP URLs and be confused when they can’t. - Not understand why certain servers are available on GitLab.com vs self-managed, or how to request new ones. - Struggle to connect an MCP server end-to-end (third-party prerequisites, catalog entry, agent association, OAuth) from a single, linear guide. ## Proposal Update the **MCP servers in the AI Catalog** doc to be more scenario- and platform-oriented, with explicit constraints and worked examples. ### 1. Add an “End-to-end setup overview” section Introduce a short, high-level “How MCP servers work with custom agents” section near the top that explains: - **Step 1: Identify your platform and role** - On **GitLab.com**: you use a **curated, GitLab-managed list** of MCP servers in the global catalog. - On **self-managed**: **instance admins** can register MCP servers directly under **AI Catalog → MCP**. - **Step 2: Register or select an MCP server** - GitLab.com: pick from the seeded list. - Self-managed: add the MCP server via the MCP tab (name, URL, transport = HTTP, auth type). - **Step 3: Associate MCP servers with a custom agent** - Use the agent edit form to attach one or more MCP servers so the agent can use their tools. - **Step 4: Authenticate (if needed)** - Use **Automate → MCP servers** at group/project level to complete OAuth where required. - **Step 5: Use the agent** - Clarify that once configured, agents can invoke any tools available on their associated MCP servers. This should read like a narrative, not just per-section field docs. ### 2. Make the GitLab.com vs self-managed behavior explicit Clarify and emphasize: - **GitLab.com** - MCP support is via a **curated, GitLab-seeded catalog**. - Users **cannot** register arbitrary servers; they can choose from the available ones. - Link to the **roadmap / seeding issue** for which servers are planned or available. - **Self-managed** - Instance admins can **register MCP servers in their own AI Catalog under AI Catalog → MCP**. - These instances still must respect the same technical constraints (remote, HTTP-only, auth model). - Make sure the “Offering: GitLab.com” line and the content reflect how self-managed scenarios are supposed to work (e.g., by adding explicit self-managed notes or cross-linking to Duo Agent Platform / AI Catalog docs that cover self-managed usage). ### 3. Clarify “vetted or partner MCP server” and “no arbitrary URLs” In the **Prerequisites** or a new **Requirements** section: - Restate and explain: - The MCP server must be a **vetted or partner MCP server**. - **Arbitrary URLs are not allowed**. - It must be a **remote MCP server**, not a local/stdio one. - Add a short explanation of what “vetted/partner” means at a high level (e.g., “provided by an official partner or explicitly approved by GitLab / your admin, rather than any random endpoint”) and how that maps to: - The **curated list** on GitLab.com. - Admin responsibilities on self-managed. - Add a **“If the server you want isn’t available”** note that: - Points GitLab.com users at the seeding roadmap / dedicated issue for proposing new servers. - Suggests how self-managed admins can decide whether to add a given MCP server (e.g., security review, validation in staging, etc.), at least at a high level. ### 4. Pull the technical constraints into a single checklist Add a concise **“Technical requirements for MCP servers”** subsection that consolidates: - ✅ Must implement **Model Context Protocol** over **remote HTTP**. - ✅ Must expose an **HTTP** endpoint (`Transport: HTTP`). - ❌ **SSE and stdio** transports are not supported. - ✅ Supported authentication types: **None** or **OAuth 2.0**. - ✅ Optional support for **OAuth 2.0 Dynamic Client Registration**; when present, GitLab can auto-register itself as an OAuth client. - ✅ Must be **remote**, not a local MCP client packaged alongside GitLab. This avoids users having to infer constraints from multiple scattered sections. ### 5. Add at least one worked example (plus mini-examples) Expand the **Available MCP servers** section into something closer to “examples”: - **Full worked example: Atlassian (Jira/Confluence) MCP** - Step through: - Atlassian admin setup (AI Settings → Rovo MCP Server, add `https://gitlab.com/**` to trusted domains). - Confirm/select the Atlassian MCP server in AI Catalog → MCP. - Associate it with a custom agent. - Authenticate via Automate → MCP servers. - Call out any gotchas (e.g., who needs to be Jira/Confluence admin). - **Shorter examples: Linear and Context7** - For each, show: - Which auth model they use (e.g., OAuth vs None). - The basic steps: select server → attach to agent → (if applicable) complete OAuth. - Keep these brief but concrete enough that a user can verify they followed the right path. These examples should intentionally show at least one simple “no auth” server and one “OAuth + admin prerequisites” server. ### 6. Cross-link to feedback and roadmap for discoverability - In the **Introduction** or **Related topics**: - Link clearly to the **MCP servers feedback issue (593219)** as the place to: - Report setup friction. - Request additional seeded servers. - Link to the **seeding / roadmap work item (591969)** for GitLab.com so users understand what “curated servers” currently exist and what’s planned. ## Implementation checklist - [ ] Add an **“End-to-end setup overview”** section that walks through platform choice (GitLab.com vs self-managed), registering/choosing a server, associating it with an agent, and authenticating. - [ ] Make **GitLab.com vs self-managed** behavior explicit (who can add servers, where, and with what constraints). - [ ] Introduce or expand a **“Requirements” / “Technical requirements”** section that clearly lists: vetted/partner-only, remote MCP, HTTP-only, auth types, and dynamic client registration behavior. - [ ] Add a **“If the server you want isn’t available”** note that points to the seeding / roadmap issue and feedback issue. - [ ] Create at least one **worked example** (e.g., Atlassian MCP) plus short examples for one “no-auth” server (Context7) and one OAuth server (e.g., Linear). - [ ] Ensure the **Available MCP servers** section reflects the curated nature of GitLab.com’s catalog and links to the roadmap/feedback issues for additions. - [ ] Double-check that the **Offering / Tier / Prerequisites** lines are consistent with the updated platform behavior and any self-managed notes.