> ## 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.

# External MCP Integrations

> Connect your project to a third-party MCP server so its tools become available to the Studio Copilot.

<Warning>
  As of the source handoff for this page (2026-07-14), External MCP was validated in **staging only**, behind the `FT_EXTERNAL_MCP` feature flag — the handoff doc explicitly says staging/beta tags should not be treated as a global-production release. Confirm with the Studio team whether this has since rolled out to your project before relying on it as generally available.
</Warning>

External MCP is the **inbound** counterpart to [MCP Builder](/mcp/mcp-builder): instead of your project exposing tools, it **consumes** tools from a third-party MCP server, so the Studio Copilot (and the in-Studio Playground) can call them.

## What it does not do

This integration **does not install or execute arbitrary code inside your pod**. There's no support for `npx`, `pip`, shell commands, or customer-supplied container images. "Install MCP" in the UI means registering a secure remote connection — nothing runs locally.

## Supported transport and auth

* **Streamable HTTP** — recommended.
* **SSE** — kept for legacy compatibility.
* Authentication: no credential, Bearer token, or a custom header — the credential itself is a reference into your project's **Vault**, never pasted directly or serialized back in API responses.

## Where it lives

Studio → **Integrations → MCP servers**. The flow: an install wizard with a mandatory connection test, transport/auth selection, a credential picker from the Vault, tool discovery with an initial allowlist, then ongoing controls (enable/disable, refresh the catalog, edit the allowlist, remove). Installed tools get a Playground built from the tool's own JSON Schema, and become available to the Studio Copilot.

Backend endpoints (Client API, per-project):

| Method   | Endpoint                                     | Purpose                                  |
| -------- | -------------------------------------------- | ---------------------------------------- |
| `GET`    | `/integrations/mcp`                          | List installations                       |
| `POST`   | `/integrations/mcp/test`                     | Test a connection and discover tools     |
| `POST`   | `/integrations/mcp`                          | Install a server                         |
| `GET`    | `/integrations/mcp/<id>`                     | Get an installation                      |
| `PATCH`  | `/integrations/mcp/<id>`                     | Enable, disable, or change the allowlist |
| `POST`   | `/integrations/mcp/<id>/refresh`             | Refresh the tool catalog                 |
| `DELETE` | `/integrations/mcp/<id>`                     | Remove an installation                   |
| `POST`   | `/integrations/mcp/<id>/tools/<tool>/invoke` | Invoke a tool                            |

An installation's state is one of `connected`, `unreachable`, `disabled`, or `validating`.

## Security guardrails

* HTTPS is required by default; insecure HTTP and private networks are disabled behind a flag.
* `localhost`, loopback, link-local, cloud metadata endpoints, and private/reserved IPs are blocked.
* Credentials embedded directly in a URL are rejected.
* Automatic HTTP redirects are disabled; the HTTP client doesn't inherit process proxies.
* Custom headers are validated against header injection.
* Schemas, names, descriptions, arguments, and results all have size limits (staging values: `MCP_EXTERNAL_MAX_TOOLS=100`, `MCP_EXTERNAL_MAX_SCHEMA_BYTES=32768`, `MCP_EXTERNAL_MAX_ARGUMENT_BYTES=131072`, `MCP_EXTERNAL_MAX_RESULT_BYTES=262144`).
* Credentials are never serialized back in API responses.
* **Every external MCP tool requires explicit approval before the Copilot can call it — even if the server advertises `readOnlyHint`.**

A known residual risk noted in the source handoff: DNS validation happens before the connection is made; for a multi-tenant production hardening pass, an egress/NetworkPolicy control is recommended as a second barrier against DNS rebinding.

## Related

* [MCP Builder](/mcp/mcp-builder) — the outbound counterpart.
* [MCP Overview](/mcp/overview) — how the two fit together.