Using MCP with LangGraph

Aion supports LangGraph MCP access through aion.langgraph.authoring, which 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

Surface	How to reference it	When to use it
Metatools (built-in)	`CapabilityReference.global_mcp()`	Stable Aion tools such as tool search and execute.
Fixed capability	`CapabilityReference.mcp(...)`	Subject and key are known at setup time.
Runtime capability	`RuntimeCapabilityReference.primary_mcp(...)`	Subject is known after a request arrives.

Each surface is passed as a capability reference in the same list, the built-in metatools server included.

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
)

Python SDK

LangGraph

Google ADK

Using MCP with LangGraph

MCP surfaces

Load tools inside a graph node

Build a `MultiServerMCPClient` config

Fixed capability reference

Runtime primary capability

​MCP surfaces

​Load tools inside a graph node

​Build a MultiServerMCPClient config

​Fixed capability reference

​Runtime primary capability

​Related pages

MCP surfaces

Load tools inside a graph node

Build a `MultiServerMCPClient` config

Fixed capability reference

Runtime primary capability

Related pages