Skip to content

Authentication

The MCP server and the API are both OAuth 2.1 resource servers. A client gets an access token from emely’s authorization server and sends it as a bearer token. Scripts can instead send a personal access token; see Get a token.

The authorization server is Nhost Auth, the same service that signs users in to the emely app.

  • Issuer: https://<auth-host>/v1
  • Flow: authorization code with PKCE
  • Client registration: client id metadata documents (CIMD). The client id is an HTTPS URL that hosts the client’s metadata.
  • Login and consent UI: https://app.emely.io/consent

The MCP server publishes its authorization server in the protected-resource metadata at https://mcp.emely.io/.well-known/oauth-protected-resource, including the path-scoped URL https://mcp.emely.io/.well-known/oauth-protected-resource/mcp.

A person connecting an assistant to the MCP server requests:

openid graphql:role:user

The token then holds only the user role, the same role the emely app uses. The MCP server’s user tools run as that person, with the app’s own permissions: the assistant sees and does what the person sees and does in the app, never more. The MCP server accepts a token on the user tools only when its allowed roles are exactly user.

Staff connect as users. A staff member who requests openid graphql:role:user gets a token with only the user role, even though their account also holds staff roles. Staff rights never reach the user tools.

The society, catalogue-import and staff tools, and the REST API, use the api roles instead:

openid graphql:role:api_user
openid graphql:role:api_operator

api_user serves a caller’s own society memberships, api_operator the shared society catalogue and the staff tools. Every role scope restricts the token to that role. Both servers refuse a token whose allowed roles mix user with an api role or with a staff role. A token minted without a role scope carries the account’s full roles and is refused. Do not request the plain graphql scope together with a role scope; the authorization server refuses the combination.

The MCP server advertises openid, graphql:role:user, graphql:role:api_operator and graphql:role:api_user in its protected-resource metadata. Its 401 challenge asks for openid graphql:role:user, the common case.

A person often belongs to several workspaces: their own, a label’s, a publisher’s. The assistant always works in one workspace that you chose, so that it never reads or changes the wrong catalog.

  • Choose. Before the assistant reads or changes a catalog, it lists your workspaces (list_my_workspaces) and asks you which one you mean. It then chooses that workspace with select_workspace. You can only choose a workspace you belong to. If you have one workspace, you still choose it once.
  • Ask. current_workspace answers which workspace is chosen, at any time.
  • Every answer says it. Each answer carries the workspace it is about, and the assistant tells you. If you were removed from the workspace you chose, the answer names it with no name ({id, name: null}) and asks you to choose again.
  • Switch. Switching is only select_workspace. Its answer names the workspace you left and the workspace you are in now. No other tool changes the choice.
  • Refusals. Until you choose, a catalog read or a change is refused with “Choose a workspace first”. A change names the workspace it is meant for and is refused, with nothing sent, when that is not the chosen workspace. A change to an item that your chosen workspace cannot change, or that would go through another workspace’s access, is also refused. If you are removed from the chosen workspace, the assistant is refused there and asks you to choose again.

emely remembers the choice for you and for each assistant app (Claude, ChatGPT), until you switch. A newly connected assistant app starts with no workspace chosen. Two chats in the same app share the choice. A chat that still thinks it is in the old workspace names the old workspace on its change, so the change is refused, never sent to the wrong place.

  • Access tokens are JWTs signed with RS256 and expire after 15 minutes.
  • Refresh tokens expire after 30 days. Refreshing is the client’s job: the MCP server never holds a refresh token, so a long chat keeps working while the client refreshes in the background.
  • An expired token gets HTTP 401 with the WWW-Authenticate challenge (resource_metadata, scope, error="invalid_token"), so the client refreshes or asks you to reconnect. That also holds when the token runs out during a call, between the MCP server’s check and the backend’s.
  • To disconnect an assistant, revoke it in the emely app under connected apps.
  • The token carries the caller’s user id. Every write is attributed to that user.