MCP
Attach outbound MCP servers to an Action Agent, configure transport and authentication, select tools, refresh catalogs, and diagnose partial connection failures.
MCP
The MCP panel in Action Agent Studio attaches outbound Model Context Protocol servers. The Agent can call selected tools on those servers during a turn.
This is not the hosted ActionFlows MCP server, where an external MCP client such as Cursor or Claude calls ActionFlows tools.
Organization connections and custom servers
An Agent attaches an organization MCP connection. The connection can come from:
- an existing connection in the organization's MCP library; or
- a catalog server or custom URL created from Action Agent Studio.
The Agent attachment stores only the organization connection reference, transport, and its enabledToolNames. URL, encrypted headers, OAuth reference, status, and the last stable error code remain on the organization connection.
Transport
| Stored transport | Runtime transport | Current use |
|---|---|---|
streamableHttp | Streamable HTTP | Default for custom connections and catalog entries that do not select SSE |
sse | SSE | Selected by the catalog entry or explicit server configuration |
A connection is runtime-ready only when its URL starts with https://. The lower-level SSRF validator accepts HTTP as a URL scheme, but the current readiness check still requires HTTPS, so use HTTPS for every runnable MCP server.
Authentication
MCP connections support two server-side secret mechanisms:
- Encrypted headers: a JSON string map stored in
headersEncryptedand decrypted only for the probe or Agent transport request. - Organization OAuth: the connection references an
oauthConnectionId; ActionFlows loads its access token and sendsAuthorization: Bearer {token}.
When both exist, the OAuth Authorization header overrides an encrypted static Authorization value.
OAuth-mapped catalog servers
A catalog slug can map to an OAuth 2.0 organization integration, including direct or aliased mappings such as GitHub, Jira, Google products, and Microsoft/Teams. For a mapped server, readiness requires either a linked organization OAuth connection or encrypted headers. Action Agent Studio shows Authenticate when it can resolve the provider.
An unmapped catalog server or custom server can use no authentication, encrypted headers, or an explicitly selected organization OAuth connection.
Slack is deliberately excluded from the MCP OAuth map. Slack bot credentials used by Flow nodes and Agent triggers are not treated as credentials for a hosted Slack MCP server.
OAuth and headers authenticate the outbound MCP session; they do not authorize the Agent beyond the remote server's own policy. Give each connection only the remote scopes it needs.
Tool selection
Action Agent Studio probes a ready connection and lists its tools. Each Agent attachment has an explicit enabledToolNames array:
- only listed names are exposed to the model;
- an empty array means no tools, not all tools;
- a newly created ready catalog/custom connection initially selects all names returned by a successful probe; and
- a newly created connection whose probe fails or returns no tools starts with an empty selection until you probe and select names.
Use Probe to refresh the displayed tool catalog. Probing does not remove an existing non-empty selection. When the current selection is empty and a probe succeeds, the Action Agent Studio flow selects all returned names; otherwise, review the checkboxes and save each change.
Tool names are namespaced internally by the Agent connection attachment before entering the model tool set. Only one function-calling model sees the merged MCP, named HTTP, builtin, and Knowledge tools for that turn.
Runtime connection and failure policy
Organization MCP status is one of the exact values connected, disconnected, or error.
The Agent runtime connects each attached server independently. One server does not fail the whole turn:
- an incomplete server is skipped;
- an unsafe URL is skipped;
- an OAuth token failure skips that server;
- a connection or tool-listing failure skips that server; and
- all successfully connected servers and their enabled tools remain available.
The organization connection receives a stable lastError code:
| Code | Meaning |
|---|---|
INCOMPLETE_CONFIGURATION | URL, HTTPS readiness, or mapped authentication is incomplete |
OAUTH_TOKEN_UNAVAILABLE | The linked OAuth connection could not produce an access token |
UNSAFE_URL_BLOCKED | The URL failed the SSRF policy |
PROBE_FAILED | The save-time Action Agent Studio probe failed |
CONNECTION_FAILED | Agent runtime connection or tool listing failed |
A failed server is omitted from that turn rather than returned as a model-callable tool. The Agent can still answer using its other capabilities or explain that the remote capability was unavailable.
Refresh behavior
A successful probe updates the Action Agent Studio catalog display. It does not by itself replace the Agent runtime cache.
The runtime cache is keyed by the session scope and config.effectiveConfig.fingerprint. shouldRefreshAgentMcpRuntime reconnects when no runtime exists for the session or when the loaded effective fingerprint differs from the previous fingerprint. configVersion alone is not the cache key.
The effective fingerprint includes the target and preset configuration versions (targetConfigVersion and presetConfigVersion) together with resolved effective resources such as MCP connections, tools, Knowledge collections, and skills. Each skill contributes its selected release's identity — the release contentDigest and version — rather than only its ID, so publishing or revoking a skill release moves the fingerprint and causes a reconnect. The guardrail policy version is tracked separately by the Agent configuration cache and does not take part in MCP runtime refresh. Changes represented in the fingerprint cause a reconnect when the runtime is next resolved. External catalog or OAuth changes outside the fingerprint may leave an already-warm client connected until the runtime is recreated. Session suspension disposes cached MCP clients, and a later resume creates a new runtime.
SSRF boundary
MCP creation, update, Action Agent Studio probing, Agent connection, and every transport fetch use ActionFlows' safe remote-URL path:
- only HTTP(S) URLs are accepted;
- URLs with embedded credentials are rejected;
- DNS results in loopback, private, link-local, carrier-grade NAT, multicast, reserved, and other blocked ranges are rejected;
- hostname resolution is pinned for the request; and
- every redirect is revalidated, with at most five redirects.
Use a public HTTPS endpoint. Do not point an MCP connection at loopback, a private service, a cloud metadata address, or an internal DNS name that resolves into those ranges.
Tool-call visibility
MCP tool calls are internal Agent message parts. Action Agent Studio shows the tool state, input, output, and error when available. The public REST JSON response and public Action Agent SSE contract expose final assistant text, not raw MCP events. See Tools.
Related
Skills
Attach read-only platform and organization-owned prompt skills to an Action Agent and control their system-prompt injection order and refresh behavior.
Tools
Configure the Action Agent httpRequest builtin and named HTTP tools, including parameters, authentication, SSRF checks, and tool-call output.