Use Phases from Claude or ChatGPT

Phases exposes its material and simulation tools through Model Context Protocol (MCP). A run started from Claude or ChatGPT belongs to the same account and workspace as a web run, appears in the same run browser, and remains recoverable if the host disconnects or ends the tool call.

Interactive simulation results#

Phases publishes one portable MCP Apps result component for heat treatment, CCT, RSW, and V-Gleeble. Claude and ChatGPT hosts that advertise MCP Apps support can render it inline with the conversation; older clients keep the structured fallback. The component shows the important scientific metrics, a simulator-specific interactive chart, and every retained solver figure in an arrow- and thumbnail-navigable gallery.

The same component also handles durable jobs: an accepted simulation first shows its real queued/running state, then loads only the verified terminal result. Figure links are resolved through the owner-authorized inspect_run tool, so expired signed URLs are not embedded in the component template.

This UI is progressive enhancement. A client that does not support MCP Apps still receives the complete structured result and normal text response. The implementation uses the open _meta.ui.resourceUri contract for portability; ChatGPT's output-template field is included only as a compatibility alias.

The production connector URL is:

https://phasesapi.aerobase.se/mcp

This is the canonical Streamable HTTP endpoint. Existing SSE connections can continue to use https://phasesapi.aerobase.se/mcp/sse, but new Claude and ChatGPT connections should use /mcp.

Connect Claude#

In Claude's Add custom connector form, enter:

The automatic-registration option uses the server's OAuth dynamic client registration endpoint. Do not select None: hosted Phases rejects anonymous MCP traffic. Do not paste an API key or Supabase token into an additional header. Complete the browser login Claude opens and approve the connection.

Anthropic's hosted client-metadata option is not required for this deployment. It can be adopted later, but only after the server has been explicitly qualified for that client-metadata mechanism.

Connect ChatGPT#

Enable connector/plugin developer mode in the ChatGPT workspace that will test the integration, add a remote MCP server, and use:

https://phasesapi.aerobase.se/mcp

Choose OAuth user authentication and complete the browser login. Scan or refresh the tools after a server update so ChatGPT sees the current schemas and safety annotations. Workspace administrators may need to enable developer mode or approve the connector before members can use it.

ChatGPT Actions is not a supported Phases surface. Use the remote MCP connector; do not create or restore an Actions/OpenAPI adapter.

How durable simulations work#

A long solver must not live inside one Claude or ChatGPT tool request. When a durable simulation is accepted, the simulation tool returns an operation_id and a non-terminal status such as queued or running.

The host then follows this lifecycle:

1. Keep the operation_id; it is stable across disconnects and conversations.
2. Wait at least the returned retry interval and call get_operation_status(operation_id). Do not busy-poll.
3. When status is completed, call get_operation_result(operation_id).
4. Use only that verified result for scientific conclusions.
5. Call inspect_run with the returned run version when signed, user-openable plot or artifact links are needed.

get_operation_result returns current status instead of blocking if the result is not ready. Failed, cancelled, and expired operations are terminal and must not be presented as successful science.

This separation is why a Cloud Run request timeout, host timeout, SSE drop, or closed chat does not determine the lifetime of the solver. PostgreSQL workflow state, worker leases, checkpoints, and committed artifact receipts are the authority.

Durable execution is feature-flagged. A deployment operator must enable the durable root, domain, and replay flags and operate the dispatcher/worker fleet. Without that rollout, a simulation may still use the legacy in-process path and remain subject to the host's request timeout.

RSW confirmation#

Generic MCP hosts do not render the web app's RSW configuration card. Before calling run_rsw_simulation, Claude or ChatGPT must show the complete material, plate, waveform, force, timing, and physics arguments and obtain explicit user approval. The exact approved call sets confirm_parameters=true. Any change requires another review.

The backend still canonicalizes and snapshots that input and binds the durable RSW approval to its digest. The MCP confirmation field cannot bypass the web chat's separate configuration-card confirmation path.

Authentication and workspace binding#

The hosted endpoint uses OAuth authorization-code flow with PKCE S256, token refresh/revocation, and dynamic client registration. Discovery is available at:

• /.well-known/oauth-protected-resource/mcp
• /.well-known/oauth-authorization-server

An unauthenticated MCP request returns a bearer challenge pointing to the protected-resource metadata. The MCP session is then bound to the authenticated user and one personal or organization workspace. A later attempt to change the workspace on the same protocol session is rejected.

An optional X-Tenant-Slug request header selects an organization workspace. Without it, Phases resolves the user's personal workspace. Only members and admins may open the hosted connector; guests and viewers are refused. Every tool call still rechecks feature prerequisites and write authorization.

Available tools#

MCP exposes the 13 web-chat tools plus four MCP-only lifecycle tools:

• log_note records a short activity annotation.
• reset_session starts a fresh Phases product session without reconnecting.
• get_operation_status reads durable status without waiting.
• get_operation_result consumes a verified terminal simulation result.

Every tool advertises a title, explicit input and output schemas, and safety annotations. The complete parameter reference is in the tool reference.

Local development#

Run local stdio from a prepared Python 3.11 backend environment:

python mcp_server.py

For isolated local HTTP testing only:

DISABLE_AUTH=true python mcp_server.py --transport streamable-http

Legacy local SSE remains available with --transport sse. DISABLE_AUTH=true creates an insecure super-admin development identity and must never be enabled in a shared, staging, or production environment. Production operators must also configure MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS; otherwise the SDK's DNS-rebinding protection rejects requests.

Publishing and compliance status#

The repository is technically prepared for connector testing after this revision is deployed: stable HTTPS Streamable HTTP, legacy Claude SSE, OAuth/DCR/PKCE discovery, server-side tenant authorization, structured results, safety annotations, durable operation recovery, activity logs, and run/artifact persistence are implemented.

That is not the same as marketplace approval or legal compliance. Before a public Claude directory or ChatGPT listing, Aerobase must still:

• deploy and qualify the exact revision with the durable worker fleet and feature flags;
• run MCP Inspector plus Claude and ChatGPT end-to-end tests, including disconnect/reconnect and invalid/unauthorized calls;
• publish reviewed privacy, terms, data-use/deletion, support, and security contact pages;
• verify the production domain and complete each platform's submission and security review;
• review whether the OAuth proxy should replace its current Supabase user JWT with a least-privilege, MCP-audience connector token.

Until those external and organizational gates are complete, describe Phases as protocol-ready for private/developer testing, not as approved, certified, or publicly listed.

Common failures#

MCP-origin sessions open in the web app as read-only external-agent replays. Their Simulation Runs tab remains available regardless of whether Claude or ChatGPT is still connected. See sessions, runs and artifacts.