MCP and agent clients¶

HLA-Compass exposes governed data and tools to external MCP clients. Choose the connection that fits your client:

Connection	Where it runs	Authentication	Server or command
Hosted OAuth	Chat apps with remote MCP and OAuth support	Your HLA-Compass sign-in and an organization-bound grant	Copy the URL ending in `/mcp/connect` from Profile → Connected apps
Hosted API key	Clients that accept a static bearer token or custom header	A personal HLA-Compass API key with explicit permissions and scopes	The same environment's API origin, path `/mcp-api`
Local stdio gateway	Codex, Claude Code, and other clients able to start a local process	The SDK's saved session or configured API key	`hla-compass mcp gateway --env dev`

The hosted endpoints use Streamable HTTP. A local stdio command is a different transport: do not paste it into a remote server URL field. Custom connections do not require an HLA-Compass marketplace listing. Repository-local plugin manifests are maintainer validation artifacts until a reviewed, release-pinned remote source is published; this guide does not claim a marketplace release.

Connect a chat app with OAuth¶

Sign in to the intended HLA-Compass environment and select your organization.
Open Profile → Connected apps and copy the MCP URL. For Alithea Bio dev it is https://api.dev.alithea.bio/mcp/connect. Use the displayed URL for other environments; the Hub home-page URL is not an MCP endpoint.
Add a custom remote MCP connection in the chat app, using that entire URL and OAuth authentication. HLA-Compass provides OAuth discovery and dynamic client registration; a personal API key is not an OAuth client secret.
Complete HLA-Compass login and any MFA prompt. Review the app, organization, role and permitted effects on the consent page, then select Connect.
Enable the connection in a new conversation and start with read-only discovery. An installed connection alone does not prove a tool call worked.

A connection stays in the organization approved at consent, even if you later switch organizations in the Hub. Current membership, catalog permissions and your granted role ceiling are checked on requests. A platform administrator's connection has at most org-admin authority in that organization; it does not grant platform-wide administration. To use another organization, make a separate connection and review its consent.

Privileged actions can require recent MFA. For oauth_reauthentication_required, reconnect and verify your sign-in; refreshing the tool list does not renew MFA. Profile → Connected apps → Disconnect revokes the selected grant without deleting data or results. That list covers OAuth grants, not API keys; revoke keys in Profile → API keys.

Claude¶

Open Customize → Connectors, add a custom connector, enter the copied HLA-Compass OAuth URL, then connect and complete consent. For Team and Enterprise, an Owner or Primary Owner first adds the server through Organization settings → Connectors → Add → Custom → Web; members then connect with their own identities. Enable the connector for the conversation from + → Connectors. Remote connections originate from Anthropic's servers, including when using Claude Desktop, so a loopback URL is not the hosted connection. Account limits and organization policy apply. Claude's custom connector guide describes the current menus and availability.

ChatGPT¶

Enable Settings → Security and login → Developer mode, if your account and workspace policy allow it. Open ChatGPT Plugins, select +, name the connection, and use the copied HLA-Compass URL under Connection. Create it, finish OAuth sign-in, and review the discovered tools. Add the connection from the tools menu in a new conversation. After a server tool or authentication change, refresh the connection's metadata and start a new conversation. These are custom MCP instructions, not an assertion that every ChatGPT account can install or use write-capable connections. See OpenAI's current connection instructions.

Mistral¶

Mistral's current official setup guide describes its Work interface. Open Connectors → + Add Connector → Custom MCP Connector, use a unique name such as HLACompassDev, enter the full HLA-Compass OAuth URL, and select Connect. Complete the detected OAuth flow and HLA-Compass consent. Connector creation requires an administrator; personal account owners are administrators by default. Under the connector's Functions tab, retain manual approval for write actions. The guide also describes bearer-token authentication and lists dynamic tool discovery, resources and automatic prompt templates as unsupported. Use the controls available in your Mistral account; these Work instructions do not establish identical menus or capabilities in every Le Chat account. See Mistral's MCP connector guide.

