Connect Claude

Get the connection URL first

There is no single MCP host for this product. Each deployment publishes its own, and a deployment with MCP switched off publishes none at all. Open Settings → MCP in the helpdesk to see whether this one serves /mcp and at which URL.

The host below is written as <MCP-HOST-PLACEHOLDER> everywhere it appears. It is not a real address; substitute the URL that screen shows you.

Every fact below is taken from source: the transport, the route, the discovery documents and the authentication configuration.

What you are connecting to


Path	`/mcp`
Methods	`GET`, `POST`, `DELETE`
Transport	Streamable HTTP
Sessions	Stateful, so a session is established and reused
Credential	An OAuth 2.0 bearer token, in the `Authorization` header

Source: services/runtime/src/runtime/mcp/asgi.py:38-39 for the path and methods, services/runtime/src/runtime/mcp/asgi.py:74-87 for the transport, the session manager and the authentication chain.

The procedure

1. Get the server URL from the operator

It is the deployment's public base URL with /mcp on the end:

https://<MCP-HOST-PLACEHOLDER>/mcp

That base is whatever the operator set as MCP_PUBLIC_BASE_URL. The discovery documents publish the same value, built from configuration rather than from the request, so the two cannot disagree.

Source: services/runtime/src/runtime/mcp/well_known.py:35-40 and services/runtime/src/runtime/config.py:553-559.

2. Add the server to your client

In claude.ai or Claude Desktop, open Customize → Connectors, click +, choose Add custom connector, paste the URL and click Add. On Team and Enterprise an owner adds it once at Organization settings → Connectors (Add → hover Custom → Web) and members then click Connect on it. In Claude Code:

claude mcp add --transport http auralis-helpdesk https://<MCP-HOST-PLACEHOLDER>/mcp
# then, in a session: /mcp → choose auralis-helpdesk → Authenticate

Any client that speaks Streamable HTTP and OAuth works the same way — see Connect ChatGPT and Connect Gemini. The steps below are what a spec-compliant client does for you; they are written out so you can tell where it stopped if it fails.

3. The client discovers where to authenticate

An unauthenticated request to /mcp is answered with a 401 whose WWW-Authenticate header names the resource metadata document. The client fetches it:

https://<MCP-HOST-PLACEHOLDER>/.well-known/oauth-protected-resource/mcp

The same document is also published at the bare path /.well-known/oauth-protected-resource, for clients that have not adopted the resource-scoped one. Both are public, which they have to be: a client has to read them before it holds any credential.

Source: services/runtime/src/runtime/mcp/well_known.py:1-21 and services/runtime/src/runtime/mcp/well_known.py:62-68.

4. The client reads which scope to ask for

The metadata document carries scopes_supported, holding the one scope this server requires. That field is the only signal a client has to request the scope on its first attempt, instead of discovering it from a refusal.

Source: services/runtime/src/runtime/mcp/well_known.py:43-56.

5. The client registers itself and authenticates

MCP clients register themselves with the authorization server through Dynamic Client Registration, then run an authorization code flow with PKCE. You sign in as yourself in a browser window. The client must include the scope from step 4 in its authorization request, otherwise the token it gets back will be refused at every call.

Source: services/runtime/src/runtime/mcp/verifier.py:13-30.

6. Confirm with a tool call

Ask the client to list tickets. That drives list_tickets, which needs only the viewer role and no arguments at all.

If you belong to more than one workspace, the first call is refused and asks you to name one. Ask again naming the workspace, which the client passes as workspace_id.

Source: services/runtime/src/runtime/mcp/tools.py:423-455 and services/runtime/src/runtime/mcp/tools.py:249-285.

If a step fails

Each of the common failures has a distinct symptom. Troubleshooting lists them with what to do about each.

On this page