MCP Authentication Troubleshooting

Use OAuth for interactive clients. Use MCP Setup for client commands. Settings lists active MCP sessions and lets you revoke them.

Check discovery first

curl https://mcp.getstack.run/.well-known/oauth-protected-resource
curl https://api.getstack.run/.well-known/oauth-authorization-server

The first response names the API authorization server. The second response names the authorization, token, registration, and device endpoints. A healthy discovery response does not prove that a stored client session can refresh.

No browser login appears

• Confirm that the MCP URL is https://mcp.getstack.run/mcp.
• Remove any Authorization header from an interactive OAuth setup.
• Start the client login command or reconnect the server.
• Sign in if required and approve the requested scopes.
• Make one real STACK tool call.

invalid_grant: refresh revoked

The stored refresh-token family is no longer valid. Sign out or remove the STACK MCP connection in that client. Add it again. Sign in if required. Approve the requested scopes. Start a new client session. Then call a read-only tool such as stack_list_agents.

401 and 403

• 401 means the Bearer token is absent, expired, revoked, or invalid for the MCP resource.
• 403 can mean a member role or connection allowlist refuses the action, the route refuses agent context, or the action needs a governance step-up.
• MCP OAuth and API-key sessions normally resolve to an operator or member. They do not normally carry an agent ID.
• GOVERNANCE_APPROVAL_REQUIRED returns a dashboard URL. A human approves there, then the client retries the exact tool call with governance_approval_id.

Headless fallback

Use a raw sk_live_ key only for CI or a service that cannot complete OAuth. Store it in the service secret store and send it as an Authorization Bearer header. Do not paste it into prompts or commit it to client configuration.