# 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.
2. Compare each scope against the scopes your GitLab instance supports.
   Expected: One scope is misspelled or unsupported on your instance.
3. Pin the config to valid scopes only (e.g. api, or read_api for read-only).
   Expected: The authorize request uses the corrected list.
4. 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.