catalyst-setup

Connect to Catalyst

Goal: end this skill able to name the user's organization and project, having made one real call to Catalyst. Anything less is not connected, however healthy it looks.

These skills drive Catalyst only through the Catalyst MCP server, the catalyst_* tools. Setup is therefore two things: the server is added to the client, and the user has signed in to it with the client's own OAuth flow. There is nothing to install.

1. Check the connection first

Do not start by changing anything. Most sessions are already connected, and a redundant sign-in is the fastest way to make a working setup stop working.

Call catalyst_whoami. Clients prefix tool names (in Claude Code it appears as mcp__plugin_catalyst-ai_catalyst__catalyst_whoami), so match the ending.

• It returns an organization. Connected. Confirm it the way section 5 says, and stop.
• The tool is not there, or it returns `NOT_AUTHENTICATED`. The server is missing or

not signed in. Go to section 2.

2. Add the server and sign in

The Catalyst MCP server is a remote (streamable HTTP) MCP server. It signs in with OAuth in the browser. There is no API key and nothing for the user to paste.

Only clients without the plugin need its address, and the table below carries it. Give the user the command or config for their client; do not quote the address on its own. Keep the X-Catalyst-Plugin-Version header in each non-plugin setup below: it is how the server tells a client set up from these instructions from one added by hand.

For Codex, add this to ~/.codex/config.toml as its own two-line table:

[mcp_servers.catalyst.http_headers]
X-Catalyst-Plugin-Version = "0.7.3"

You cannot do the sign-in for the user. Ask them to do it, and once they say it is done, call catalyst_whoami again. Tools appear when it finishes.

The sign-in must be granted the scopes catalyst:read catalyst:write offline_access. The authorization server has no dynamic registration, so each client signs in with its registered client ID (the table above). Without catalyst:write a signed-in user never sees write tools, whatever their role. Without offline_access there is no refresh token, so the user signs in again each time the session expires.

If the user already added the server by hand in Claude Code and also installed the plugin, they have two copies of every tool. Ask them to remove their own entry.

3. Know what the connection depends on

• The address must be exact. Copy it from the table in section 2 rather than typing

it from memory; a near-miss does not resolve.

• A token only works on the server it was issued for. A token from another server is

refused as NOT_AUTHENTICATED. If sign-in succeeded but calls are refused, check that the client's entry matches section 2 before anything else.

• The tool list depends on the user's role and on the scopes they granted. Write

tools, such as catalyst_apply, or starting or terminating a workflow run, are left out of the list entirely unless the role can write and the sign-in granted catalyst:write. They are not refused when called; they are simply not there. If one is missing, either the role is read-only or the sign-in did not grant write scope. Ask the user to sign in again and approve write access; if the tool is still missing, their role is read-only, so tell them a write role is needed and stop.

4. Read the error, do not guess

Every Catalyst refusal names its own kind and carries an instruction addressed to you. Act on the instruction rather than improvising. Improvising here usually means asking the user for an API key, which is never the right next step.

Two things during sign-in look like errors and are not:

• A `401` with `WWW-Authenticate: Bearer resource_metadata=...` is how sign-in starts.

The client follows that header to find the sign-in server. Nothing needs fixing.

• The consent screen. Partway through sign-in the browser asks the user to approve

access for their organization. If they decline, sign-in stops and no tools appear. The fix is to sign in again and approve.

If a refusal is marked retryable, wait briefly and retry once. If it is not, do not retry at all: a permanent refusal retried looks to the user like a hang.

5. Confirm, out loud

Report two things, from a real call and not from configuration:

• the organization, by name. It is data.attributes.name under getCurrentOrgWithDetails

in the catalyst_whoami answer. If it has no name, give the organization ID instead, and do not explain why the name is missing.

• the project you will work in

Then add one line on write access: whether the write tools are present. Keep it to that. Do not name the server, its address, the API host or any other endpoint; the user is asking whether they are connected, not where to.

If either is unknown, say which, and say what you tried. A confident "connected!" that turns out to be wrong costs more than an honest "the server is added but not signed in".

What is not available over MCP yet

Some things have no catalyst_* tool. Say so in one line and do not improvise a route around it: invoking an app, publishing to a topic, reading or writing state through Catalyst, and cluster diagnostics are not available over MCP yet.

The one exception is an app tunnel, which lets Catalyst call into a process on the user's machine and print inbound requests as they arrive. No tool opens one, so the catalyst-app-tunnels skill uses the Diagrid CLI for that, and only for that.

Rules

• Use the Catalyst MCP tools for everything in Catalyst.
• Never ask the user to paste a token or key of any kind. If one is needed, the

client's sign-in flow supplies it.

• Do not create a project. Every organization gets a project named default with

managed pub/sub, KV, workflow store and agent infrastructure already attached. Use it. A hand-made project that behaves differently is indistinguishable from a broken one to the person asking for help.

• Do not install anything. Everything here runs through the MCP server. Only an app

tunnel needs the Diagrid CLI, and catalyst-app-tunnels installs it when one is needed.

• Name the proof. This skill is done when catalyst_whoami has actually returned an

organization, and you have said so. Configuration that looks right is not proof.