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). 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.
If you're new to MCP, start with the MCP protocol overview — it explains why MagOneAI uses MCP and how first-party integrations work.
When to use external MCP
Third-party MCP server
A vendor or open-source project already provides an MCP server for the service you want to integrate. Connect by URL.
Your own hosted MCP server
You've built a custom MCP server internally and deployed it. Point MagOneAI at the URL and your agents can use it.
Prototyping and evaluation
Trying out a new MCP-compatible tool before committing to a deeper integration.
Org-specific integrations
You need a tool for one organization but not platform-wide. External MCP keeps it scoped to that org.
For tools you need to customize deeply or ship alongside the platform, consider building a custom MCP server instead.
What this looks like in practice
MCP servers are published by vendors, by open-source projects, and by teams for their own use. Typical things organizations connect this way:
- A SaaS vendor's own MCP server for their product, so agents can read and write records in your CRM, ticketing system, or analytics tool
- An internal service you wrapped in MCP, exposing your own API to agents without waiting for a platform release
- A community MCP server for a developer tool you already use
There is no approved list. If it speaks MCP over HTTPS and you have a URL, it connects. The catalog it advertises is what your agents get.
An external server is code you do not control, running somewhere you do not control, that your agents can call. Connect servers you trust, from sources you would take a dependency on, and read what tools a server exposes after discovery. The tool descriptions it returns are shown to your agents as instructions.
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.
Open Tools → Add external MCP
From the organization's tool settings, choose to add an external server.
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).
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.
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.
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.
Security considerations
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 deployed alongside MagOneAI.
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.
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.
External MCP servers are scoped to the organization that added them. Other organizations on the same MagOneAI deployment can't see or use them.
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.
The same URL can only be connected once per organization. A second attempt is rejected rather than creating a duplicate, so if you are trying to change a server's credentials, disconnect it first. Two different organizations connecting the same URL is fine, and each gets its own registration.
Set a credential expiry date
When you connect a server whose credential is a bearer token, API key or service-account secret, you can record the date it expires. MagOneAI then reminds you 7 days before, 1 day before, and once the date passes.
Only you know that date, so MagOneAI cannot discover it. Without one, the connection simply starts failing on the day it lapses.
An expiry date never takes a working connection offline. It informs. See Tool credential health.
Test Connection
Test Connection refreshes the stored OAuth token first, then calls the server. Two consequences:
- A pass means the connection works now, not that it worked before the token was about to expire.
- A pass clears a stale reconnect prompt.
Auth configuration locking
Once a server has active connections, its authentication configuration can be locked. Re-registering it with a changed configuration is then refused.
The lock exists so a configuration change cannot break every existing connection at once. An administrator unlocks it when a change is genuinely needed, for example to turn on PKCE for a provider that now requires it.
Why a connected server can look offline
MagOneAI checks server health every minute, and an unhealthy server's tools are dropped from runs. A vendor-hosted server never sends a heartbeat, so MagOneAI probes it instead, and reads anything below a 500 as alive, including a 401.
The probe asks whether the server is there, not whether your credentials are good. Those are different problems with different fixes. See Tool credential health.
DocuSign is blocked across MCP tools. It is refused at discovery, on the consent screen, and at execution. A connection to it cannot be created or used.
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
MCP protocol
Understand how MCP works and why MagOneAI uses it for tool integration
Custom tools
Build your own MCP server when external connection isn't enough
Tools overview
See the full catalog of built-in integrations
Tool credential health
Expiry reminders, token refresh, and reconnect prompts
Platform access for tool servers
What a connected server can read and write
Secrets management
How MagOneAI stores and injects credentials securely