MCP Connect
Install the private package that checks a remote MCP connection and prints the host setup values.
MCP Connect
@kigo-digital/mcp-connect is a developer utility. Run it against an environment before anyone opens Claude Desktop, ChatGPT, or Grok.
The command tries the same login those products will use. When it succeeds, it prints a worksheet with the MCP URL, the issuer, and the scopes. A person types those values into the host, and the host signs in on its own. The worksheet has no client id and no tokens.
The worksheet is not imported. The login this command just completed is not handed to the host. Exit 0 means the worksheet is ready after the MCP URL itself responded: for Claude Desktop and ChatGPT the fresh bearer was accepted, and for Grok the URL answered 401 as a protected resource. It still does not connect the host.
Host screens and consent are in Remote MCP connectors.
Install
The package is private on GitHub Packages. Use Bun 1.4.4 and a personal access token or GitHub App token with read:packages.
Add this to the user or project .npmrc:
@kigo-digital:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKENInstall it as a development dependency of the project that will run the check:
bun add -d @kigo-digital/mcp-connectbunx mcp-connect --help prints the command. The command runs on Bun.
Check an environment
Replace <api-host> with the public origin of the API, with no path and no trailing slash.
bunx mcp-connect \
--mcp-url https://<api-host>/mcp \
--authorization-server https://<api-host>/api/auth \
--host claude-desktop--host chooses the worksheet:
| Host | Value | What the check does |
|---|---|---|
| Claude Desktop | claude-desktop | Opens a browser, completes authorization-code login with S256 PKCE, and stores a refresh grant on this machine. |
| ChatGPT | chatgpt | Same login and local grant as Claude Desktop. |
| Grok | grok | Requires a public HTTPS URL. Stores no grant. |
Optional flags:
--scopes openid,@readlimits the requested scopes. Omit it to use the public connection scopes the server advertises. Omitting it does not request the factory catalog.--output worksheet.mdalso writes the worksheet. The command still prints it.--timeout-ms 300000changes how long the browser login may take.
Exit 0 prints the worksheet after the MCP URL itself responded. A Claude Desktop or ChatGPT success also prints clientId after the worksheet, and that value is what refresh --client-id uses. A Grok success prints only the worksheet. That Grok result does not connect Grok Build. Follow the Grok Build steps in Remote MCP connectors, which send the User-Agent header Grok Build's OAuth discovery client omits. Exit 1 prints stage code: message and writes no worksheet. Exit 2 means the command line is wrong.
Use the printed MCP URL, issuer, and scopes in the host. Then finish that product's own sign-in, described in Remote MCP connectors.
What the local grant is for
A Claude Desktop or ChatGPT check stores a refresh grant at ~/.local/state/augeo/mcp-connect/credentials when XDG_STATE_HOME is unset. The directory is owner-only. The grant proves this authorization server can issue a credential for this MCP URL. It is not the host session, and it does not choose which tools the host shows. The account that approves consent decides that. An operator receives the factory and admin access that role already has. Another account does not. Nobody pastes those scopes into the host.
Rotate that grant later with:
bunx mcp-connect refresh \
--issuer https://<api-host>/api/auth \
--resource https://<api-host>/mcp \
--client-id <client-id>The command prints the issuer, resource, and client id. It prints no token. The client id is the value printed after a Claude Desktop or ChatGPT worksheet. reauthorization_required means the stored grant is no longer valid. Run the check again.
A Grok check does not create a grant, so there is nothing to refresh.
Library
Other tooling can call the same check:
import { check, refresh } from "@kigo-digital/mcp-connect";
const result = await check({
mcpUrl: "https://<api-host>/mcp",
authorizationServer: "https://<api-host>/api/auth",
host: "claude-desktop",
});result.ok is the same pass or fail as the command. result.handoff.content is the worksheet.