# MCP tools

**Use these tools through a [connected AI assistant](/mcp/).** Read tools inspect state. Write tools can start work or change resources, subject to your connection's grant and your role in the selected Workspace.

Your client discovers each tool's input schema from the server. For provider tools found through `hlix_tools_search`, use `hlix_tool_describe` to inspect the selected tool's current schema, availability and supported funding modes.

## Find projects and inspect work

| Tool | What it does | Access |
| --- | --- | --- |
| `hlix_whoami` | Identifies accessible Workspaces, the default selection, your role and whether the connection can write | Read |
| `hlix_projects` | Lists or finds projects by name or GitHub repository, across accessible Workspaces unless one is specified | Read |
| `hlix_status` | Reads a project's progress, questions, repositories, preview and delivery; accepts a message's `turn_id` to retrieve its reply | Read |
| `hlix_preview` | Gets the project's preview link | Read |
| `hlix_review` | Lists project tasks or reads one task's changed files, review verdict and comments | Read |

Start with `hlix_whoami`, find the intended project, then read its status. Most project tools accept a project name or ID and an optional Workspace. If the server returns several candidates, resolve the choice before continuing.

## Start, message and deliver

| Tool | What it does | Access |
| --- | --- | --- |
| `hlix_build` | Starts a project from an idea or repository, or adds requested work to an existing project | Write |
| `hlix_connect_repo` | Attaches a GitHub repository to a project without starting work | Write |
| `hlix_message` | Sends instructions or feedback to a project's team and returns a `turn_id` for the reply | Write |
| `hlix_answer` | Answers a pending question or approves or declines the team's request | Write |
| `hlix_set_coder` | Selects the coding agent for a project's new work | Write |
| `hlix_stop` | Stops current project work | Write |
| `hlix_resume` | Resumes a stopped project or starts one that has not started | Write |
| `hlix_deliver` | Prepares a pull request, then opens it after its confirmation step; never merges it | Write |

`hlix_build` starts billable work and returns before delivery finishes. Work follows the project's settings, including initial proposal approval when required. Check progress with `hlix_status` no more than once a minute.

Use `hlix_deliver` with `step: "prepare"`, show the returned delivery summary, then call `step: "confirm"` with its `confirm_token` after the user confirms. If the project changed, prepare again. The final merge remains separate.

If a project-start response is lost, inspect `hlix_projects` and `hlix_status` before repeating it.

## Work on the canvas

| Tool | What it does | Access |
| --- | --- | --- |
| `hlix_canvas_read` | Reads shared project context and Hlix's own canvas elements, with private work represented only as occupied areas | Read |
| `hlix_canvas_draw` | Applies one batch of canvas edits, attributed to Hlix acting on the user's request | Write |
| `hlix_canvas_undo` | Reverts Hlix's most recent canvas edit without undoing a person's edits | Write |

Read before drawing so the assistant can use free space. Only people mark project context. Edits to existing project context can appear as suggestions unless the project accepts Hlix's edits automatically.

## Discover and call provider tools

| Tool | What it does | Access |
| --- | --- | --- |
| `hlix_tools_search` | Finds native and connected provider tools, including their availability and funding options | Read |
| `hlix_tool_describe` | Reads a selected tool's input schema, accounting owner and supported funding modes | Read |
| `hlix_tool_call` | Invokes a described tool with an explicit funding mode and durable idempotency key | Write |
| `hlix_tool_status` | Reads a saved invocation's result and cost state without dispatching it again | Read |
| `hlix_tool_calls` | Lists saved invocations with cursor pagination, optionally scoped to a project | Read |

For example, discover tools exposed by customer MCP connections with these inputs to `hlix_tools_search`:

```json
{"query":"email","provider":"mcp","limit":10}
```

Pass a returned `toolId` to `hlix_tool_describe`. Use the returned input schema rather than guessing arguments from the tool's name.

## Durable tool calls

1. Discover and describe the tool. Its current availability and funding modes determine whether and how it can be called.
2. Call `hlix_tool_call` with `toolId`, the exact `input`, a unique `idempotencyKey` and supported `funding` choice. Include `projectId` when the call belongs to a project.
3. Keep the saved call ID. Read results with `hlix_tool_status`, or find recent calls with `hlix_tool_calls` and follow `nextCursor` for older records.
4. After a lost response, retain the same idempotency key and complete request body. Read the saved invocation before taking further action; a new key can create a second external action.

Results and final costs are recorded separately. A completed invocation can still have a pending cost. `maxCostMicros` is a reservation budget in USD micros, and the final charge can exceed it.

For routed provider tools, `hlix` funding uses Hlix's provider account and `organization` uses your connected account. Organization funding does not fall back to Hlix funding. Native AI and web tools retain their own service billing rules; use the described tool's supported choices.

Customer MCP calls use the provider account attached to that connection. Hlix adds no call charge; the external provider's cost remains unknown in Hlix. Use `auto` or `organization` funding and omit `maxCostMicros`. A completed external call does not need continued polling for a price. Replaying its saved request with the same key does not send the action again, even after the connection is removed. If the outcome is unknown, inspect the provider before creating another call.

## Managed domains and mailboxes

These tools require a Workspace owner or admin. Domain registration, recurring mailbox hosting and optional warmup are separate purchases or services.

| Tool | What it does | Access |
| --- | --- | --- |
| `hlix_managed_mailbox_orders` | Reads mailbox configuration and saved orders, including separate setup and billing states | Read |
| `hlix_quote_managed_mailboxes` | Checks domain availability and observes registration, hosting and warmup prices without ordering | Write |
| `hlix_order_managed_mailboxes` | Places a domain and Google mailbox order from a quote with a durable idempotency key | Write |
| `hlix_reconcile_managed_mailboxes` | Recovers a saved order using provider evidence instead of repeating an uncertain purchase | Write |
| `hlix_manage_mailbox_resource` | Resolves a setup error, cancels hosting or warmup, or requests domain removal | Write |

A quote shows observed prices; it does not lock them. After an order that stopped, retain the exact idempotency key and complete body, then read or reconcile the saved order. A missing mailbox account is not a completed setup.

Canceling hosting stops new cold sends locally and keeps conversations. Warmup cancellation is separate. Domain removal does not promise a refund or cancellation of renewal.

## Connect customer tools

Adding a customer MCP server lets Hlix agents and authorized Workspace users call that provider. This is the other direction from [connecting your assistant to Hlix](/mcp/).

Configure the connection under **Integrations → Agent tools & plugins**, authorize it and choose **Check connection** to save its catalog. Recheck after the provider changes its tools. Use `provider=mcp` to search all customer servers, or the returned provider ID to search one.

The [MCP servers guide](/configure/mcp-servers/) covers endpoints, headers, OAuth, project configuration and connection checks. The TypeScript SDK provides `client.mcpServers` for the registry and `client.tools` for discovery and saved runs; see the [Tools API](/api/reference/tools/).

## Next steps

[Set up your agent](/mcp/agent-setup/)
  [Connect your AI](/mcp/)
  [MCP servers](/configure/mcp-servers/)