> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Using MCP with LangGraph

> Connect LangGraph agents to Aion control-plane and capability MCP servers.

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

| Surface              | How to reference it                           | When to use it                                     |
| -------------------- | --------------------------------------------- | -------------------------------------------------- |
| Global control plane | `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.          |

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.

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
{
    "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.

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
RuntimeCapabilityReference.primary_mcp(
    CapabilitySubjectSource.ACTIVE_ENVIRONMENT
)
```

## Related pages

* [LangGraph MCP API](/sdk/langgraph/api/mcp)
* [aion-mcp](/sdk/python/packages/aion-mcp)
* [aion-api-client](/sdk/python/packages/aion-api-client)