TrialStack Catalyst MCP

TrialStack Catalyst is the governed agent interface for TrialStack, the clinical development system for teams and agents. It is the MCP layer between TrialStack and an AI client such as Codex or Claude. It exposes a remote Model Context Protocol endpoint at https://api.trialstack.com/mcp so the client can work with governed organization data without receiving a general-purpose TrialStack API credential.

Catalyst provides three complementary AI surfaces:

• MCP tools let the client search, fetch, and call governed TrialStack operations.
• MCP prompts provide reusable read, review, and change-preparation workflows to clients that support MCP prompts.
• The Catalyst agent skill teaches supported coding agents when to use each tool and how to preserve the two-step change approval boundary.

The AI client handles the conversation and tool selection. Catalyst handles TrialStack authentication, organization scope, capability checks, operation policy, and execution. Catalyst is an interface into the governed clinical development system, not a separate product category or an autonomous source of truth.

Before you connect

Access is organization-scoped. TrialStack verifies the signed-in user, selected organization membership, current business-role capabilities, and the organization’s Catalyst rollout setting on every connection. A user needs Use MCP read tools; changes additionally need Use MCP change tools and the capability required by the underlying operation.

If the organization is unavailable during authentication, ask a TrialStack administrator to confirm that Catalyst is enabled and that your business role includes MCP access.

Connect from Codex

In the Codex app, open Settings, select MCP servers, and add a Streamable HTTP server with this URL:

https://api.trialstack.com/mcp

Save the server, restart Codex, and select Authenticate. Sign in to TrialStack, choose the organization you want Codex to work with, review the requested access, and approve the connection. Type /mcp in the composer to confirm that trialstack-catalyst is connected.

You can configure the same connection from a terminal:

codex mcp add trialstack-catalyst \
  --url https://api.trialstack.com/mcp
codex mcp login --scopes user:org:read trialstack-catalyst

Codex discovers the OAuth resource from Catalyst’s protected-resource metadata, so no separate oauth_resource override is needed. The explicit login scope keeps the OAuth grant limited to the organization selector Catalyst requires.

The Codex app, CLI, and IDE extension share MCP configuration for the same Codex installation.

Connect from Claude

In Claude, Claude Desktop, or Cowork, open Customize, select Connectors, and add a custom connector with this URL:

https://api.trialstack.com/mcp

Select Connect, sign in to TrialStack, choose the organization you want Claude to work with, review the requested access, and approve the connection. Enable the Catalyst connector for each conversation where Claude should use TrialStack tools.

On Claude Team or Enterprise, an owner must first add the custom web connector under Organization settings → Connectors. Individual members then connect their own TrialStack account. Claude reaches remote connectors from its cloud infrastructure, so the Catalyst endpoint must be available over public HTTPS rather than only from a local network or VPN. See Claude’s custom connector guide for current plan and administration details.

To configure Claude Code, run:

claude mcp add \
  --transport http \
  --scope user \
  trialstack-catalyst \
  https://api.trialstack.com/mcp

Open Claude Code, type /mcp, select trialstack-catalyst, and complete the browser authentication flow. See the Claude Code MCP guide for other scopes and connection-management commands.

Verify the connection

Restart or reload the client after adding Catalyst, then confirm that the trialstack-catalyst server and its tools are visible. Start with operation discovery, which does not depend on your organization already containing a trial:

Use TrialStack Catalyst to find operations related to trials. Do not make changes.

Then test an organization-scoped read:

List the trials available in my selected TrialStack organization.

A successful connection and the number of records are separate checks. A response with total: 0 means Catalyst authenticated successfully and the selected organization currently contains no matching trials. It is not a 404, an OAuth failure, or a broken MCP connection. Confirm the organization selected during authorization if the result is unexpectedly empty.

Use the agent skill

The TrialStack Catalyst Codex plugin includes the trialstack-catalyst skill. It acts as a compact operating guide for agents: start read-only, choose the smallest relevant tool, report record identifiers, distinguish empty data from connection errors, and require a separate approval message before execution.

The skill complements the server rather than replacing its controls. Catalyst still enforces OAuth organization scope, business-role capabilities, operation exposure, one-time intents, and expiry at the API boundary even when a client does not load the skill.