Client instructions above were checked against official documentation on 9 September 2026. This is setup guidance, not evidence that a particular account's end-to-end research workflow has passed. If custom connections are unavailable, ask that client's workspace administrator to enable the feature. HLA-Compass permissions do not override the client's account policy.

Connect with an API key¶

Create a dedicated key in Profile → API keys, choose the required read, write or delete permissions and exact MCP scopes, then configure the client's protected credential field. The endpoint is /mcp-api on the selected environment's API origin, for example https://api.dev.alithea.bio/mcp-api. The server accepts either Authorization: Bearer <HLA_API_KEY> or X-API-Key: <HLA_API_KEY>. Basic authentication is not supported. The placeholder is explanatory: enter the real key only in the client's credential store.

Use this mode only when the client supports the required authentication header. It does not perform OAuth consent or appear in Connected apps. Keys remain bounded by their organization, permissions, scopes and current authorization. A key cannot satisfy tools that require an interactive bearer session. Rotating or revoking a key is separate from disconnecting an OAuth app. See API and authentication for key lifecycle and SDK credentials.

Install and authenticate a local gateway¶

These commands use SDK 5.9.2. Hosted OAuth connections do not require a local SDK installation. A local gateway uses the permissions of its configured HLA-Compass credential. For dev/staging, download the exact TestPyPI candidate; installation dependencies resolve only from PyPI.

For a gateway using your interactive login, remove any HLA_API_KEY override from that process environment; a configured API key takes precedence over the saved session.

python -m pip download --index-url https://test.pypi.org/simple/ --no-deps --only-binary=:all: --dest sdk-wheel "hla-compass==5.9.2"
python -m pip install "hla-compass[mcp]==5.9.2" --index-url https://pypi.org/simple/ --find-links sdk-wheel
hla-compass auth login --env dev
hla-compass mcp doctor --env dev
hla-compass mcp gateway --help

mcp doctor checks authentication, protocol initialization, paged tool discovery and tool schemas. Its JSON output reports discovery_verified and toolExecutionVerified: false when those checks pass. It never invokes a tool; execution, authorization for a particular action, and scientific results still need separate verification.

The packaged Codex and Claude Code plugins invoke the bare hla-compass executable. The client process must inherit the environment that contains it. For GUI clients, prefer an isolated client-wide command:

pipx install "hla-compass[mcp]==5.9.2" --index-url https://pypi.org/simple/ --pip-args="--find-links=$PWD/sdk-wheel"
command -v hla-compass

Ensure the pipx apps directory is on the client's PATH, then restart the client. If policy requires a project virtual environment, launch the client from that activated environment or set an absolute executable path in a standalone MCP configuration. Do not put a virtual-environment-specific path in a distributable plugin manifest.

If a client reports that the executable is missing, verify the active Python environment and SDK version. Do not make the client silently install an unreviewed package or repository checkout.

Generic stdio configuration¶

{
  "mcpServers": {
    "hla-compass": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/hla-compass",
      "args": ["mcp", "gateway", "--env", "dev"]
    }
  }
}

Use "command": "hla-compass" only when the MCP client demonstrably inherits the PATH entry printed by command -v hla-compass.

The configuration contains no bearer token or API key. The explicit --env dev matches the login command above. Choose staging or prod only deliberately; without --env, the SDK resolves its selected environment and HLA_COMPASS_ENV override. For a custom deployment, configure the exact HLA_API_ENDPOINT in the SDK process environment; do not infer prod from an unrecognized hostname. Keep credentials in the SDK's credential store or a protected process environment, outside prompts and shared configuration files.

The gateway forwards calls to /mcp for a saved bearer session and /mcp-api for an API key. It reads all discovery pages and preserves standard tool metadata, structured results, images, resource links and structured errors. hla-compass mcp serve and mcp schema are module-authoring previews, not replacements for the platform gateway. The gateway can attempt to open a returned module UI URL on the local machine; remote chat apps return a link for the user to open. Browser login remains separate from an API key.

