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

# External MCP servers

> Plug any third-party MCP server into MagOneAI by URL — no code, no packaging, no custom build

## Bring the MCP ecosystem into MagOneAI

MagOneAI ships with first-party integrations (Google, Microsoft, databases, web search, and more — see the [tools overview](/tools/overview)). But MCP is an open protocol, and a growing ecosystem of third-party MCP servers already exposes tools for CRMs, ticketing systems, analytics platforms, internal APIs, and more.

**External MCP servers** let you connect any of those to your organization by pasting a URL. The tools the server exposes become available to agents in your projects immediately — no image to build, no integration to write.

<Info>
  If you're new to MCP, start with the [MCP protocol overview](/tools/mcp-protocol) — it explains why MagOneAI uses MCP and how first-party integrations work.
</Info>

## When to use external MCP

<CardGroup cols={2}>
  <Card title="Third-party MCP server" icon="globe">
    A vendor or open-source project already provides an MCP server for the service you want to integrate. Connect by URL.
  </Card>

  <Card title="Your own hosted MCP server" icon="server">
    You've built a custom MCP server internally and deployed it. Point MagOneAI at the URL and your agents can use it.
  </Card>

  <Card title="Prototyping and evaluation" icon="flask">
    Trying out a new MCP-compatible tool before committing to a deeper integration.
  </Card>

  <Card title="Org-specific integrations" icon="building">
    You need a tool for one organization but not platform-wide. External MCP keeps it scoped to that org.
  </Card>
</CardGroup>

For tools you need to customize deeply or ship alongside the platform, consider building a [custom MCP server](/tools/custom-tools) instead.

## Connecting an external server

Only **organization owners** can add external MCP servers, because tools connected this way are shared across every project in the org.

<Steps>
  <Step title="Open Tools → Add external MCP">
    From the organization's tool settings, choose to add an external server.
  </Step>

  <Step title="Provide the server URL">
    Paste the HTTPS URL of the MCP server. The URL must be publicly reachable — private IPs and internal-only hostnames are rejected for security (see below).
  </Step>

  <Step title="Configure authentication headers">
    Most MCP servers require authentication. Add the headers the server expects — for example, an `Authorization` header with a bearer token, or a vendor-specific API key header. Credential values are stored securely and never appear in workflow logs.
  </Step>

  <Step title="Discovery">
    MagOneAI calls the server to fetch its tool catalog. Each tool's name, description, and parameter schema is imported automatically. If the server is unreachable or the credentials are wrong, you'll see a clear error at this step rather than silent failure later.
  </Step>

  <Step title="Use in workflows">
    Once discovery succeeds, the new tools show up in the tool picker on the canvas. Agents in any project in this organization can be given access to them.
  </Step>
</Steps>

## Security considerations

<AccordionGroup>
  <Accordion title="Only public HTTPS endpoints are allowed">
    External MCP URLs must use `https://` and must resolve to a public address. Private IPs, localhost, and internal-only hostnames are blocked to prevent the platform from being used to reach networks it shouldn't. If you need to connect an internal-only server, host it behind a public HTTPS endpoint (with its own auth) or package it as a [custom MCP server](/tools/custom-tools) deployed alongside MagOneAI.
  </Accordion>

  <Accordion title="Credentials are stored in the vault, not in workflows">
    The credential values you enter are sent directly to the platform's secure vault. Workflows reference them indirectly, and they're only injected into outbound requests to the MCP server at runtime — never logged, never exposed in exports.
  </Accordion>

  <Accordion title="Forbidden header names">
    Some headers are reserved by the transport (`Host`, `Content-Type`, `Content-Length`, and similar) and cannot be used for authentication. MagOneAI rejects these at configuration time so you notice during setup, not during a live run.
  </Accordion>

  <Accordion title="Per-organization isolation">
    External MCP servers are scoped to the organization that added them. Other organizations on the same MagOneAI deployment can't see or use them.
  </Accordion>
</AccordionGroup>

## Ongoing management

Once a server is connected, you can manage it from the same tool settings page:

* **Re-discover tools** — if the upstream server adds or removes tools, trigger a refresh to pull the latest catalog.
* **Update credentials** — to change the stored credential values, disconnect the server and reconnect it with the new values.
* **Rotate the organization's service token** — MagOneAI authenticates *to* the upstream connector on your behalf using a per-org service token; rotate it if you suspect it's been compromised.
* **Disconnect** — remove the server when it's no longer needed. Workflows that reference its tools will show a clear "tool unavailable" error rather than silently skipping.

## What external MCP doesn't do

* **It doesn't host the server for you.** The MCP server itself runs somewhere else — wherever the vendor or your own infrastructure hosts it. MagOneAI is the client.
* **It doesn't modify the tool contract.** The tools' names, descriptions, and parameter schemas come from the upstream server. If you need to rename or reshape a tool, you'd do that on the server side.
* **It doesn't replace first-party integrations.** For heavily used services (Google, Microsoft, databases), the built-in integrations offer deeper platform features — OAuth flows, per-user scoping, richer credential management. Use external MCP when those integrations don't already cover what you need.

## Next steps

<CardGroup cols={2}>
  <Card title="MCP protocol" icon="link" href="/tools/mcp-protocol">
    Understand how MCP works and why MagOneAI uses it for tool integration
  </Card>

  <Card title="Custom tools" icon="puzzle-piece" href="/tools/custom-tools">
    Build your own MCP server when external connection isn't enough
  </Card>

  <Card title="Tools overview" icon="wrench" href="/tools/overview">
    See the full catalog of built-in integrations
  </Card>

  <Card title="Secrets management" icon="key" href="/security/secrets-management">
    How MagOneAI stores and injects credentials securely
  </Card>
</CardGroup>