Skip to main content
Aion supports LangGraph MCP access through aion-authoring-langgraph. The package builds on aion-mcp and returns standard LangChain MCP adapter configuration or LangChain-compatible tools. Use MCP in LangGraph when your agent needs tools exposed by the Aion control plane or by a runtime capability, such as the MCP server attached to the distribution that delivered the request.

​
MCP surfaces

SurfaceHow to reference itWhen to use it
Global control planeCapabilityReference.global_mcp()Stable Aion tools such as tool search and execute.
Fixed capabilityCapabilityReference.mcp(...)Subject and key are known at setup time.
Runtime capabilityRuntimeCapabilityReference.primary_mcp(...)Subject is known after a request arrives.
The global control-plane MCP server is now just an explicit capability reference in the list. There is no separate include_control_plane flag.

​
Load tools inside a graph node

Use this pattern when tool availability depends on the incoming request. 
from langgraph.runtime import Runtime
from langgraph.graph import MessagesState

from aion.api import (
    CapabilityReference,
    CapabilitySubjectSource,
    RuntimeCapabilityReference,
)
from aion.core.runtime import AionRuntimeContext
from aion.langgraph.authoring.mcp import AionLangGraphMcpResolver


resolver = AionLangGraphMcpResolver(
    capability_references=[
        CapabilityReference.global_mcp(),
    ],
    runtime_capability_references=[
        RuntimeCapabilityReference.primary_mcp(
            CapabilitySubjectSource.INCOMING_DISTRIBUTION
        ),
    ],
)


async def call_tools(state: MessagesState, runtime: Runtime[AionRuntimeContext]):
    tools = await resolver.load_tools(runtime.context)
    # Bind these tools to your model or pass them into a ToolNode.
    return {}
CapabilitySubjectSource.INCOMING_DISTRIBUTION means the incoming request distribution from the Aion Distribution extension payload. It is resolved from the current request’s AionRuntimeContext, not from global process state.

​
Build a MultiServerMCPClient config

LangChain’s MCP adapter accepts a mapping of server names to transport config. Aion can generate that mapping with authenticated headers. 
from langchain_mcp_adapters.client import MultiServerMCPClient

config = await resolver.server_config(runtime.context)
client = MultiServerMCPClient(config)
tools = await client.get_tools()
The generated server entries use: 
{
    "transport": "http",
    "url": "https://api.aion.to/...",
    "headers": {
        "Authorization": "Bearer ...",
        "Aion-Principal-Selector": "aion://agent/environment/...",
    },
}

​
Fixed capability reference

Use a fixed reference when the endpoint is known at setup time. 
from aion.api import CapabilityReference, CapabilitySubject

fixed_twitter = CapabilityReference.mcp(
    CapabilitySubject.distribution("distribution-id"),
    key="mcp.twitter.distribution",
)

config = await aion_langgraph_mcp_server_config(
    capability_references=[
        CapabilityReference.global_mcp(),
        fixed_twitter,
    ],
)
Fixed references do not require a runtime context unless you also pass runtime_capability_references. Pass an explicit principal_selector when no runtime context is available and the endpoint must be scoped to a runtime principal.

​
Runtime primary capability

Use runtime references when a graph can be reused across projects or invoked through different distributions. 
RuntimeCapabilityReference.primary_mcp(
    CapabilitySubjectSource.INCOMING_DISTRIBUTION
)
This means: when this request arrives, take the distribution from the request payload and connect to that distribution’s primary MCP capability. For agent or environment-specific tools, use another source: 
RuntimeCapabilityReference.primary_mcp(
    CapabilitySubjectSource.ACTIVE_ENVIRONMENT
)