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

# Deploy an MCP server

> Stand up one Engine-hosted MCP server that reaches every service an agent is allowed to use.

An MCP server is an Engine-hosted runtime with its own stable URL. It never builds or downloads a package — apply stands it up, and it stays live until you deactivate it.

One server can span several internal and external services, so an agent needs one connection rather than one per provider.

<Card title="Describe the capabilities you need" icon="wand-magic-sparkles" href="/docs/app/from-a-prompt">
  Use prompt to create an MCP app, update an existing local config, or draft a sequential Unified Operation for review.
</Card>

For supported OAuth integrations, [use a Managed service](/docs/workspace/use-managed-service) or [configure your own provider app](/docs/bucket/connect-user-accounts). Managed auth uses the same MCP connection flow, while Fused keeps the provider client secret on its broker.

## Author and deploy

```bash theme={null}
fused-cli init support-agent --mcp \
  --description 'Update support issues and notify the owning team in Slack.' \
  --service linear \
  --service slack
```

`--service` accepts comma-separated selectors or repeated flags. Use the canonical `<service>@<version>` form when the server must select one exact immutable service version.

For each service, **All operations** is highlighted by default. Press Enter to expose the complete service, or open **Choose operations…** to search by operation ID, method, path, summary, or tag. The example below assumes you accepted all operations for both services.

Init enables any missing service after one combined confirmation under a separate workspace receipt. It builds and validates the MCP candidate in memory, then plans it before creating `.fused/mcps/support-agent.yaml`. A successful plan creates the file atomically; init then applies the MCP server and prints its connection details. If the MCP plan fails, no app config or app receipt is created, though a completed workspace activation remains applied. MCP planning never changes credentials, and missing values do not block publication. The first affected tool call stops before contacting the provider and returns the exact safe `secret set` command.

The resulting config is durable desired state:

```yaml theme={null}
apiVersion: fused/v1
kind: mcp
name: support-agent
version: "1.0.0"
description: Update support issues and notify the owning team in Slack.
bucket: default
services:
  linear:
    version: "v1"
    select_all: true
    auth: { type: "oauth" }
    connect: { scopes: ["read:issues"] }
  slack:
    version: "v1"
    select_all: true
```

`description` summarizes what the server helps an agent accomplish in one to three concise sentences. Keep operation IDs out of this overview; the agent discovers exact calls later through `search_docs`. In a terminal, init prompts when you omit it. With `--no-input`, pass it explicitly.

Each service resolves credentials through its own `bucket:` override when set, otherwise the top-level `bucket:`. A local `${bucket.auth...}` reference joins services in the same bucket. A managed `${fused.bucket.auth...}` reference selects a Fused Managed App while keeping user connections in the selected bucket.

Use `fused-cli mcp list` whenever you need to recover the stable and pinned endpoints after initialization.

<Warning>
  The first successful apply may return an execution token once. An idempotent apply will not reveal it again. Store it immediately.
</Warning>

## Flags

### `fused-cli init --mcp`

| Flag                   | What it does                                                                                                                                       | Example                                                                          |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `--description`        | Describes the server's business capability; required with `--no-input`                                                                             | `fused-cli init support --mcp --description 'Read and update support issues.'`   |
| `--service`            | Adds services as `<service>[@<version>]`; comma-separated or repeatable, with an omitted version defaulting to an enabled or latest public version | `fused-cli init support --mcp --service linear@v1,slack`                         |
| `--operation`          | Skips the selector for one exact operation; repeatable                                                                                             | `fused-cli init support --mcp --service linear --operation 'linear=issueUpdate'` |
| `--select-all`         | Skips the selector and takes every operation of a service                                                                                          | `fused-cli init support --mcp --service slack --select-all slack`                |
| `--bucket`             | References an existing bucket; never creates one                                                                                                   | `fused-cli init support --mcp --bucket agent-credentials`                        |
| `--webhook-attachment` | Attaches an already applied webhook config                                                                                                         | `--webhook-attachment managed-slack-events`                                      |
| `--events`             | Selects explicit provider events; repeatable                                                                                                       | `--events 'slack=app_mention'`                                                   |
| `--version`            | Sets the initial server version                                                                                                                    | `fused-cli init support --mcp --version 2.0.0 --service linear`                  |
| `--no-apply`           | Writes validated desired state, saves available plan receipts, and prints the commands to apply later                                              | `fused-cli init support --mcp --service linear --no-apply`                       |

`--language` is SDK-only. An MCP server is a runtime, not a generated package.

