MCP Servers - Idun Engine

Idun Engine uses the Model Context Protocol (MCP) to extend agent capabilities with external tools. You declare MCP servers in your config.yaml (or through the admin panel at /admin/mcp/), and the engine discovers every advertised tool at boot.

The langgraph-tool-local template shows how to mix local tools with MCP tools in a single agent.

How it works

Register MCP servers in the admin panel or YAML config with transport settings and connection details
The engine discovers tools from each configured MCP server at startup
Agents invoke tools during conversations as needed, with results passed back for response generation

The standalone runs a single agent per process, so every MCP server registered in the config (or admin panel) is available to that agent.

Transport types

MCP servers connect to the engine through one of four transport protocols:

Transport	Use case	Required fields
`stdio`	Local processes, Docker containers	`command`, `args`
`sse`	Remote servers with Server-Sent Events	`url`
`streamable_http`	Remote servers with HTTP streaming (default)	`url`
`websocket`	Persistent bidirectional connections	`url`

The transport is decided by the MCP server, not the client. Most hosted servers expose exactly one. For example, https://mcp.data.gouv.fr/mcp is streamable_http only, with no sse or stdio fallback. Check the server’s documentation before picking a transport; mismatched values fail at the handshake, not the YAML schema.

Configuration example

Define MCP servers in your config.yaml or through the admin panel:

Config file
Admin UI

config.yaml

mcp_servers:
  - name: fetch
    transport: stdio
    command: docker
    args: ["run", "-i", "--rm", "mcp/fetch"]

  - name: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    env:
      ALLOWED_DIRECTORY: /data

  - name: custom-api
    transport: streamable_http
    url: https://mcp.example.com/api
    headers:
      Authorization: "Bearer ${MCP_API_TOKEN}"

Tools are discovered at engine boot and made available to your agent via get_langchain_tools() / get_adk_tools().

Open the MCP admin page

Navigate to /admin/mcp/ in the running standalone. The catalog at the top groups MCP servers by transport: Streamable HTTP, SSE, WebSocket, and stdio. Existing servers are listed below with their transport, endpoint, and status.

Add an MCP server

Click the transport card you want and fill in the form: a unique name, the URL (or command and args for stdio), optional headers. The Enabled toggle lets you keep a server configured but skipped at startup.

Save and verify

Save; the reload pipeline re-instantiates the engine with the new MCP registry. Click the wrench icon next to a server to probe it and list the tools it advertises. The probe doubles as a connection check.

Tools discovered for the atlassian MCP server

Integration approaches

Framework integration

The engine provides helper functions to load MCP tools into your agent code:

from idun_agent_engine.mcp import get_adk_tools

idun_tools = get_adk_tools()

These functions discover all MCP servers attached to your agent and make their tools available. You do not need to configure individual tools.

Probing a server programmatically

The wrench icon in the MCP admin page is backed by an admin REST endpoint, so the same probe runs from a script or a CI smoke check. POST /admin/api/v1/mcp-servers/{mcp_id}/tools connects to the registered server, lists every advertised tool, and returns a StandaloneConnectionCheck:

curl -sX POST "http://localhost:8000/admin/api/v1/mcp-servers/$MCP_ID/tools" \
  --cookie "$IDUN_SESSION_COOKIE"

{
  "ok": true,
  "details": {
    "name": "data_gouv",
    "transport": "streamable_http",
    "toolCount": 9,
    "tools": ["get_dataset_info", "search_datasets", "..."]
  },
  "error": null
}

On failure (unreachable URL, MCP handshake mismatch, malformed config, registry init error) the same shape returns with ok: false, the upstream message in error, and any partial detail still attached. The probe runs under a 5-second timeout (services/connection_checks.py) and converts every exception into the ok: false payload, so it is safe in a polling loop. The HTTP status stays 200 on every outcome except the auth check failing or the row id not existing. The route is admin-authenticated: under IDUN_ADMIN_AUTH_MODE=password you need the session cookie minted by POST /admin/api/v1/auth/login. Use this in CI to fail fast when a production MCP server has gone away, or in a release-time check before flipping traffic.

get_langchain_tools() is async, so it must be awaited inside an async function. If you need to bind tools at module load, run it with asyncio.run(...) as shown above. A synchronous helper (get_langchain_tools_sync) is also available; see the engine MCP reference for details.

Next steps

Docker MCP toolkit

Pre-built MCP servers packaged as Docker containers. Pull, configure, and use without writing server code.

Configuration reference

Full schema for config.yaml including the mcp_servers block.

Documentation Index

​How it works

​Transport types

​Configuration example

​Integration approaches

​Framework integration

​Probing a server programmatically

​Next steps

Docker MCP toolkit

Configuration reference

How it works

Transport types

Configuration example

Integration approaches

Framework integration

Probing a server programmatically

Next steps