GitHub

Magento MCP — Verify authentication

Confirm the sign-in works with MCP Inspector

The Inspector is the official interactive client for MCP servers. It walks the same OAuth sign-in an AI does — and shows you exactly where it succeeds or fails, in far more detail than any AI app will.

When to use this

Use the Inspector when an AI reports something vague like “Authorization failed” and you need to see why. It surfaces the real HTTP responses behind the OAuth handshake and lets you list and call tools with a token. Run the connection checker first — if endpoints are unreachable or redirecting, fix that before reaching for the Inspector.

It runs on your machine. The Inspector is a local web UI — your store address and any token stay on your computer and never reach a third party.

Before you start

Launch the Inspector

From a terminal, run:

npx @modelcontextprotocol/inspector

It prints a local web UI address (usually http://localhost:6274) and opens it in your browser, with a one-time session token pre-filled.

Path A — Verify the OAuth sign-in

This is the same flow an AI like Claude (web) uses. The server doesn't register clients automatically, so you first create an OAuth client for the Inspector in your Magento admin, then hand its Client ID and Secret to the Inspector.

  1. Register the Inspector as an OAuth client

    In your Magento admin, go to System → MCP → OAuth Clients and click Add New Client. Give it a Name (e.g. MCP Inspector) and set Redirect URIs to the Inspector's callback — exactly this, one line, no trailing slash:

    http://localhost:6274/oauth/callback

    It must match character-for-character (http://localhost is allowed here precisely for local tools like this). Leave Auth Mode on Personal, open the Allowed Tools tab and grant some tools, then click Save Client.

  2. Copy the Client ID and Client Secret

    After saving, copy the Client ID and the Client Secret. The secret is shown only once — if you lose it, use Rotate Secret to generate a new one (the Client ID stays the same).

  3. Enter the credentials in the Inspector

    Set Transport Type to Streamable HTTP and URL to your https://your-store.com/mcp address. Expand Authentication and, under OAuth 2.0 Flow, paste the Client ID and Client Secret. Confirm Redirect URL reads http://localhost:6274/oauth/callback — the Inspector's default, which must match what you registered. You can leave Scope blank (it defaults to mcp:read); the scope string only hints the consent screen — what the token can actually do is set by the tools you grant in Allowed Tools and the store's Allow Write Tools setting, not by this field.

  4. Connect and approve

    Click Connect. You're sent to your store's consent screen — sign in with your Magento admin account if prompted, review the tools, and approve. You're redirected back, the connection turns green, and the Tools tab lists what the client can use. That confirms discovery, consent, the token exchange and the authenticated call all work.

If it fails here, the failure is visible. The Inspector shows the failing request and response — a redirect on the token exchange, a 401, or a wrong callback URL — instead of the generic message an AI app shows. Compare what you see against the table at the bottom of this page.

Path B — Verify a bearer token

Use this to confirm a token works and to see which tools it can reach, without the OAuth round-trip.

  1. Mint a token

    Create a token for your admin user. With CLI access to the store:

    bin/magento magebit:mcp:token:create --admin-user=<your-username> --name=inspector

    Copy the plaintext token from the output — it's shown only once.

  2. Connect with the token

    Set Transport Type to Streamable HTTP, enter your /mcp URL, and paste the token into the Authentication field (the Inspector sends it as Authorization: Bearer <token>). Click Connect.

  3. List and call tools

    Open the Tools tab — it loads on connect. Pick a tool and run it with sample arguments to confirm an end-to-end call returns data. Every call is recorded in System → MCP → Audit Log.

A short tool list isn't a bug. The core module ships the system.* tools (cache, indexes, store info, config); domain tools — orders, catalog, customers, CMS — come from the add-on modules. The list reflects what you granted in Allowed Tools and what your admin role permits, so a narrow list means a narrow grant, not a broken connection.

Self-signed certificates (local / dev stores)

If your store uses a self-signed HTTPS certificate, the Inspector's Node proxy will refuse the connection. Disable certificate checking for that one process only:

NODE_TLS_REJECT_UNAUTHORIZED=0 npx @modelcontextprotocol/inspector

Dev only. This turns off all certificate validation in the Inspector's Node process. Never export it globally or use it in CI, and never against a production store.

Reading the failures

Connect bounces or the token exchange shows a 3xx redirect
A redirect (often a store-code or locale rewrite like /de/…, or http→https) is sitting in front of the MCP endpoints. The MCP and OAuth paths must respond directly. Run the connection checker to pinpoint which endpoint redirects.
A "Basic" auth prompt appears, or the request lands on a login wall
An HTTP Basic-auth gateway (common on staging) is intercepting requests before Magento. Exclude the /mcp and /.well-known/oauth-* paths from it — and from any store-code redirect that would push them behind it.
401 Unauthorized after entering a token
The token is wrong, expired or revoked. Mint a fresh one and try again.
"invalid_client" or a wrong redirect URI during OAuth
The OAuth client doesn't exist, is disabled, or its allowed redirect URIs don't match. Check the client under System → MCP → OAuth Clients.
"Server unavailable" or 503
The server is turned off. Confirm Enable MCP Server is set to Yes under Stores → Configuration → Magebit → MCP Server.

Endpoints unreachable?

Start with the connection checker — it tests reachability and redirects from your browser in seconds. Or return to the setup guide.