The requested scope is invalid, unknown, or malformed (GitLab MCP OAuth)

The requested scope is invalid, unknown, or malformed (GitLab MCP OAuth)

TL;DR: Request only scopes your GitLab instance recognizes; Claude Code asking for both api and read_api can trip this. Check the exact scope strings against your instance docs; one unknown scope fails the whole request. Pin the scope list in the server config to the minimal set that works.

The error

The requested scope is invalid, unknown, or malformed

Fix it

1. Find the scope string the MCP server requests during OAuth.

Expected: You see the scope list in the authorize URL or logs.

1. Compare each scope against the scopes your GitLab instance supports.

Expected: One scope is misspelled or unsupported on your instance.

1. Pin the config to valid scopes only (e.g. api, or read_api for read-only).

Expected: The authorize request uses the corrected list.

1. Re-run the OAuth flow.

Expected: Authorization completes and the server connects.

When this applies

GitLab MCP OAuth fails at the authorize step with the invalid-scope message, often when the client requests a scope bundle the instance does not know.

When this does NOT apply

PAT-based 401s are a different path. If OAuth succeeds but calls 401, check token expiry.

Tool compatibility

jmrplens/gitlab-mcp-server with OAuth, Claude Code

Also seen as

• GitLab OAuth invalid scope MCP
• MCP GitLab scope malformed
• Claude Code GitLab OAuth scope error

Why it happens

OAuth authorize rejects the entire request if any requested scope is unknown. Clients that ask for combined scopes like api plus read_api hit this on instances with a restricted scope list.

Edge cases

• Self-managed instances may disable certain scopes admin-side.
• read_api alone is enough for read-only tool use and avoids over-permissioning.
• After fixing scopes, clear the stored OAuth grant so the old request is not replayed.