Phonemos User Guide

Claude Connector Configuration (Keycloak)

How to connect Claude (claude.ai, Claude Desktop, mobile) to the Phonemos MCP server at https://<site>/_api/mcp. Authentication is OAuth against the Keycloak realm of the instance. Claude is configured with a fixed client (no dynamic client registration), so a dedicated Keycloak client must exist.

Keycloak

Realm: the Phonemos realm of the instance (example: acme Phonemos).

  • Create client in Clients: type OpenID Connect, client ID claude, enabled.

  • Client authentication on (confidential client). The client secret is on the Credentials tab and is entered in Claude.

  • Valid redirect URIs: https://claude.ai/api/mcp/auth_callback. Anthropic documents that the callback may move to https://claude.com/api/mcp/auth_callback, so register both.

Client scopes

Realm client scopes involved: claudeai (description "Needed for Claude"), hasura (adds the hasura claims), offline_access. All three have the realm level type None or Optional, so they must be assigned on the client itself.

Assigned on client claude (Client scopes tab, Setup):

Scope

Assigned type

Purpose

claudeai

Default

Needed for Claude

hasura

Default

Adds the hasura claims (user, email, roles) that the Phonemos backend requires in the access token

offline_access

Default

Refresh tokens, so users do not have to sign in again

acr, basic, email, profile

Default

Realm defaults

microprofile-jwt

Optional

Realm default, not used

Claude connector

In Claude, add a custom connector with these settings:

  • Name: any, for example acne Phonemos

  • URL: https://acme.phonemoscloud/_api/mcp

  • Authentication: Sign in now

  • OAuth client: Use your own OAuth client (not "Use Claude's published identity", not "Register automatically")

  • Client ID: claude

  • Client secret: the secret from the Credentials tab of the Keycloak client

  • Request headers: none

Notes