MCP Authentication

Every MCP client should be authenticate with a user-owned bearer token that is generated through the backend API and stored only as a hash on the server.

Generate a token

Send an authenticated request as the target user to:

POST /v1/users/mcp-token

The response returns the plaintext token once:

{
  "token": "hmcp_..."
}

Store this value in the MCP client configuration. The backend cannot return the same plaintext token again later because only its hash is stored.

Use the token

Send the token in the MCP request headers:

Authorization: Bearer hmcp_...

This bearer token is accepted on the MCP transport endpoints, including the information endpoint and the tool routes under /v1/ai/mcp.

Rotation behavior

• Calling POST /v1/users/mcp-token again rotates the token for that user.
• After rotation, the old token stops working immediately.
• Each user has at most one active MCP token at a time.

Practical setup flow

1. Log in as the user that should own the MCP access.
2. Call POST /v1/users/mcp-token.
3. Copy the returned token.
4. Paste it into the AI tool or MCP client as Authorization: Bearer <token>.
5. Re-run token generation whenever you want to revoke and replace that access.

Notes

• The MCP information payload now documents the auth format as Bearer <user_mcp_token>.
• If an MCP request uses an invalid or rotated token, the backend responds with 401 Unauthorized.