Use Phases through MCP

Phases exposes one main MCP tool, ask_phases. Claude, Codex, ChatGPT, or another MCP host sends your request to the Phases agent, which uses its own engineering tools and returns its answer, scientific results, figures and files. Follow-up messages continue the same Phases conversation.

Runs belong to your authenticated account and workspace and appear in the web run browser. Durable runs remain recoverable after the host disconnects when the deployment has enabled durable execution and its worker fleet.

Answers, figures and results#

The response contains the agent's complete answer, original structured tool results, signed figure/download URLs, and operation status. The portable MCP Apps component displays the answer with tables, a figure gallery and files. Hosts without MCP Apps support receive the prose, structured results and resource links. The surrounding host controls its own final response, so Phases cannot force every host to reproduce its answer or render the entire web app.

The component uses the open _meta.ui.resourceUri contract; ChatGPT's output-template field is only a compatibility alias. Signed links expire; ask Phases to show the run again to obtain current links.

Choose your environment#

Choose OAuth authentication and sign in to the selected environment. Keep separate connectors for staging and production; accounts, workspaces, session handles and runs must stay within their originating environment. A merge into dev does not update the production connector.

Both URLs use the canonical Streamable HTTP endpoint. Existing SSE connections can use https://phasesapi.aerobase.se/mcp/sse only when a deployment operator has temporarily enabled that deprecated compatibility route. It is disabled by default everywhere; new Claude and ChatGPT connections must 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.

Other MCP hosts and checking the connection#

For another MCP host, including Codex, use its remote Streamable HTTP connector with the URL for your chosen environment and complete OAuth login. Refresh the tool catalog after reconnecting or after a server update. The default public catalog contains only ask_phases; the Phases agent chooses its engineering tools internally.

After connecting, try this short sequence in one conversation:

1. Ask: "Use DC04. Show its material information without running a simulation."
2. Follow up: "Which material did we select?" Check that Phases retains the selection without asking you to copy a session ID.
3. Request a heat-treatment or CCT simulation with your chosen parameters. Check the full answer, figures, downloadable files and recorded run. If the operation is pending, wait for its verified result rather than starting it again.
4. Ask a question about that result in the same conversation. Check that Phases refers to the existing run and preserves its scientific caveats.
5. For RSW, check that the host presents the resolved parameters for approval before execution. Declining approval must not start the solver.

A host with MCP Apps support can show the portable answer and figure viewer. Other hosts can present the text and openable result links. If the old direct tool list still appears, refresh the connector and verify the environment; an operator may also have enabled the compatibility catalog.

How durable simulations work#

When a durable simulation is accepted, ask_phases returns status: pending and an operations entry with operation_id and retry_after_seconds.

1. Keep the returned product_session_id and operation handle.
2. Wait at least the retry interval, then call ask_phases with that same product_session_id and operation_id, leaving message empty.
3. Pending checks return current status without another model call. When ready, Phases retrieves the verified result, explains it and returns its figures.
4. Never resubmit a simulation merely because it is still pending or the host disconnected. Failed, cancelled and expired operations are not successful science.

A temporary status or result-service outage preserves the operation handle and retry delay. Wait and check the same operation again. A missing or inaccessible operation is reported as a failure: verify the handle, account and environment instead of automatically submitting a replacement.

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. The same machinery is what lets a web session survive a closed tab; Long-running simulations explains it from the user's side.

Durable execution is feature-flagged. When the durable root, domain and replay flags — feature.durable_simulation_jobs, feature.durable_ht_cct_jobs, feature.durable_rsw_jobs, feature.durable_vgleeble_jobs, feature.durable_custom_simulator_jobs and feature.durable_workflow_replay — are enabled for a workspace, an operated dispatcher/worker fleet owns the run after admission. A deployment that has not enabled them and does not run that fleet can fall back to the gated in-process path, where a simulation remains subject to the host's request timeout.

RSW confirmation#

Generic MCP hosts do not render the web app's RSW configuration card. Before executing run_rsw_simulation, Phases resolves one immutable effective request and asks the host to show it for explicit approval. The review expands every omitted default and template value, resolves both plates, records execution mode and template provenance, and binds an inherited active material by its definition/card hashes without exposing private card bytes. A caller-supplied confirm_parameters=true cannot authorize the run.

