Skip to main content

mcpServer

Connects an external MCP (Model Context Protocol) server to an agent, exposing the server's tools to the LLM at runtime. Like subagent, this node is not executed directly by the runner — DeepAgentCompiler reads its configuration from the graph, loads the remote server's tool list, and registers those tools on the agent it is attached to.

A mcpServer node attaches to a subagent via a tools → tool edge. The subagent in turn attaches to the main deepAgent via an agents → agent edge. The agent can then call any tool the MCP server advertises.

note

MCP servers attach under a subagent, not directly to a deepAgent. The canonical chain is deepAgent → subagent → mcpServer. Grouping external tools under a specialist subagent keeps the main agent's tool surface focused and lets it delegate tool use via its task() call.

Parameters​

ParamTypeRequiredDefaultDescription
server_urlstringYes—URL of the MCP server to connect to (e.g. https://mcp.alien.club/datacluster/mcp). Query parameters in the URL are forwarded to the server
transportstringNo"streamable_http"Transport protocol used to reach the server. One of streamable_http, sse, stdio (see below)
auth_tokenstring?NonullBearer token sent to authenticate with the server. Forwarded as Authorization: Bearer <token>. Omit (or set null) for public / unauthenticated servers
tool_filterstring[]?NonullAllow-list of tool names to expose. When null, every tool the server advertises is exposed. When set, only the named tools are registered on the agent

Transport modes​

ValueWhen to use
streamable_httpDefault. Remote HTTP MCP servers reachable over the network. Use this for the Alien-hosted connectors and for most third-party MCP servers
sseLegacy Server-Sent-Events HTTP transport. Use only for servers that have not migrated to streamable HTTP
stdioLocal process MCP servers spoken over standard input/output. Use only when the server runs in-process alongside the runner

Handles​

This node has a single output handle, tool. It is the target of a tools → tool edge from a subagent:

subagent (tools) ──▶ (tool) mcpServer

The edge carries no data and does not affect execution order — it tells DeepAgentCompiler which agent should be given the server's tools. A single subagent can fan out to several mcpServer nodes (each its own tools → tool edge), giving that specialist access to multiple tool sources.

Output​

This node produces no direct output. Its effect is to register the remote server's tools on the subagent it is wired to; the tools' results are returned to the agent when it calls them.

Example​

{
  "id": "datasourceMcp",
  "type": "mcp_server",
  "data": {
    "label": "MCP Server",
    "isExecuted": false,
    "handles": ["tool"],
    "schema": {},
    "params": {
      "server_url": { "value": "https://mcp.alien.club/datacluster/mcp", "isExpression": false, "isAttachedToInputNode": false },
      "transport": { "value": "streamable_http", "isExpression": false, "isAttachedToInputNode": false },
      "auth_token": { "value": null, "isExpression": false, "isAttachedToInputNode": false },
      "tool_filter": { "value": null, "isExpression": false, "isAttachedToInputNode": false }
    },
    "inputs": [], "outputs": [], "errors": []
  },
  "position": { "x": 600, "y": 400 },
  "isSelected": false,
  "isDragging": false
}

Connect this node to a subagent with a tools → tool edge.

Example: giving an agent RAG over a corpus​

The Alien platform hosts a datacluster MCP server that exposes search tools over your data clusters. Wiring it to an agent gives that agent retrieval-augmented generation (RAG) over an uploaded document corpus.

The pattern is a three-node chain:

  1. A subagent whose system prompt instructs it to answer questions by searching the corpus.
  2. A mcpServer node pointing at https://mcp.alien.club/datacluster/mcp, attached to that subagent via a tools → tool edge.
  3. The subagent attached to the main deepAgent via an agents → agent edge.

The datacluster search tool takes a datasetIds argument that selects which datasets to search. Tell the subagent which dataset IDs to pass in its system prompt:

You are a knowledge-base specialist. To answer a question, use the
datacluster search tool with datasetIds=[42] and ground your answer in
the passages it returns. Cite the source documents.

The agent passes datasetIds=[42] when it calls the tool, scoping the search to dataset 42.

deepAgent ──(agents → agent)──▶ subagent ──(tools → tool)──▶ mcpServer
                                                               (datacluster)

Datacluster MCP tools​

The Alien-hosted datacluster MCP server exposes the search/retrieval tools below over your data clusters. Each search tool accepts a datasetIds array argument that scopes the call to specific datasets.

ToolWhat it does
keyword_searchLexical (keyword) search over the corpus. Takes datasetIds
vector_search_chunksSemantic (embedding-similarity) search returning matching chunks. Takes datasetIds
get_entry_contentReturns the full text content of a single entry (document)
get_entry_documentsLists the entries/documents available within a dataset
Tool-name prefix — datacluster_ vs bare

The names above are the bare tool names as the server advertises them and as the corpus subagent's system prompt references them inside a workflow (keyword_search, vector_search_chunks, …). When the same server is reached through the Alien MCP connector from an external client (Claude, ChatGPT, Le Chat — see the connect guides), each tool is namespaced with a datacluster_ prefix, so the same calls appear as datacluster_keyword_search, datacluster_vector_search_chunks, datacluster_get_entry_content, and datacluster_get_entry_documents. Both refer to the same underlying tools; only the prefix differs by access path. The connector also surfaces a few additional tools (e.g. datacluster_list_datasets, datacluster_get_entry_file) — see the MCP FAQ and Connector Examples.

For a public corpus the datacluster MCP needs no auth_token; for a private one, supply a Bearer token scoped to read the cluster. To discover a dataset's ID, see Create a Dataset and Upload Documents.