GitLab GraphQL MCP Tool Builder
Build a new GraphQL-backed MCP server tool in gitlab-org/gitlab — the *Tool +
*Service pair under app/services/mcp/tools/. Scope: GraphQL tools only. Bias to
minimal, idiomatic change: copy the closest existing GraphQL tool, swap the
query/variables/schema, register it — don't invent abstractions. Mirror existing
patterns, verify everything against the live schema (never guess field/arg/auth
details), and produce a tool + service + specs that pass rubocop and rspec.
Canonical source of truth (read first; this skill distills them and adds the
gotchas): doc/development/duo_agent_platform/mcp/_index.md (tool-proposal process,
versioning, aliases, aggregated tools) and
doc/development/duo_agent_platform/mcp/graphql_integration.md (the two-layer
architecture and the .graphql-file convention). If this skill and the docs
disagree, the docs win — tell the user so they can refile an update here.
Before writing any tool: the proposal process is required. New tools go through an
MCP Tool Proposal issue
reviewed by the interim mcp-tool-review-board. Confirm the proposal exists (or is
waived) before building — tool proliferation degrades every agent's context, so the
bar for a new tool is deliberately high.
What you're building
A GraphQL MCP tool is two classes + one registration line, executed in-process:
MCP client (JSON-RPC POST /api/v4/mcp, "tools/call")
→ API::Mcp::Base (auth: PAT/token with `mcp` scope)
→ Handlers::CallTool (looks up tool, sets current_user)
→ Manager.get_tool(name:) (registry lookup)
→ <Name>Service (picks version, defines agent-facing schema)
→ execute_graphql_tool(arguments)
→ <Name>Tool (holds the operation + variable mapping)
→ GitlabSchema.execute(query, variables:, context:) ← the actual call
→ process_result (shape output → MCP Response)
<Name>Tool (.../<area>/<name>_tool.rb) — subclass of Mcp::Tools::GraphqlTool;
loads the operation from a .graphql file, maps params → variables, optionally
reshapes output.
<Name>Service (.../<area>/<name>_service.rb) — subclass of
Base::GraphqlService; the agent-facing wrapper defining input_schema,
description, and annotations.
- Registration — one line in
manager.rb GRAPHQL_TOOLS:
'<tool_name>' => ::Mcp::Tools::<Area>::<Name>Service.
Key fact: GraphqlTool#execute calls GitlabSchema.execute(...) — the same schema
the HTTP /api/graphql endpoint uses, run as current_user, so the tool inherits
the caller's permissions (don't re-check perms). Field-by-field detail of both classes,
the naming convention, the mapping cheat-sheet, and the mutation (write) deltas are in
references/tool-anatomy.md.
GraphQL operations live in .graphql files — not inline strings
Every operation is a committed file under app/graphql/queries/mcp/<domain>/, loaded
by GraphqlTool.load_graphql(<relative path>). This is enforced, not stylistic:
- The
Mcp/UseGraphqlQueryFile RuboCop rule fails on an inline string / HEREDOC
passed as graphql_operation: and points you at load_graphql.
- Files here are validated against
GitlabSchema at build time by
spec/graphql/all_queries_spec.rb, so an operation that drifts from the schema fails
CI. An inline operation skips that safety check.
Rules for the file:
- Name it
<name>.query.graphql or <name>.mutation.graphql in a subdirectory
mirroring the tool's domain (merge_requests/, work_items/, labels/).
- First line must be
# @feature_category: mcp_server — the
graphql_require_feature_category lint rule fails without it.
- Verb-first operation name to match
app/graphql/queries (getMergeRequestNotes,
createNote — not MergeRequestNotes).
- Load with the direct
load_graphql(...) form, not a lambda. -> { load_graphql(...) }
rereads the file every request. The one exception is an operation composed at load
time (e.g. a query built from EE-overridden fragments) — build it in a method and
reference it with a lambda (graphql_operation: -> { build_query }).
Tool naming and consolidation conventions (!245400)
Note: Existing tools (get_merge_request_notes, create_merge_request_note, etc.)
predate these conventions. Copy them for the implementation pattern but name and
structure your new tool per the conventions below.
Every tool name uses a verb_object shape. The verb signals the operation class:
get_ — single object (e.g. get_merge_request)
list_ — collection (e.g. list_merge_requests)
save_ — create or update field mutations; presence of id determines which.
Mark create-required params as required in the schema.
Intentional exception: when a lifecycle action has its own mutation (e.g. retry, cancel)
and targets the resource this tool creates, fold it behind an action param rather than
adding a tool. Route on the resource's own ID, not the parent's, and state the rule in the
tool description (save_pipeline: no pipeline_id creates, pipeline_id + action
transitions). Annotations are per tool, so the whole tool inherits the most destructive
action's destructiveHint; note the fold in the proposal.
delete_ — delete operations only; never fold into save_.
add_ or other verbs — reserved for objects without a typical CRUD shape (e.g. add_commit).
Facets fold into get_, not separate tools. Sub-reads scoped to one parent object
(notes, diffs, commits, pipelines) become an include: enum on the parent's get_ tool
(e.g. get_merge_request with include: diffs|commits|notes|pipelines|conflicts), not
separate list_* tools. Independent collections that can be queried on their own get
their own list_ tool (e.g. list_merge_requests, list_pipelines).
Resource identification is always url OR project_id + resource internal ID —
never folded into a single id. url is the single-value convenience path; project_id
iid/sha/etc. is the explicit path. When both are supplied they are cross-validated.
Pagination mirrors the endpoint, not a forced convention:
- GraphQL-backed tools → native cursor pagination (
first, after); return pageInfo
with endCursor and hasNextPage. Never hardcode the page size numbers: splat
Mcp::Tools::Concerns::CursorPagination.input_schema_params(items:) into the service's
input_schema, and use its paginated_first in the tool.
- REST-backed tools → offset pagination (
page, per_page); return metadata with
page, per_page, has_more.
Document intentional exceptions in the tool proposal when a tool deliberately breaks
a convention (non-standard verb, second write tool on one resource).
Recipe — build a new GraphQL MCP tool
- Confirm a tool proposal exists (MCP Tool Proposal issue / review board — see top), and
build exactly what it specifies — under-ship, don't over-ship. An MCP
input_schema is
versioned (_index.md): adding a parameter later is additive and safe, but removing one is a
breaking change needing a new version plus multi-version support. So a param you're unsure
about is far cheaper to add later than to remove. If the issue is project-scoped, ship
project-scoped; capability it doesn't ask for is a separate proposal, not a bonus. Resist
"compatibility" surface too — if this tool replaces/aliases another that still runs (see
Renaming, tool-anatomy.md), the old tool is the compatibility path and this one need not
absorb its parameter shape.
- Verify the GraphQL field exists — before writing anything. Check that the schema
already exposes a field covering your use case:
- Type file:
app/graphql/types/<resource>_type.rb (or project_type.rb /
group_type.rb) — scan for the field name.
- Resolver:
app/graphql/resolvers/<resource>_resolver.rb — scan argument
lines to confirm the filter args you need exist.
- Console fallback:
GitlabSchema.query_type.fields.keys.grep(/keyword/) or
Types::MergeRequestType.fields.keys to list available fields at runtime. See
references/graphql-api-model.md for more.
- ⚠️ If the field doesn't exist: stop and alert the user. A missing field means
the tool isn't buildable without a schema addition — a separate MR requiring its
own GraphQL review. Do not invent or guess field names.
- Copy the closest existing GraphQL tool — tool + service +
.graphql + specs. A
full read example is in references/worked-example.md.
- Write the operation in GraphiQL/console until it returns what you want (variables
for all inputs; paginate connections), then save it as a
.graphql file per the
rules above. Never inline it.
- Tool class:
graphql_operation: load_graphql('<domain>/<file>.graphql'); set
operation_name to the root field in register_version — or override it as an
instance method if the root field varies at call time (e.g. project-or-group tools —
see references/tool-anatomy.md); map params → variables in build_variables;
reshape in process_result if needed.
- Service class (
< Base::GraphqlService): write input_schema (agent-facing args
required; do not add additionalProperties), description, annotations
(readOnlyHint correct — it drives pre-approval); point graphql_tool_class at the Tool.
- Agent-as-consumer review — review name/description/schema/output as the LLM sees
them, before specs. See references/agent-consumer-review.md.
- Register in
manager.rb GRAPHQL_TOOLS.
- Update the
list_tools specs — required, both files. Each holds its own copy of the
same expected_annotations hash, so both need the identical
'<tool_name>' => { 'readOnlyHint' => … } entry under the matching comment bucket (write
non-destructive / write destructive / read-only) — annotations only, neither file asserts
description or inputSchema. Both also assert every service under the MCP tools tree is
registered in Mcp::Tools::Manager, so they catch a skipped step 7.
spec/requests/api/mcp/handlers/list_tools_spec.rb — its annotations example is guarded
unless: Gitlab.ee?.
ee/spec/requests/api/mcp/handlers/list_tools_spec.rb — unguarded, and its hash also
lists EE-only tools.
Only one of the two annotations examples runs in a given pipeline, so green specs never
prove you updated both files.
- Unit specs for the Tool and the Service. Lock the service
input_schema as a
whole with a single expect(...).to eq({ … }) (a full version-lock, like
list_merge_requests_service_spec), not property-by-property — it catches accidental
schema drift across versions. Don't re-assert readOnlyHint here: the list_tools
specs (step 8) already cover annotations, so a per-tool "is marked read-only" example
is redundant. Match the sibling MCP specs' feature_category: :mcp_server on both files.
- Update user docs:
doc/user/model_context_protocol/mcp_server_tools.md.
bundle exec rubocop + bundle exec rspec the changed files; fix failures. Also
run bundle exec rspec spec/graphql/all_queries_spec.rb — it validates your new
.graphql file against GitlabSchema, so a bad field/arg fails here. It does not check
id selections — a missing id passes rspec and only fails the graphql-verify eslint CI
job (see Gotchas), which can't run locally without the schema dump. Green specs are not proof
the query lints.
Gotchas (learned the hard way)
- Inline operation → RuboCop failure.
Mcp/UseGraphqlQueryFile rejects a
string/HEREDOC as graphql_operation:; use a .graphql file via load_graphql.
- Missing
# @feature_category: → lint failure. Every .graphql file needs it as
the first line (graphql_require_feature_category).
load_graphql in a lambda rereads the file per request. Use the direct form; a
method + lambda is only for an operation composed at load time (EE fragments).
- Don't hand-set
additionalProperties. SchemaDefaults applies false
automatically (!243352); setting it manually is redundant and will be flagged.
readOnlyHint changes behavior, not just docs. The pre-approved tool list is
derived from it (!231431); a write wrongly marked readOnlyHint: true runs without
confirmation.
operation_name is the root field, not the query Name label. process_result
digs result.dig('data', operation_name). { project(...) { … } } → 'project'.
- Unused declared variable → validation error. Don't declare
$x you don't reference.
- Undeclared argument → validation error. Only pass args the field defines (verify
with
.arguments.keys).
iid is a String in GitLab GraphQL, not Int — iid: "1".
- Client-side post-filtering breaks pagination — prefer a real server-side arg; if
none exists, consider cutting the input from v1 (see references/graphql-api-model.md).
position (DiffPositionType) is null for non-diff notes — expected.
- Select
id on every object type that has one — it is lint-mandated, not padding.
@graphql-eslint/require-selections (error, applies to **/*.graphql) requires id on
project, group, connection nodes, author, etc. spec/graphql/all_queries_spec.rb
passes without them — it only checks schema-correctness — so the only thing that catches a
missing id is the graphql-verify CI job, which needs the schema dump and does not run
locally. Never remove an id to "slim" a payload; a reviewer (human or agent) suggesting that
is wrong.
- A root
oneOf/anyOf silently disables additionalProperties: false. SchemaDefaults
skips composition schemas (tool-anatomy.md), so expressing "exactly one of url/project_id"
as a schema oneOf quietly stops unknown args being rejected. Enforce mutual exclusivity in
Ruby instead (in resolve_*, raising on zero-or-many), and keep the schema composition-free so
the strictness guard survives. State the "exactly one of" rule once in the tool description,
not in each property.
find_project! / find_group! fold authorization in — "forbidden" and "missing" are indistinguishable.
ResourceFinder#find_project! and #find_group! check Ability.allowed? after the DB lookup.
If the record is missing or the caller lacks the required ability, both raise the same
"'<id>' not found or inaccessible" StandardError. This is intentional: a distinct
"Access denied" message would let an authenticated caller enumerate private projects/groups
by comparing error strings. Do not add a separate authorization check after calling these
finders — the check is already inside them. If you need a non-default ability (e.g.
:read_merge_request instead of :read_project), pass it as ability::
find_project!(project_id, ability: :read_merge_request). The same uniform-error guarantee
applies regardless of which ability you pass.
- Don't hardcode a value list the schema already derives from a model. GraphQL
enums are often generated from a model constant (e.g. DuoWorkflowStatusGroup is built
from Ai::DuoWorkflows::Workflow::GROUPED_STATUSES). Derive your input_schema enum
from that same constant so they stay in lock-step; a hand-copied list silently drifts and
starts rejecting values the schema accepts. Point at the source of truth, don't duplicate
it (same for a URL you could read off the model instead of re-templating the route).
- When you alias/replace another tool, read its real source, not the catalog blurb. Catalog
and doc descriptions drift (a tool documented as "project or group" was project-only in code).
Open the actual tool definition to learn its true parameters and scope. And a
tool_aliases
entry only helps clients that had the old name advertised by the MCP server — if the tool
you're replacing lives elsewhere (e.g. a Duo Workflow Python tool that was never MCP-served),
no MCP client cached the old name, and if it still runs it remains the compatibility path.
Don't claim the alias "protects cached clients" without confirming the old name was ours.
- Where you declare an alias depends on the tool type. Custom, GraphQL, and aggregated tools
override
self.tool_aliases on the class. API tools (route_setting :mcp) set tool_aliases: in
the route settings instead — the class override does nothing for them, since one ApiTool class
backs every route. tool_aliases: on a route that also sets aggregators: is ignored; alias that
tool through the aggregator class's self.tool_aliases.
- Add the tool to the built-in catalog only if a custom agent would use it. Registering in
manager.rb already exposes the tool to agentic chat (Ai::DuoWorkflows::McpConfigService
injects the GitLab MCP server's tools). The extra entry in
ee/lib/ai/catalog/built_in_tool_definitions.rb — plus an Ai::ToolRules::Registry
privilege-group mapping, or it's silently ungovernable — is what lets a custom AI Catalog
agent select the tool. So ask: would someone building a custom agent want to grant this
tool? Yes → add it; no → don't. Omitting is safe (adding an entry later is additive), whereas
removing one is a breaking change: custom agent definitions store the tool's catalog id
(BuiltInTool.where(id: tool_ids)), so removal makes those stored references silently dangle —
the same expand-safe / contract-breaking asymmetry as an input_schema param. When unsure,
omit and revisit; it's ultimately a proposal / review-board call.
Testing locally (easy loop)
Prove it with a real tools/list + tools/call round trip, not just specs. A spec run
confirms the classes wire up; it does not confirm the tool is advertised or that a call returns
what you promised. Restart the app first (gdk restart rails-web) so the new tool registers —
Manager memoizes GRAPHQL_TOOLS.
- Request spec (canonical): pattern in
spec/requests/api/mcp/handlers/call_tool_spec.rb.
- Don't hardcode the GDK URL, and don't assume port 3000. Puma may bind a UNIX socket
(
config/puma.rb), so 127.0.0.1:3000 can be refused; the app is reachable through nginx at
whatever Gitlab.config.gitlab.url reports (e.g. https://gdk.test:3443). Derive it.
- A
rails runner script is the most reliable driver. curl to gdk.test may hit a
permission prompt, and a runner script also gives you DB access to pick fixtures inline. Real
HTTP, self-signed cert, URL derived:require 'net/http'; require 'json'
base = URI("#{Gitlab.config.gitlab.url}/api/v4/mcp")
token = User.find_by_username('root').personal_access_tokens.create!(
name: 'mcp-verify', scopes: [:api, :mcp], expires_at: 7.days.from_now)
token.set_token('someknownvalue'); token.save! # token.revoke! when done
def rpc(base, tok, body)
req = Net::HTTP::Post.new(base)
req['Authorization'] = "Bearer #{tok}"; req['Content-Type'] = 'application/json'
req.body = body.merge(jsonrpc: '2.0', id: 1).to_json
opts = { use_ssl: base.scheme == 'https', verify_mode: OpenSSL::SSL::VERIFY_NONE }
JSON.parse(Net::HTTP.start(base.hostname, base.port, **opts) { |h| h.request(req) }.body)
end
# rpc(base, 'someknownvalue', { method: 'tools/list' })
# rpc(base, 'someknownvalue', { method: 'tools/call', params: { name: '<tool>', arguments: {...} } })
Check tools/list for registration + the schema the model actually sees; check tools/call
for the result shape, and confirm removed/invalid args are rejected. Measuring the advertised
JSON ({name, description, inputSchema}.to_json.length) against the other tools' is a cheap way
to catch a bloated schema — tools/list is paid once per session for every tool.
curl works too if unblocked: POST {url}/api/v4/mcp -k -H "Authorization: Bearer <PAT>"
with the same JSON-RPC body.
- MCP Inspector:
npx @modelcontextprotocol/inspector → Streamable HTTP → the
endpoint + bearer header.
- Claude Code:
claude mcp add --transport http gitlab-gdk <url> --header "Authorization: Bearer <PAT>".
- Console: introspect the GraphQL query directly with
GitlabSchema.execute(...).
References
| Topic |
Location |
| Two-class field-by-field detail, naming, mapping, mutation deltas |
references/tool-anatomy.md |
| How the GraphQL API is built + how to discover it (introspection) |
references/graphql-api-model.md |
Full worked read example (get_merge_request_notes) |
references/worked-example.md |
| Agent-as-consumer review checklist |
references/agent-consumer-review.md |
| Canonical dev docs |
doc/development/duo_agent_platform/mcp/{_index,graphql_integration}.md |
| Framework classes |
app/services/mcp/tools/graphql_tool.rb, .../base/graphql_service.rb, .../manager.rb |
| Concerns |
app/services/mcp/tools/concerns/{resource_finder,url_parser,content_validation,constants}.rb |
| Closest read / write templates |
.../merge_requests/get_merge_request_notes_{tool,service}.rb / create_merge_request_note_{tool,service}.rb |
| Project-or-group tool template |
.../labels/search_{tool,service}.rb + app/graphql/queries/mcp/labels/search.query.graphql |
| RuboCop rule forbidding inline operations |
rubocop/cop/mcp/use_graphql_query_file.rb |
1---2name: gitlab-mcp-tool-builder3description: "Build a new GraphQL-backed MCP server tool in gitlab-org/gitlab. Use when adding or scaffolding a GitLab Duo Agent Platform MCP tool that follows the app/services/mcp/tools/ *Tool + Graphql*Service pattern — covers GraphQL API discovery, the two-class-plus-registration build recipe, and gotchas. Keywords: MCP tool, MCP server, GraphQL tool, GitLab Duo Agent Platform."4version: 1.8.05license: MIT6compatibility: opencode7metadata:8 source: https://skillmd.com/skills/gitlabhq/gitlab-mcp-tool-builder9 audience: developers10 keywords: MCP tool, MCP server, GraphQL tool, Duo Agent Platform, mcp/tools11 slash-command: enabled12---1314# GitLab GraphQL MCP Tool Builder1516Build a new **GraphQL-backed MCP server tool** in `gitlab-org/gitlab` — the `*Tool` +17`*Service` pair under `app/services/mcp/tools/`. Scope: GraphQL tools only. Bias to18**minimal, idiomatic change**: copy the closest existing GraphQL tool, swap the19query/variables/schema, register it — don't invent abstractions. Mirror existing20patterns, verify everything against the live schema (never guess field/arg/auth21details), and produce a tool + service + specs that pass `rubocop` and `rspec`.2223**Canonical source of truth** (read first; this skill distills them and adds the24gotchas): `doc/development/duo_agent_platform/mcp/_index.md` (tool-proposal process,25versioning, aliases, aggregated tools) and26`doc/development/duo_agent_platform/mcp/graphql_integration.md` (the two-layer27architecture and the `.graphql`-file convention). If this skill and the docs28disagree, the docs win — tell the user so they can refile an update here.2930**Before writing any tool: the proposal process is required.** New tools go through an31[MCP Tool Proposal issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?description_template=MCP%20Tool%20Proposal)32reviewed by the interim `mcp-tool-review-board`. Confirm the proposal exists (or is33waived) before building — tool proliferation degrades every agent's context, so the34bar for a new tool is deliberately high.3536## What you're building3738A GraphQL MCP tool is **two classes + one registration line**, executed in-process:3940```41MCP client (JSON-RPC POST /api/v4/mcp, "tools/call")42 → API::Mcp::Base (auth: PAT/token with `mcp` scope)43 → Handlers::CallTool (looks up tool, sets current_user)44 → Manager.get_tool(name:) (registry lookup)45 → <Name>Service (picks version, defines agent-facing schema)46 → execute_graphql_tool(arguments)47 → <Name>Tool (holds the operation + variable mapping)48 → GitlabSchema.execute(query, variables:, context:) ← the actual call49 → process_result (shape output → MCP Response)50```5152- **`<Name>Tool`** (`.../<area>/<name>_tool.rb`) — subclass of `Mcp::Tools::GraphqlTool`;53 loads the operation from a `.graphql` file, maps `params → variables`, optionally54 reshapes output.55- **`<Name>Service`** (`.../<area>/<name>_service.rb`) — subclass of56 `Base::GraphqlService`; the agent-facing wrapper defining `input_schema`,57 `description`, and `annotations`.58- **Registration** — one line in `manager.rb` `GRAPHQL_TOOLS`:59 `'<tool_name>' => ::Mcp::Tools::<Area>::<Name>Service`.6061Key fact: `GraphqlTool#execute` calls **`GitlabSchema.execute(...)`** — the same schema62the HTTP `/api/graphql` endpoint uses, run **as `current_user`**, so the tool inherits63the caller's permissions (don't re-check perms). Field-by-field detail of both classes,64the naming convention, the mapping cheat-sheet, and the mutation (write) deltas are in65**[references/tool-anatomy.md](references/tool-anatomy.md)**.6667## GraphQL operations live in `.graphql` files — not inline strings6869Every operation is a committed file under `app/graphql/queries/mcp/<domain>/`, loaded70by `GraphqlTool.load_graphql(<relative path>)`. This is enforced, not stylistic:7172- The `Mcp/UseGraphqlQueryFile` RuboCop rule **fails** on an inline string / HEREDOC73 passed as `graphql_operation:` and points you at `load_graphql`.74- Files here are validated against `GitlabSchema` at build time by75 `spec/graphql/all_queries_spec.rb`, so an operation that drifts from the schema fails76 CI. An inline operation skips that safety check.7778Rules for the file:79- **Name it `<name>.query.graphql` or `<name>.mutation.graphql`** in a subdirectory80 mirroring the tool's domain (`merge_requests/`, `work_items/`, `labels/`).81- **First line must be `# @feature_category: mcp_server`** — the82 `graphql_require_feature_category` lint rule fails without it.83- **Verb-first operation name** to match `app/graphql/queries` (`getMergeRequestNotes`,84 `createNote` — not `MergeRequestNotes`).85- **Load with the direct `load_graphql(...)` form, not a lambda.** `-> { load_graphql(...) }`86 rereads the file every request. The one exception is an operation *composed at load87 time* (e.g. a query built from EE-overridden fragments) — build it in a method and88 reference it with a lambda (`graphql_operation: -> { build_query }`).8990## Tool naming and consolidation conventions (!245400)9192> **Note:** Existing tools (`get_merge_request_notes`, `create_merge_request_note`, etc.)93> predate these conventions. Copy them for the **implementation pattern** but name and94> structure your new tool per the conventions below.9596Every tool name uses a `verb_object` shape. The verb signals the operation class:9798- **`get_`** — single object (e.g. `get_merge_request`)99- **`list_`** — collection (e.g. `list_merge_requests`)100- **`save_`** — create **or** update field mutations; presence of `id` determines which.101 Mark create-required params as `required` in the schema.102 Intentional exception: when a lifecycle action has its own mutation (e.g. `retry`, `cancel`)103 and targets the resource this tool creates, fold it behind an `action` param rather than104 adding a tool. Route on the resource's own ID, not the parent's, and state the rule in the105 tool description (`save_pipeline`: no `pipeline_id` creates, `pipeline_id` + `action`106 transitions). Annotations are per tool, so the whole tool inherits the most destructive107 action's `destructiveHint`; note the fold in the proposal.108- **`delete_`** — delete operations only; never fold into `save_`.109- **`add_`** or other verbs — reserved for objects without a typical CRUD shape (e.g. `add_commit`).110111**Facets fold into `get_`, not separate tools.** Sub-reads scoped to one parent object112(notes, diffs, commits, pipelines) become an `include:` enum on the parent's `get_` tool113(e.g. `get_merge_request` with `include: diffs|commits|notes|pipelines|conflicts`), not114separate `list_*` tools. Independent collections that can be queried on their own get115their own `list_` tool (e.g. `list_merge_requests`, `list_pipelines`).116117**Resource identification** is always `url` OR `project_id` + resource internal ID —118never folded into a single `id`. `url` is the single-value convenience path; `project_id`119+ `iid`/`sha`/etc. is the explicit path. When both are supplied they are cross-validated.120121**Pagination** mirrors the endpoint, not a forced convention:122- GraphQL-backed tools → native cursor pagination (`first`, `after`); return `pageInfo`123 with `endCursor` and `hasNextPage`. Never hardcode the page size numbers: splat124 `Mcp::Tools::Concerns::CursorPagination.input_schema_params(items:)` into the service's125 `input_schema`, and use its `paginated_first` in the tool.126- REST-backed tools → offset pagination (`page`, `per_page`); return `metadata` with127 `page`, `per_page`, `has_more`.128129**Document intentional exceptions** in the tool proposal when a tool deliberately breaks130a convention (non-standard verb, second write tool on one resource).131132## Recipe — build a new GraphQL MCP tool1331340. **Confirm a tool proposal exists** (MCP Tool Proposal issue / review board — see top), and135 **build exactly what it specifies — under-ship, don't over-ship.** An MCP `input_schema` is136 versioned (`_index.md`): adding a parameter later is additive and safe, but removing one is a137 breaking change needing a new version plus multi-version support. So a param you're unsure138 about is far cheaper to add later than to remove. If the issue is project-scoped, ship139 project-scoped; capability it doesn't ask for is a separate proposal, not a bonus. Resist140 "compatibility" surface too — if this tool replaces/aliases another that still runs (see141 Renaming, tool-anatomy.md), the old tool is the compatibility path and this one need not142 absorb its parameter shape.1431. **Verify the GraphQL field exists — before writing anything.** Check that the schema144 already exposes a field covering your use case:145 - **Type file:** `app/graphql/types/<resource>_type.rb` (or `project_type.rb` /146 `group_type.rb`) — scan for the field name.147 - **Resolver:** `app/graphql/resolvers/<resource>_resolver.rb` — scan `argument`148 lines to confirm the filter args you need exist.149 - **Console fallback:** `GitlabSchema.query_type.fields.keys.grep(/keyword/)` or150 `Types::MergeRequestType.fields.keys` to list available fields at runtime. See151 **[references/graphql-api-model.md](references/graphql-api-model.md)** for more.152 - **⚠️ If the field doesn't exist: stop and alert the user.** A missing field means153 the tool isn't buildable without a schema addition — a separate MR requiring its154 own GraphQL review. Do not invent or guess field names.1552. **Copy the closest existing GraphQL tool** — tool + service + `.graphql` + specs. A156 full read example is in **[references/worked-example.md](references/worked-example.md)**.1573. **Write the operation** in GraphiQL/console until it returns what you want (variables158 for all inputs; paginate connections), then save it as a `.graphql` file per the159 rules above. **Never inline it.**1604. **Tool class:** `graphql_operation: load_graphql('<domain>/<file>.graphql')`; set161 `operation_name` to the **root field** in `register_version` — or override it as an162 instance method if the root field varies at call time (e.g. project-or-group tools —163 see `references/tool-anatomy.md`); map `params → variables` in `build_variables`;164 reshape in `process_result` if needed.1655. **Service class** (`< Base::GraphqlService`): write `input_schema` (agent-facing args166 + `required`; do **not** add `additionalProperties`), `description`, `annotations`167 (`readOnlyHint` correct — it drives pre-approval); point `graphql_tool_class` at the Tool.1686. **Agent-as-consumer review** — review name/description/schema/output as the LLM sees169 them, *before* specs. See **[references/agent-consumer-review.md](references/agent-consumer-review.md)**.1707. **Register** in `manager.rb` `GRAPHQL_TOOLS`.1718. **Update the `list_tools` specs — required, both files.** Each holds its own copy of the172 same `expected_annotations` hash, so both need the identical173 `'<tool_name>' => { 'readOnlyHint' => … }` entry under the matching comment bucket (write174 non-destructive / write destructive / read-only) — annotations only, neither file asserts175 `description` or `inputSchema`. Both also assert every service under the MCP tools tree is176 registered in `Mcp::Tools::Manager`, so they catch a skipped step 7.177 - `spec/requests/api/mcp/handlers/list_tools_spec.rb` — its annotations example is guarded178 `unless: Gitlab.ee?`.179 - `ee/spec/requests/api/mcp/handlers/list_tools_spec.rb` — unguarded, and its hash also180 lists EE-only tools.181 Only one of the two annotations examples runs in a given pipeline, so green specs never182 prove you updated both files.1839. **Unit specs** for the Tool and the Service. Lock the service `input_schema` as a184 whole with a single `expect(...).to eq({ … })` (a full version-lock, like185 `list_merge_requests_service_spec`), not property-by-property — it catches accidental186 schema drift across versions. Don't re-assert `readOnlyHint` here: the `list_tools`187 specs (step 8) already cover annotations, so a per-tool "is marked read-only" example188 is redundant. Match the sibling MCP specs' `feature_category: :mcp_server` on both files.18910. **Update user docs:** `doc/user/model_context_protocol/mcp_server_tools.md`.19011. **`bundle exec rubocop` + `bundle exec rspec`** the changed files; fix failures. Also191 run `bundle exec rspec spec/graphql/all_queries_spec.rb` — it validates your new192 `.graphql` file against `GitlabSchema`, so a bad field/arg fails here. **It does not check193 `id` selections** — a missing `id` passes rspec and only fails the `graphql-verify` eslint CI194 job (see Gotchas), which can't run locally without the schema dump. Green specs are not proof195 the query lints.196197## Gotchas (learned the hard way)198199- **Inline operation → RuboCop failure.** `Mcp/UseGraphqlQueryFile` rejects a200 string/HEREDOC as `graphql_operation:`; use a `.graphql` file via `load_graphql`.201- **Missing `# @feature_category:` → lint failure.** Every `.graphql` file needs it as202 the first line (`graphql_require_feature_category`).203- **`load_graphql` in a lambda rereads the file per request.** Use the direct form; a204 method + lambda is only for an operation composed at load time (EE fragments).205- **Don't hand-set `additionalProperties`.** `SchemaDefaults` applies `false`206 automatically (!243352); setting it manually is redundant and will be flagged.207- **`readOnlyHint` changes behavior, not just docs.** The pre-approved tool list is208 derived from it (!231431); a write wrongly marked `readOnlyHint: true` runs without209 confirmation.210- **`operation_name` is the root field, not the `query Name` label.** `process_result`211 digs `result.dig('data', operation_name)`. `{ project(...) { … } }` → `'project'`.212- **Unused declared variable → validation error.** Don't declare `$x` you don't reference.213- **Undeclared argument → validation error.** Only pass args the field defines (verify214 with `.arguments.keys`).215- **`iid` is a `String` in GitLab GraphQL**, not Int — `iid: "1"`.216- **Client-side post-filtering breaks pagination** — prefer a real server-side arg; if217 none exists, consider cutting the input from v1 (see references/graphql-api-model.md).218- **`position` (DiffPositionType) is null** for non-diff notes — expected.219- **Select `id` on every object type that has one — it is lint-mandated, not padding.**220 `@graphql-eslint/require-selections` (error, applies to `**/*.graphql`) requires `id` on221 `project`, `group`, connection `nodes`, `author`, etc. **`spec/graphql/all_queries_spec.rb`222 passes without them** — it only checks schema-correctness — so the *only* thing that catches a223 missing `id` is the `graphql-verify` CI job, which needs the schema dump and does not run224 locally. Never remove an `id` to "slim" a payload; a reviewer (human or agent) suggesting that225 is wrong.226- **A root `oneOf`/`anyOf` silently disables `additionalProperties: false`.** `SchemaDefaults`227 skips composition schemas (tool-anatomy.md), so expressing "exactly one of `url`/`project_id`"228 as a schema `oneOf` quietly stops unknown args being rejected. Enforce mutual exclusivity in229 Ruby instead (in `resolve_*`, raising on zero-or-many), and keep the schema composition-free so230 the strictness guard survives. State the "exactly one of" rule once in the tool `description`,231 not in each property.232- **`find_project!` / `find_group!` fold authorization in — "forbidden" and "missing" are indistinguishable.**233 `ResourceFinder#find_project!` and `#find_group!` check `Ability.allowed?` after the DB lookup.234 If the record is missing **or** the caller lacks the required ability, both raise the same235 `"'<id>' not found or inaccessible"` `StandardError`. This is intentional: a distinct236 `"Access denied"` message would let an authenticated caller enumerate private projects/groups237 by comparing error strings. Do **not** add a separate authorization check after calling these238 finders — the check is already inside them. If you need a non-default ability (e.g.239 `:read_merge_request` instead of `:read_project`), pass it as `ability:`:240 `find_project!(project_id, ability: :read_merge_request)`. The same uniform-error guarantee241 applies regardless of which ability you pass.242- **Don't hardcode a value list the schema already derives from a model.** GraphQL243 `enum`s are often generated from a model constant (e.g. `DuoWorkflowStatusGroup` is built244 from `Ai::DuoWorkflows::Workflow::GROUPED_STATUSES`). Derive your `input_schema` `enum`245 from that same constant so they stay in lock-step; a hand-copied list silently drifts and246 starts rejecting values the schema accepts. Point at the source of truth, don't duplicate247 it (same for a URL you could read off the model instead of re-templating the route).248- **When you alias/replace another tool, read its real source, not the catalog blurb.** Catalog249 and doc descriptions drift (a tool documented as "project or group" was project-only in code).250 Open the actual tool definition to learn its true parameters and scope. And a `tool_aliases`251 entry only helps clients that had the *old name advertised by the MCP server* — if the tool252 you're replacing lives elsewhere (e.g. a Duo Workflow Python tool that was never MCP-served),253 no MCP client cached the old name, and if it still runs it remains the compatibility path.254 Don't claim the alias "protects cached clients" without confirming the old name was ours.255- **Where you declare an alias depends on the tool type.** Custom, GraphQL, and aggregated tools256 override `self.tool_aliases` on the class. API tools (`route_setting :mcp`) set `tool_aliases:` in257 the route settings instead — the class override does nothing for them, since one `ApiTool` class258 backs every route. `tool_aliases:` on a route that also sets `aggregators:` is ignored; alias that259 tool through the aggregator class's `self.tool_aliases`.260- **Add the tool to the built-in catalog only if a custom agent would use it.** Registering in261 `manager.rb` already exposes the tool to **agentic chat** (`Ai::DuoWorkflows::McpConfigService`262 injects the GitLab MCP server's tools). The extra entry in263 `ee/lib/ai/catalog/built_in_tool_definitions.rb` — plus an `Ai::ToolRules::Registry`264 privilege-group mapping, or it's silently ungovernable — is what lets a **custom AI Catalog265 agent** select the tool. So ask: *would someone building a custom agent want to grant this266 tool?* Yes → add it; no → don't. Omitting is safe (adding an entry later is additive), whereas267 removing one is a **breaking change**: custom agent definitions store the tool's catalog `id`268 (`BuiltInTool.where(id: tool_ids)`), so removal makes those stored references silently dangle —269 the same expand-safe / contract-breaking asymmetry as an `input_schema` param. When unsure,270 omit and revisit; it's ultimately a proposal / review-board call.271272## Testing locally (easy loop)273274**Prove it with a real `tools/list` + `tools/call` round trip, not just specs.** A spec run275confirms the classes wire up; it does not confirm the tool is advertised or that a call returns276what you promised. Restart the app first (`gdk restart rails-web`) so the new tool registers —277`Manager` memoizes `GRAPHQL_TOOLS`.278279- **Request spec** (canonical): pattern in `spec/requests/api/mcp/handlers/call_tool_spec.rb`.280- **Don't hardcode the GDK URL, and don't assume port 3000.** Puma may bind a UNIX socket281 (`config/puma.rb`), so `127.0.0.1:3000` can be refused; the app is reachable through nginx at282 whatever `Gitlab.config.gitlab.url` reports (e.g. `https://gdk.test:3443`). Derive it.283- **A `rails runner` script is the most reliable driver.** `curl` to `gdk.test` may hit a284 permission prompt, and a runner script also gives you DB access to pick fixtures inline. Real285 HTTP, self-signed cert, URL derived:286 ```ruby287 require 'net/http'; require 'json'288 base = URI("#{Gitlab.config.gitlab.url}/api/v4/mcp")289 token = User.find_by_username('root').personal_access_tokens.create!(290 name: 'mcp-verify', scopes: [:api, :mcp], expires_at: 7.days.from_now)291 token.set_token('someknownvalue'); token.save! # token.revoke! when done292 def rpc(base, tok, body)293 req = Net::HTTP::Post.new(base)294 req['Authorization'] = "Bearer #{tok}"; req['Content-Type'] = 'application/json'295 req.body = body.merge(jsonrpc: '2.0', id: 1).to_json296 opts = { use_ssl: base.scheme == 'https', verify_mode: OpenSSL::SSL::VERIFY_NONE }297 JSON.parse(Net::HTTP.start(base.hostname, base.port, **opts) { |h| h.request(req) }.body)298 end299 # rpc(base, 'someknownvalue', { method: 'tools/list' })300 # rpc(base, 'someknownvalue', { method: 'tools/call', params: { name: '<tool>', arguments: {...} } })301 ```302 Check `tools/list` for registration + the schema the model actually sees; check `tools/call`303 for the result shape, and confirm removed/invalid args are rejected. Measuring the advertised304 JSON (`{name, description, inputSchema}.to_json.length`) against the other tools' is a cheap way305 to catch a bloated schema — `tools/list` is paid once per session for every tool.306- **`curl`** works too if unblocked: `POST {url}/api/v4/mcp -k -H "Authorization: Bearer <PAT>"`307 with the same JSON-RPC body.308- **MCP Inspector:** `npx @modelcontextprotocol/inspector` → Streamable HTTP → the309 endpoint + bearer header. 310- **Claude Code:** `claude mcp add --transport http gitlab-gdk <url> --header "Authorization: Bearer <PAT>"`.311- **Console:** introspect the GraphQL query directly with `GitlabSchema.execute(...)`.312313## References314315| Topic | Location |316|---|---|317| Two-class field-by-field detail, naming, mapping, mutation deltas | [references/tool-anatomy.md](references/tool-anatomy.md) |318| How the GraphQL API is built + how to discover it (introspection) | [references/graphql-api-model.md](references/graphql-api-model.md) |319| Full worked read example (`get_merge_request_notes`) | [references/worked-example.md](references/worked-example.md) |320| Agent-as-consumer review checklist | [references/agent-consumer-review.md](references/agent-consumer-review.md) |321| Canonical dev docs | `doc/development/duo_agent_platform/mcp/{_index,graphql_integration}.md` |322| Framework classes | `app/services/mcp/tools/graphql_tool.rb`, `.../base/graphql_service.rb`, `.../manager.rb` |323| Concerns | `app/services/mcp/tools/concerns/{resource_finder,url_parser,content_validation,constants}.rb` |324| Closest read / write templates | `.../merge_requests/get_merge_request_notes_{tool,service}.rb` / `create_merge_request_note_{tool,service}.rb` |325| Project-or-group tool template | `.../labels/search_{tool,service}.rb` + `app/graphql/queries/mcp/labels/search.query.graphql` |326| RuboCop rule forbidding inline operations | `rubocop/cop/mcp/use_graphql_query_file.rb` |