Compass chat and external MCP servers¶

Compass's built-in chat uses its own governed tool registry. Its tool groups are categories of platform and module tools, not connections to external MCP servers. The Tool suggestions controls only determine which optional groups appear in @ autocomplete; they do not restrict the agent's tool permissions. Platform tools remain suggested. Authorization is enforced on the server.

SQL availability differs by interface: Compass chat currently offers query_data only to platform administrators and follows the selected chat mode's approval policy. External MCP offers it to authorized bearer/OAuth sessions without that role requirement, with confirm=true required per call. Both paths use the same governed, read-only catalog query handler; a restricted data profile can still prevent raw SQL. Other Compass users use the typed data tools available in their chat inventory.

There is currently no user-facing contract for registering an arbitrary remote MCP URL or local stdio command as a provider inside Compass. Profile → LLM keys configures supported model-provider credentials for Compass chat; it does not add MCP servers. To combine Compass with another MCP service today, configure each in an external client that supports both. Each service retains its own authentication and permissions.

Tools are grouped into action families¶

Platform tools are grouped by domain and selected with an action argument, rather than exposed as one tool per operation. module_runs covers status, results, logs, listing, and comparison; storage_objects covers browsing through deletion; and so on. tools/list is authoritative — read it rather than assuming a name.

{ "name": "module_runs", "arguments": { "action": "status", "runId": "…" } }

action is required. Omitting it, or passing one the tool does not declare, is rejected before the call runs.

Permissions are per action, not per family. A read-only API key can call storage_objects with action="browse" but not action="delete", and each action requires its own exact scope. Grouping never widens what a read action needs, and never narrows what a destructive one does.

A few tools stay standalone because they are used constantly or have no siblings: query_data, describe_schema, inspect_scientific_data, manage_api_keys, open_tool_window, and get_next_actions.

Breaking change. Clients pinned to the previous one-tool-per-operation names (check_run_status, delete_storage_objects, …) must move to the family plus action form. There is no compatibility alias: a stale name returns "unknown tool" rather than silently doing something adjacent.

Safe agent workflow¶

Hosted per-module run tools keep platform controls separate from module-owned parameters. Supply the manifest-defined payload under the stable inputs field. Platform-owned siblings include idempotency_key, executionMode, computeProfile, maxRuntimeSeconds, dataContext, admissionId, and requestFingerprint; version-bound descriptors also expose version. Charged or mutating hosted calls advertise boolean confirm; include "confirm": true only after the user has reviewed and approved the exact call. Read the actual tool schema because optional controls depend on the descriptor.

Use run_module with action="prepare" to obtain a costed plan before action="start". Retain the returned proposed start arguments, including their frozen dataContext, admissionId, and requestFingerprint. Those values come from preparation; never invent them, reconstruct inputs from a summary, or drop the admission fields on an uncertain retry.

After approval, add this platform control to the unchanged proposed start arguments (alongside inputs, never inside it):

{"confirm": true}

This fragment is not a complete run request. Keep every argument returned by preparation and send the resulting arguments to the proposed tool.

The same wrapper applies to hosted native module capabilities. This prevents a permissive manifest from losing legitimate module fields that happen to use a platform-control name. Standard JSON-RPC tools/list clients should read the advertised inputSchema: hosted module parameters are always under inputs, with platform controls outside that object. The hosted transport consumes confirm; it is never forwarded inside the module payload. Local hla-compass mcp schema/serve remain module-local previews and accept the manifest payload directly; hosted tools/list is authoritative for gateway calls.

List visible catalogs, modules, or pipelines before selecting an ID.
Describe the selected resource and compatibility contract.
Prefer read-only typed tools over raw SQL.
Present the inputs, target environment, organization, credit impact, and destructive effect before requesting confirmation.
Reuse the unchanged prepared admission on an uncertain run retry; retain a stable idempotency key for other operations that accept one.
Poll the returned run or job ID to a terminal state.

