Skip to main content
The MCP server authenticates every request with an OAuth access token issued for your Koalr account. There are no API keys to copy and nothing to store in a config file beyond the server URL.

​
The flow

  1. Your client discovers the server’s OAuth metadata from the server URL.
  2. A browser window opens on Koalr’s sign-in. Sign in as you normally would.
  3. A consent screen names the client and the access being granted. Approve it.
  4. The client receives a token and starts calling tools.

​
What a token grants

  • Your identity. Tools run as you, with exactly your permissions: the workspaces you belong to and the sites you are assigned to.
  • Read-only access. There are no write scopes.
A token does not grant access to any organisation you are not a member of, and adding you to a new workspace in Koalr makes it visible on the next list_workspaces call without reconnecting.

​
Disconnecting

  • Remove the server from your client and the agent stops immediately.
  • Sign-ins are short-lived and expire within 24 hours. If you need a connection cut off sooner, email support@koalr.ai and say which client you used.
  • Membership is refreshed within about 30 seconds, so if you are removed from a workspace, access stops within about 30 seconds rather than when the sign-in expires.

​
Multiple workspaces

Agencies do not need one connection per client. You choose a default workspace when you sign in, and your agent can switch to any other workspace you belong to by passing its org_id. Ask it to “list my workspaces” to see them.

​
Errors

Two things arrive as HTTP statuses: Everything else comes back in the tool’s reply text, beginning “Request refused”:
  • Access. A workspace or site outside your access, or an id that does not exist, returns the same message: “No such site, or you do not have access to it.” Call list_workspaces and list_sites for valid ids rather than guessing.
  • Rate limits. Over the limit, the reply says so and asks you to wait. See Limits and security.
  • Failed lookups. After 20 failed workspace or site lookups in an hour, the reply asks you to wait an hour and fetch valid ids from list_workspaces and list_sites.