MCP Servers

The MCP Server tool node connects an Agent node to any Model Context Protocol server. At run time the node asks the server which tools it offers, turns each one into a regular agent tool with a typed input schema, and routes the agent's calls back to the server. One node can expose a whole toolbox — and you control exactly which tools the agent sees.

Connection types

The platform supports the two remote MCP transports as Connection types:

Pick the one your server documents. Modern servers usually serve Streamable HTTP on /mcp; older servers serve SSE on /sse. Connecting with the wrong transport (or the wrong path) is the most common setup failure — see troubleshooting below.

Create an MCP Connection

Add a new Connection

In your project, go to Connections and click Add new connection. In the Type dropdown pick MCP Streamable HTTP (or MCP SSE), and give the Connection a Name.

Fill in the server details

URLstringrequired

The server's MCP endpoint, including the path — e.g. https://remote.mcpservers.org/fetch/mcp.

Headerskey-value pairs

HTTP headers sent with every request to the server — use this for auth (see below). Click Add header for each pair.

Timeoutnumber (seconds)

Timeout for establishing the initial connection. Defaults to 30.

SSE Read Timeoutnumber (seconds)

How long to wait for messages on the open stream. Defaults to 300.

Create

Click Create. The Connection is active immediately and can be selected on any MCP Server node in the project.

Auth headers

MCP Connections authenticate with HTTP headers. Add whatever scheme your server expects under Headers — most commonly a bearer token:

Some servers use a custom header instead (for example an X-API-Key). The headers are stored on the Connection and sent with every request the node makes — both the initial tool discovery and each tool call.

Add the MCP Server tool to an agent

Attach the tool

Select your Agent node, open Tools, click Add tool, and pick MCP Server. The tool appears as a child node of the agent on the canvas.

Pick the Connection

Click the gear icon to open the MCP Server configuration and select the MCP Connection you created. You can also rename the node — the name shows up in traces as the server the tools came from.

Optionally filter tools

Use Include tools and Exclude tools to control which of the server's tools the agent sees (details below). Type a tool name and press Enter to add it to either list. Leave both empty to expose everything.

How tool discovery works

You never define schemas for MCP tools — they are discovered dynamically:

1. When the agent initializes, the MCP Server node opens a session against the Connection and calls the server's list_tools endpoint.
2. Every tool the server advertises becomes an individual agent tool, carrying the server-provided name and description — that text is what the agent's LLM reads when deciding which tool to call, so the server's own docs drive tool selection.
3. Each tool's JSON Schema is converted into a typed input schema. Nested objects, arrays, unions (anyOf/oneOf), allOf composition, recursive $refs, and enums are all supported; enum values are appended to the field description as "Allowed values: …" so the model picks valid ones.
4. When the agent calls a tool, the node opens a session, invokes the tool on the server with the validated arguments, and returns the result text (or the server's structured content, when provided) as the tool observation.

Because discovery happens at initialization, tools added to the server later are picked up on the next run — no workflow changes needed. If the server changes a tool's input schema, the node picks that up the same way.

Filter the exposed tools

Big MCP servers can advertise dozens of tools, and every one of them adds a line to the agent's system prompt. Filtering keeps the prompt small and removes tools you don't want the agent to ever call:

• Include tools — if non-empty, only the listed tool names are exposed.
• Exclude tools — the listed tool names are removed from whatever is exposed.
• Both empty — all of the server's tools are exposed.

Names must match the server's tool names exactly (as returned by discovery); a misspelled entry in Include tools silently exposes nothing for that name. In the SDK the same fields are include_tools and exclude_tools on MCPServer.

Runnable example: a public MCP server

The community fetch server at https://remote.mcpservers.org/fetch/mcp is public (no auth) and speaks Streamable HTTP — it exposes a tool that fetches a web page and returns its content.

In the UI:

1. Create a Connection of type MCP Streamable HTTP with URL https://remote.mcpservers.org/fetch/mcp and no headers.
2. Attach an MCP Server tool to your Agent node and select that Connection.
3. Open the Test tab and ask: "Retrieve the information displayed on https://www.apple.com/ and summarize it." The trace shows the agent discovering the server's tools and calling the fetch tool.

The same setup with the Python SDK:

import os

from dynamiq import Workflow
from dynamiq.connections import MCPStreamableHTTP
from dynamiq.connections import OpenAI as OpenAIConnection
from dynamiq.nodes.agents import Agent
from dynamiq.nodes.llms import OpenAI
from dynamiq.nodes.tools import MCPServer

# Public, no-auth MCP server speaking Streamable HTTP
connection = MCPStreamableHTTP(url="https://remote.mcpservers.org/fetch/mcp")

mcp_server = MCPServer(
    name="fetch-mcp",
    connection=connection,
    # include_tools=["fetch"],   # optional: expose only specific tools
    # exclude_tools=[...],       # optional: hide specific tools
)

agent = Agent(
    name="react-agent",
    id="react-agent",
    llm=OpenAI(
        connection=OpenAIConnection(api_key=os.getenv("OPENAI_API_KEY")),
        model="gpt-4o",
    ),
    tools=[mcp_server],
    max_loops=10,
)

wf = Workflow()
wf.flow.add_nodes(agent)

result = wf.run(
    input_data={"input": "Retrieve the information displayed on https://www.apple.com/ and summarize it."}
)
print(result.output.get("react-agent", {}).get("output", {}).get("content"))

For a server that needs auth, add headers to the connection:

connection = MCPStreamableHTTP(
    url="https://your-mcp-server.example.com/mcp",
    headers={"Authorization": f"Bearer {os.getenv('MCP_SERVER_TOKEN')}"},
)

Troubleshooting

Next steps