Authenticating with the MCP Endpoint

The Polarity MCP endpoint enforces the same authentication as the rest of the Polarity API.  Every request must include a valid, enabled JWT (JSON Web Token) issued by Polarity.

How Authentication Works

The MCP pipeline applies these checks on every incoming connection:

1. Token extraction:  The server reads the token from:

   1. the Authorization: Bearer <token> header or

   2. the \_polarity\_key session cookie.

2. Token verification:  The token is verified against the expected issuer (PolarityWeb.<env>) using Guardian.

3. Token-enabled check:

   1. The token's jti (JWT ID) is checked against the token\_metadata database table.

   2. If the token has been explicitly disabled by an admin (for example, after a user is deprovisioned), the request is rejected even if the token signature is valid.

4. User assignment:

   1. On successful authentication, the resolved user record is attached to the MCP connection frame as mcp\_user.

   2. All tool calls in that session execute in the context of that user.

Obtaining a Token

Use the Polarity login endpoint to obtain a JWT:

POST https://<polarity-host>/api/users/login
Content-Type: application/vnd.api+json
{
  "identification": "{{identification}}",
  "password":"{{password}}"
}

The response includes a token field in the response body. Use this token as the Bearer token for all subsequent MCP requests:

Authorization: Bearer <token>

Token Management

Polarity administrators can disable specific API tokens from the Admin panel.  A disabled token will be rejected at the MCP endpoint even if it has not expired.  

Rotate tokens regularly and revoke them when users leave or roles change.

User Scoping

Tools available through the MCP are scoped to the authenticated user.  

The list\_available\_integrations tool returns only integrations the user is subscribed to and that are currently running.

The do\_integration\_lookup tool validates that the requested integration is in the user's allowed list before executing the lookup.