Building with Claude Code

In a Helix project, Claude Code does the building: it scaffolds functions, starts the local dev server, wires authenticated services, tests routes, and deploys. Start it with claude inside the project folder. The CLI’s MCP server gives the agent direct access to the platform, so most of the time you describe the outcome and the agent runs the commands.

Using the MCP server is required for this workflow. Without it Claude can still edit files, but it cannot drive Helix.

What the agent can do

• Write the app. Functions in functions/ and the front end in app/. It’s ordinary TypeScript, so you can read and edit anything it writes.
• Run and test locally. The agent starts the dev server itself, calls routes, and reads execution logs to find errors.
• Use authenticated services. Function code calls ctx.http.authed('alias'); the alias points at IT-managed credentials the agent never sees.
• Deploy. The agent deploys the project and reports the project ID and live URL.

How the agent connects: MCP

helix init writes an .mcp.json file into the project root (and .cursor/mcp.json for Cursor). Any agent that opens the folder discovers it and starts the Helix MCP server automatically, with no manual configuration.

The first time you run claude in the project, it asks you to trust the folder, then asks whether to use the Helix MCP server. You can allow the server once or allow it always. Allow it either way: everything below assumes it’s running.

The .mcp.json file is committed to the repo:

{
  "mcpServers": {
    "helix": {
      "command": "npx",
      "args": ["helix", "mcp"],
      "cwd": "."
    }
  }
}

The MCP server is always available: it doesn’t need the dev server running, and it can start, stop, and monitor the dev server itself. Claude starts it from the project’s MCP configuration, so you rarely run helix mcp yourself. It speaks the stdio transport. See the CLI overview.

What the agent does through it

The MCP server is the agent’s connection to Helix. Through it, Claude can:

• Read the project structure and configuration, so it knows what already exists before it writes anything.
• Scaffold and edit function code.
• Wire up authentications by alias.
• Start, stop, and watch the local dev server.
• Deploy the project.

A typical session: the agent opens the folder, reads the project layout, writes a function, starts the dev server, calls the route, reads the logs, then deploys.

Prompting patterns

Describe outcomes and let the agent pick the tools. Patterns that work well:

• Ask Claude to build and verify in one go. “Add GET /api/v1/contacts that returns the saved contacts, then run it and show me the response.” The agent writes the function, starts the dev server, calls the route, and reads the logs.
• Ask Claude to wire a service by alias. “Pull my open deals from Salesforce onto the dashboard.” The agent looks up the project’s auth aliases and writes ctx.http.authed() calls; it never needs the credentials.
• Ask Claude to run the app. “Start the dev server and check every route responds.” The agent starts the server and exercises the routes in sequence.
• Ask Claude to deploy. “Deploy this project.” The agent runs the deploy and reports the project ID and the live URL.

When to run the CLI yourself

A few things stay in your hands:

• Logging in. Run helix login in a plain terminal, outside the Claude session. The command opens your browser to sign in, then saves your session to ~/.tray.config. That file is a secret: never ask an agent to read it or print it.
• Choosing a workspace. Run helix workspace select yourself, or helix workspace set <id> if you know the ID. You have to be a member of the workspace you deploy into.
• Checking a deployment. helix deployment get <deploymentId> prints the status, warnings, and build errors for one deploy.
• Managing credentials. Authentications are created in Tray iPaaS today, not in Helix. helix auth list shows which ones the project can use.