Rejected approval, a client without elicitation support, or any change to the arguments, template, execution policy, or inherited material stops before solver execution and requires a new review. After acceptance, the backend executes the same resolved snapshot and verifies its digest again; it does not re-read mutable material or template state. The MCP path remains separate from the web chat's configuration-card confirmation path.

Approval is single-use and fail-closed. If the host loses the terminal response after you accepted, inspect existing runs and operation status before approving again; the original approval cannot be replayed. This avoids duplicate solver starts at the cost of requiring a fresh review after an ambiguous failure.

run_simulator and publish_simulator_draft work the same way: a first call that returns a review payload, then an accepted host approval before anything executes or is published.

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. Guests are refused; the main agent requires member or admin access because it can change state and run simulations. Each internal operation still checks its own role; publication requires admin access. The direct-tool compatibility profile permits viewers to use allowed reads. Every call rechecks current membership and feature prerequisites. Your workspace's run and storage allowances are shared with the web app rather than separate; see Workspace limits and features.

Product-session continuity#

The network connection and MCP transport session are not the Phases conversation. A successful hosted tool result returns the opaque handle both as ordinary structured content in product_session_id and, for capable hosts, as _meta["se.aerobase/productSessionId"]. ask_phases accepts an optional product_session_id argument, which is the most portable way for a generic client to continue the same active material, runs and confirmation state. Hosts that preserve extension metadata may instead send params._meta["se.aerobase/productSessionId"]; a bounded Aerobase-Product-Session-Id request header remains a transport fallback.

Treat this as an opaque handle, not a credential. Phases reauthorizes its owner, workspace, MCP origin and deletion state on every request. Omitting it creates a fresh product session; changing OAuth tokens, user-agent strings or connections does not implicitly merge conversations. To explicitly start over, omit the handle on the next ask_phases call and retain the new returned handle. The user does not need to copy IDs manually: the host keeps the handle as conversation state. Phases cannot infer which host chat a request belongs to if the host discards that handle.

Main tool#

ask_phases accepts:

Request examples for client implementers#

These are the arguments to ask_phases, not complete JSON-RPC envelopes. Generate a new turn_id for each new message and reuse it only when retrying that exact message. A first request omits product_session_id:

{
  "message": "Use DC04 and show its material information. Do not run a simulation.",
  "turn_id": "material-selection-1"
}

Read the returned product_session_id and retain it for this host conversation. For the next request, replace the placeholder with that exact returned value:

{
  "message": "Which material did we select?",
  "product_session_id": "<returned-product-session-id>",
  "turn_id": "material-follow-up-2"
}

When a later simulation returns a pending operation, wait its retry_after_seconds, then retrieve it through the same tool:

{
  "message": "",
  "product_session_id": "<returned-product-session-id>",
  "operation_id": "<returned-operation-id>"
}

Retrieve an operation separately from a new message. Preserve the handle through reconnects; omit it only when intentionally starting a new conversation. For a host approval, continue the original MCP approval exchange with its sealed request state. A new message saying "approved" is not that exchange.

Reading the response#

Ordinary agent responses have type: phases_agent_response and schema_version: 1 in structured content:

completed can describe a conversational answer; only verified simulation results establish that a simulation completed. Required approvals use the host's MCP approval exchange and must not be treated as completed work. Privacy and aggregate output limits still apply. At most 128 downloads per run are included; warnings disclose additional files or retrieval failures. Open the run in Phases to browse the complete file list.

Retry deduplication uses the existing durable ADK turn store when enabled. Ordinary conversation history and active-material state use the existing product session. The deployment still needs configured model credentials.

The agent uses the same root Phases agent and application tools as chat. Web-specific graph study/Ultra routing is not exposed through this tool; those workflows have a separate web approval/resume protocol. Workspace feature flags, quotas and human approval still apply.

The tool reference describes the internal capabilities the agent can use. Direct tools are hidden by default. Operators migrating an existing integration may temporarily set MCP_ENABLE_DIRECT_TOOLS=true to retain the previous catalog alongside ask_phases; new integrations should use the main agent.

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 requires both explicit compatibility and insecure-local flags:

MCP_ENABLE_LEGACY_SSE=true DISABLE_AUTH=true python mcp_server.py --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, optional 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. If something goes wrong that none of the responses above explain, Reporting a problem says what to collect.