# MatrixMD public MCP authentication

The public MatrixMD operations MCP uses OAuth 2.0 Authorization Code with dynamic client registration and PKCE.

## Discovery

- Protected resource: `https://mcp.matrixmdsoftware.com/mcp/plugin`
- Protected-resource metadata: `https://mcp.matrixmdsoftware.com/.well-known/oauth-protected-resource/mcp/plugin`
- Authorization-server issuer: `https://auth.matrixmdsoftware.com/api/v1/auth/oauth2`
- Authorization-server metadata: `https://auth.matrixmdsoftware.com/.well-known/oauth-authorization-server`

Clients should discover endpoint URLs from the metadata instead of hard-coding them. The server supports `mcp.tenant`; clients may request `offline_access` when a refresh token is necessary. Use PKCE with `S256`.

## Claude compatibility

- Hosted Claude surfaces use `https://claude.ai/api/mcp/auth_callback`.
- Claude Code uses an ephemeral loopback redirect on `http://127.0.0.1:<port>/callback` or `http://localhost:<port>/callback`.
- Dynamic clients are public OAuth clients and must use PKCE with `S256`.
- Refresh tokens rotate. A consumed, expired, or invalid refresh token returns the RFC-compliant `invalid_grant` error.

## User flow

1. Register a public OAuth client with an HTTPS redirect URI or an HTTP loopback redirect URI for a native client.
2. Start the authorization-code flow and request `mcp.tenant`.
3. Present the MatrixMD login page to the user. Never collect the MatrixMD password inside an agent prompt or MCP tool argument.
4. Exchange the returned authorization code using the original PKCE verifier.
5. Send the access token as an HTTP Bearer token to the MCP endpoint.
6. Call `tenant_list` before any tenant-scoped tool and use only a returned tenant slug.

The public MCP does not accept API keys in URLs or tool arguments. It does not expose patient records, appointments, clinical encounters, diagnoses, government identifiers, financial workflows, reports, administration, or raw SQL.

Support: <https://matrixmdsoftware.com/contact>