magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
2 min read

MGS9001: bearer token rejected

The server received a request on a guarded route (/mcp, the console data services) carrying a bearer token it would not accept, so it answered 401 unauthorized with WWW-Authenticate: Bearer realm="magus", error="invalid_token". This is the most common reason an MCP client (Claude Code, an IDE, Desktop) fails to connect.

[MGS9001] the server rejected the bearer token: it is wrong, expired, or
revoked. Mint one with: magus config mcp connector create, or magus config
console token create
  see: .../MGS9001.md

Why

Every guarded route requires a bearer token. The server does NOT say why it refused one (that would let a caller probe which tokens exist), so any of these produces the same 401:

  • Wrong token (a typo, or a token from a different server).
  • Expired token (every stored token expires, at most 366 days out).
  • Revoked token (revoked from the CLI or the console Settings).
  • A token of the wrong class for the listener: a share link's mgl_ token on the loopback server, or any other token on a share link's listener.
  • A token minted by an older magus, from before the class prefix. Mint a new one (MGS9016, MGS9017 name the files).

A request that carried no token at all is MGS9011 instead, and a valid token whose grant is below the route's need is MGS9015.

Resolution

  1. Mint a connector token and read how to wire it into your client:

    magus config mcp connector create --name my-client

  2. Confirm the token your client sends matches one the server knows:

    magus config mcp connector ls

    A token you expect but do not see was revoked or belongs to another server.

  3. If it is present but still rejected, it may be expired: mint a fresh one (there is no renew by design).

What this is not

  • Not a network error. The server answered; it declined the token. A refused connection or timeout is a different problem (server not running, wrong port).
  • Not a missing grant. A valid token without the grant a route needs gets 403 MGS9015.

See also

AuthPages in this section. Tokens and grantsHow the magus daemon decides who may use which route. Four token classes told apart by prefix, a grant of none, read or write per scope, a need declared by every procedure, one rule for minting, the trust model, and what the activity trail records about each. MGS3016: workspace failed to loadThe server refused a call because the workspace it targets failed to load, usually a magusfile that does not compile. The server holds the failure until a workspace source changes. ActivityServiceActivityService serves the trail to a viewer, mirroring magus.viewer.v1alpha1's shape: List a page of events (newest first), Get a payload blob by ref.
MGS9001authmcpconnectortokenonboardingbearer
Last updated (353014be)
Earlier changes on this page (6)

Full history ↗ · Blame source ↗

Glossary

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. Service in full.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate. Run in full.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.