> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machina.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Builder

> Compose an outbound MCP server from your project workflows, agents, prompts, and connector operations — driven by chat, not a form.

MCP Builder is the **outbound** side of MCP in Machina: it composes an MCP server that exposes a chosen set of your project's existing primitives — workflows, agents, prompts, connector operations, skills, and document search/get — as callable **tools** for an external agent.

<Info>
  Studio's own code comments describe MCP Builder as a "thin client": it renders profiles and relays intent to a composition layer in `machina-client-api` — it doesn't own the builder's state itself. This page documents what Studio shows and does; the underlying contract lives in `machina-client-api` (epic `86ajkh09z`) and wasn't read directly for this page — treat exact lifecycle/versioning semantics as needs-validation if you're building against the contract directly rather than through Studio.
</Info>

## It's chat-driven, not a form

There's no "new MCP server" wizard with fields to fill in. From the MCP Builder list page, **"New MCP" / "Describe your first MCP"** opens the Studio Copilot with this prompt already sent:

> "Help me build a new outbound MCP server. Ask me what tools it should expose, then use `create_mcp_server` to draft a profile composing existing workflows, agents, prompts and connector operations in this project."

Editing an existing one works the same way — **"Edit in chat"** sends:

> "Continue editing the MCP server "`<slug>`" in this project. Show its current tools and help me add, remove or adjust bindings with `update_mcp_server`, then validate and preview before publishing."

So the actual authoring loop is a conversation with Copilot, which calls `create_mcp_server` / `update_mcp_server` on your behalf.

## What a tool binding is made of

Each tool the profile exposes (`ToolBinding`) has:

| Field                 | Purpose                                                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`, `description` | What the external caller sees.                                                                                                                                            |
| `effect`              | `read_only` or `mutating`.                                                                                                                                                |
| `source`              | A reference to the underlying primitive — `kind` is one of `workflow`, `agent`, `prompt`, `connector_operation`, `skill`, `document_search`, `document_get`, `retrieval`. |
| `input_schema`        | The JSON Schema the caller must satisfy.                                                                                                                                  |
| `args`                | How inputs map to the source: `static` values, `passthrough` fields, or `rename`s.                                                                                        |
| `fixture`             | Optional sample args, used by `preview` for read-only tools.                                                                                                              |

## Lifecycle: draft → published → paused → archived

A profile version's `status` is one of `draft`, `published`, `paused`, or `archived`. The actions Studio exposes, each proxying a `machina-client-api` endpoint under `/mcp-profile/<slug>/*`:

| Action       | What it does                                                                                                                                                            |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Validate** | Runs structural checks, returns a `ValidationReport` with any errors.                                                                                                   |
| **Preview**  | Compares the live `tools/list` against the profile, and runs fixtures for `read_only` tools only — `mutating` tools are never executed in preview (`skipped_mutating`). |
| **Publish**  | Snapshots the draft as an immutable version and atomically flips the active version. Studio's own confirmation copy: "activation, not deployment."                      |
| **Rollback** | Reverts to a previously-published version.                                                                                                                              |
| **Pause**    | Removes the server from the runtime catalog without deleting it.                                                                                                        |
| **Delete**   | Removes a draft that was never published; archives a server with publish history instead of hard-deleting it.                                                           |

## Where it shows up for callers

Once published, the profile's tools become part of the same MCP endpoint every project already exposes — see [MCP Overview](/mcp/overview) for the URL/transport/auth, and [Connecting External Agents](/mcp/connecting-external-agents) for how an external client actually connects to it.

## Related

* [MCP Overview](/mcp/overview) — the shared connection endpoint.
* [External MCP Integrations](/mcp/external-mcp-integrations) — the inbound counterpart (consuming someone else's MCP server).