Use Catalyst prompts

Catalyst publishes reusable prompts through MCP. In clients that expose MCP prompts, select one of these templates and provide its arguments:

Prompt	Arguments	Purpose
discover-trialstack-data	goal	Explore organization data in read-only mode and report empty results accurately.
review-trial	trialId, optional focus	Review one trial and related governed records without filling data gaps with assumptions.
prepare-governed-change	request	Discover the exact operation, validate the input, and create a preview without executing it.

You can use the same workflows as ordinary conversation prompts when a client does not expose the MCP prompt picker:

Discover the TrialStack data related to [study or question]. Work read-only,
cite the record identifiers you use, and distinguish empty data from a
connection error.

Review TrialStack trial [trial ID] with a focus on [topic]. Use only governed
read operations and identify missing data rather than making assumptions.

Prepare this governed TrialStack change: [requested change]. Show the exact
operation, effect, input, and complete preview. Do not execute it.

Treat these prompts as starting points. Keep the record identifiers, requested scope, and approval boundary explicit when adapting them.

Understand the tools

Tool	Use it for	Changes data
search	Find records across searchable governed collections.	No
fetch	Retrieve one record by entity type and ID.	No
search_operations	Find operations in the governed OpenAPI-derived catalog.	No
describe_operation	Inspect an operation’s exact input and authorization contract.	No
call_read_operation	Invoke a catalog operation marked read-only.	No
prepare_change	Validate a proposed change and create a ten-minute preview.	No
execute_change	Consume the exact approved intent once.	Yes

For a governed change, ask the client to prepare but not execute it. Review the complete preview, then explicitly approve execution in a follow-up message. Changed input, expired intents, and replay attempts are rejected.

Administrative identity, billing, onboarding, consent, raw chat, webhook, credential, binary-download, streaming, hard-delete, and purge operations are not exposed. Long-running generation, verification, import, and export routes return their normal asynchronous TrialStack run or request identifiers.

Follow the governed agent workflow

For reliable changes, use this sequence:

1. Confirm that the organization shown in Catalyst’s server instructions is the organization named by the user. Reconnect and select the correct organization if it does not match.
2. Discover and describe the relevant operation, then read the current record. For Trial Design and relationship changes, use the stable entity identifier named by the operation description rather than a version-row identifier.
3. Prepare the complete change and show the preview without executing it.
4. Wait for explicit approval in a later user message, then execute the exact prepared intent once.
5. If execution returns an unexpected error, read back the affected record before retrying. Persistence can complete before response serialization, and an immediate retry may create a duplicate.

For asynchronous exports, retain the returned workflow or request identifier and poll the matching status operation. Readiness indicates whether authored data can enter a standards workflow; it is not itself a completed formal CDISC CORE conformance result.

Roll out access

TrialStack administrators enable read and write access separately for an organization. Start with read access in a private pilot. Enable change tools only after reviewing the organization’s business roles and after operators have confirmed the two-step approval experience in their MCP client.

The server stores an intent hash, operation identity, actor, organization, client identity, expiry, and compact outcome. It does not persist OAuth tokens or full proposed request bodies in the intent audit record.

Troubleshoot

The endpoint returns 404

Confirm that the URL is exactly https://api.trialstack.com/mcp and that the deployed TrialStack environment includes Catalyst. Opening the endpoint as an ordinary browser page is not a complete MCP test; use an MCP client or a protocol request.

Authentication returns 401 or does not start

Reconnect the server and complete the OAuth flow. Do not add a manual oauth_resource value: Catalyst advertises its OAuth resource and authorization server through protected-resource metadata.

Access returns 403

The authenticated user or selected organization does not have the capability required by that tool or operation. Ask a TrialStack administrator to check the organization rollout setting and your business role.

The browser ends on a localhost connection error

Some CLI clients use a short-lived localhost callback during OAuth. If the CLI already reports that authentication succeeded, the browser callback may simply have been consumed before the tab retried. Verify the server with /mcp or a read-only prompt before restarting authentication.

Catalyst returns zero trials

total: 0 is a valid organization data result. It means the selected organization currently has no matching trials. Create or connect a trial in that organization, or reconnect Catalyst and select the organization that owns the expected data.