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).
  • Wrong class for this listener: a share link's mgl_ token on the loopback server, or any other token on a share link's listener.
  • Minted by an older magus: a token 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 server decides who may use which route. Four token classes told apart by prefix, a grant of none, read or write per surface, 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 (95680f58)
Earlier changes on this page (4)

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). See operations.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. See services.

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

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.

Conventions

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