Init also resolves server-template variables for the operations you selected and writes the matching `server_variable` injections, reporting a count of what it generated. The behaviour is identical to the SDK side — [how init fills in routing](/docs/app/build-an-sdk#init-fills-in-the-routing-for-you).

Omit the mode flags in a terminal to choose between SDK, API, and MCP interactively. With `--no-input`, pass `--mcp`, `--description`, and an explicit `--operation` or `--select-all` for every service.

### `fused-cli extend`

Add another service or operation without repeating `--mcp`:

```bash theme={null}
fused-cli extend support-agent --service slack
```

`extend` reads `.fused/mcps/support-agent.yaml`, infers MCP mode, and updates that same file. An idempotent repeat keeps its version. A real change to a stable SemVer version advances to the next minor version and is shown in terminal confirmation; the same inference works with `--no-input`. Use `--version` to override the inferred successor. Prerelease and non-SemVer versions require an explicit successor.

### `mcp plan`

| Flag            | What it does                                    | Example                                               |
| --------------- | ----------------------------------------------- | ----------------------------------------------------- |
| `--json`        | Prints the plan result and required permissions | `fused-cli mcp plan --no-input --json`                |
| `--owner-team`  | Sets the owning team; defaults to you           | `fused-cli mcp plan --owner-team support`             |
| `--receipt-out` | Writes the receipt to a chosen path             | `fused-cli mcp plan --receipt-out ./ci/mcp.plan.json` |

MCP planning never mutates credentials. It reports missing entries as readiness metadata and still creates a valid plan. By contrast, an SDK plan in a terminal can offer to store missing credentials securely and retry once; declining also keeps the valid plan. Use `mcp validate` only when you need an offline-only check.

### `mcp apply`

| Flag        | What it does                    | Example                                            |
| ----------- | ------------------------------- | -------------------------------------------------- |
| `--plan-id` | Applies one exact remote plan   | `fused-cli mcp apply --plan-id pln_6b2…`           |
| `--receipt` | Applies from a specific receipt | `fused-cli mcp apply --receipt ./ci/mcp.plan.json` |

`--download` and `--json` are SDK-only. An MCP server has no package to download.

## MCP-specific constraints

* **Explicit webhook selection.** Set `webhook_attachment` and a per-service `webhooks` list to expose provider events as MCP resources. Event-only services are supported. `webhooks_select_all: true` is rejected. See [receive MCP events](/docs/mcp/receive-events) for client requirements, live notifications, and retained payload reads.
* **Unified operations require explicit targets.** A top-level `unified_operations` map uses the same bindings, dependencies, rollback, mapping, and output contract as an SDK. Each operation authorized by the execution token appears in `search_docs` and runs through the existing `execute` tool with `await call(operationId, {input, targets, selectors?, pagination?, idempotencyKey?})`. `targets` is always required, must be dependency-closed, and never defaults to every declared binding. See [declare a unified operation](/docs/app/unified/declare) and [call a unified operation](/docs/app/unified/call).
* **No implicit latest app.** Init may default a provider version while writing the config, but MCP app references and runtime promotions always resolve one exact immutable app version.

## Versions

One MCP name has one stable MCP ID shared by every version, and each explicit version has its own immutable Version ID. Multiple versions can run at once.

Applying a version explicitly promotes it for new sessions on the stable MCP URL. Applying an older version again explicitly rolls the stable target back. Existing sessions continue on the immutable version they resolved during initialization.

The CLI displays both endpoints after apply and in `mcp list`:

| Endpoint                   | Use it for                                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| Stable `/mcp/<mcp-id>`     | Recommended for agents that should receive explicit version promotions without changing configuration |
| Pinned `/mcp/<version-id>` | Clients that must remain on one exact immutable version                                               |

Applying identical content to the same version is a no-op. Changing its description, operation, auth, or injection scope returns `app_version_immutable` — publish a new version instead.

<Note>
  Deactivating the promoted version makes the stable URL unavailable. The Engine does not guess another sibling version; explicitly apply the version you want to promote next.
</Note>

## Deactivating

```bash theme={null}
fused-cli mcp deactivate support-agent@1.0.0
```

<Warning>
  This is irreversible. The Engine writes a tombstone, stops that runtime, and will not allow that MCP name and version to be recreated. Sibling versions and shared tokens survive.
</Warning>

Unlike removing a workspace service, deactivation is immediate and is not gated behind a blocker for configs that still reference it. There is no MCP deprecate or undeprecate command — do not invent one.

<Card title="Connect an agent with a scoped token" icon="shield-halved" href="/docs/mcp/use-the-server">
  Bind a token to the right connected user and place it in the MCP client.
</Card>