Review the returned costed plan before admitting a run. Preserve the prepared binding and admission identity; changed inputs or an expired proposal require preparation again. Check the run's recorded settlement instead of inferring a credit charge or refund from a chat message.

A useful first prompt is:

Discover the catalogs and modules I can access in the approved organization. Describe a compatible small analysis and show its exact inputs and costed plan before running it. After I approve, execute once, follow the returned run ID, and return the exact result, provenance and an authenticated HLA-Compass link. Report any tool error instead of inventing results.

External clients can create or update saved notebook artifacts through the advertised notebook tools and return an Open in HLA-Compass link. This does not control a live browser canvas or automatically execute notebook code when opened. Retain notebook identity and revision when updating; conflicts require reviewing the current revision. Opening a module link also does not authorize execution.

A tool can fail inside a successful transport response: the call returns HTTP 200 with no top-level JSON-RPC error, while its result payload carries isError: true and the failure in its content. Always inspect the tool result, not just the envelope. A 200 is not evidence that a run started — confirm the returned run ID and poll it to a terminal state.

Standard MCP annotations communicate whether a tool is read-only, destructive, or idempotent. They are safety hints, not authorization. The platform still enforces role, scope, quota, rollout, MFA, and confirmation rules independently.

When connecting with a personal API key, choose the smallest exact MCP scopes in the profile page. New scope-policy version 1 keys require both the action's permission and its matching scope. Scope checks are exact: for example, modules:write does not satisfy pipelines:write, and wildcard spellings grant nothing. Read-only and publish-only keys intentionally have no mutation scopes. Legacy keys without scopePolicyVersion and with an empty scope set retain MCP scope compatibility: otherwise permitted mutations can still be allowed. Once a legacy key declares any scopes, its scope must match the action exactly. Permissions, current role, resource access and confirmation still apply in both cases. Rotate legacy keys to explicit scoped replacements before giving them to an agent; an empty legacy scope list does not mean read-only access. See legacy-key behavior for the different REST enforcement.

Tools that require a human in the loop — credential management, catalog ingestion and import, module publication, platform-wide resource grants — are marked JWT-only and reject every API key regardless of who created it or what scopes it carries. Machine publication has its own dedicated route (POST /v1/api/modules/publish with a publish-only key); it is not reachable through MCP.

When a tool returns isError=true, preserve its typed code and correct the request. Do not hide an authorization, quota, verification, or rollout-gate failure behind repeated generic retries.

Files and saved reports¶

Use module_runs(action="artifacts") to obtain the selected run's file identities, then module_runs(action="artifact_download") with its exact runId, artifactId, lineageId and versionId. The response authorizes a short-lived download; the client still needs to transfer the bytes. Never substitute a current object key for retained history, and report missing historical checksum evidence.

storage_objects provides upload_initiate, upload_parts, upload_status, upload_complete, upload_cancel and upload_download. Keep the same upload ID, idempotency key and latest revision through retries. PUT exact part bytes with all required headers; only the verified completion receipt proves acceptance. Cancellation preserves files whose completion already won the race.

module_runs also provides reports, attach_report and report_download. Attachment takes completed PDF and snapshot upload references, binds them to the exact completed run, and requires authorization plus confirm=true. Limits are 20 MiB PDF and 5 MiB SDK snapshot JSON. Preserve list pagination and the same attachment idempotency key on retry. Reports are user-supplied, immutable files; they do not change computation outputs or credits. See SDK file and report workflows. Browser PDF export alone does not attach a report.

Catalog Import¶

Catalog Import tools require an interactive bearer session with an authorized administrator role. They use the governed multipart and replace-only ingestion contract; an API key or module-run credential cannot broaden into that control plane.

Credential hygiene¶

Put credentials only in the client's protected credential field, the SDK credential store or a protected process environment. Never paste them into prompts, chat summaries, shared MCP configuration or durable agent files.
Never print presigned upload or result URLs into logs.
Do not let an agent switch organization or environment based only on conversational text.
Require explicit approval for run, publish, ingest, cancel, abort, delete, and other mutating tools.