Authentication

What happens when you connect

1. Your client sends a request to the server without a token. The server answers 401 and tells the client where its protected-resource metadata lives.
2. The client reads that metadata, learns which authorization server to use (WorkOS AuthKit at auth.vindexgateway.com) and which scopes to request, and registers itself. No pre-registration by Vindex is needed.
3. The client opens your browser on the Vindex sign-in. You sign in (or create an account) and choose your organization if you belong to more than one.
4. The client receives an access token and a refresh token, stores them, and retries the request. From now on it refreshes silently; you sign in again only when the refresh token expires or is revoked.
5. On each call the server verifies the token locally against the authorization server’s published keys, resolves your organization to your Vindex company, and checks that you are an active member before running the tool.

Discovery documents

Standards: the MCP authorization specification (OAuth 2.1 profile), RFC 9728 Protected Resource Metadata, RFC 8414 Authorization Server Metadata, RFC 7591 Dynamic Client Registration, RFC 7636 PKCE, RFC 8707 Resource Indicators.

POST https://mcp.vindexgateway.com/mcp

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.vindexgateway.com/.well-known/oauth-protected-resource/mcp"

{
  "resource": "https://mcp.vindexgateway.com/mcp",
  "authorization_servers": ["https://auth.vindexgateway.com"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://www.vindexgateway.com/docs/mcp"
}

The server also passes through the authorization server’s own metadata at https://mcp.vindexgateway.com/.well-known/oauth-authorization-server for clients that look for it on the MCP host. Both Dynamic Client Registration and Client ID Metadata Documents are accepted, so current and older clients can identify themselves.

Scopes and entitlements

Clients request the OpenID Connect scopes openid profile email offline_access. The access token carries your identity and your organization id and nothing else. Which tools you may call is decided by Vindex, not by the token:

A user deactivated in Vindex keeps a valid sign-in but receives no entitlements, so the scoring and usage tools refuse. Registration of a client grants nothing by itself; a registered client still has to complete a user sign-in.

Your organization is your company

The organization you sign in under maps to exactly one Vindex company. Everything the tools do is scoped to it: the allowance get_usage reports, the stories score_story counts, the scores that appear in the Vindex Portal. If your organization has never used Vindex, the first sign-in creates the company on the free plan and gives it a placeholder name; rename it in the Portal. Scoring through the MCP server uses one gateway key per company, held by Vindex; it never reaches your machine.

Sessions and re-consent

Access tokens are short-lived and refreshed by the client without your involvement. You are asked to sign in again when the refresh token expires, when you sign out of Vindex everywhere, when an admin removes you from the organization, or when the client’s stored session is deleted. Each client keeps its own session, so connecting a second client means one more sign-in.

Troubleshooting