Skip to main content
aion-mcp is the framework-neutral package for Aion MCP integration. It builds authenticated remote MCP endpoint metadata for Aion control-plane and capability MCP servers, and it can lazily load the local ASGI MCP proxy configured in aion.yaml. Use this package directly when you want MCP endpoint URLs and headers without committing to a specific agent framework.

​
Install

pip install aion-mcp
The package depends on aion-api-client for authentication and typed control-plane addressing.

​
MCP endpoint types

Aion exposes two broad MCP surfaces:
SurfaceReference shapeTypical path
Global control planeCapabilityReference.global_mcp()/mcp
Keyed system MCPCapabilityReference.global_mcp(key=...)/mcp/{systemKey}
Capability MCPCapabilityReference.mcp(subject, key=...)/{subject}/mcp[/{key}]
The global control-plane MCP server exposes stable Aion tools such as tool search and tool execute. It can also be addressed by its concrete system key, mcp.aion.control_plane, for callers that want all MCP endpoints to be expressed as capability references. Capability MCP servers expose behavior-declared tools for a subject such as a distribution, environment, or agent identity.

​
Build one endpoint

from aion.api import CapabilityReference, CapabilitySubject, PrincipalSelector
from aion.api import AION_CONTROL_PLANE_MCP_CAPABILITY_KEY
from aion.mcp import aion_mcp_endpoint

principal = PrincipalSelector.agent_environment("environment-id")

control_plane = await aion_mcp_endpoint(
    CapabilityReference.global_mcp(),
    principal_selector=principal,
)

keyed_control_plane = await aion_mcp_endpoint(
    CapabilityReference.global_mcp(
        key=AION_CONTROL_PLANE_MCP_CAPABILITY_KEY
    ),
    principal_selector=principal,
)

distribution_primary = await aion_mcp_endpoint(
    CapabilityReference.primary_mcp(
        CapabilitySubject.distribution("distribution-id")
    ),
    principal_selector=principal,
)
Each AionMcpEndpoint contains:
FieldPurpose
nameStable server name for multi-server MCP clients.
urlAbsolute Aion MCP endpoint URL.
headersBearer token and optional Aion-Principal-Selector header.
transportMCP transport name. Aion remote endpoints use http.
Use endpoint.as_langchain_config() or endpoint.as_multi_server_config() when passing the endpoint to LangChain’s MCP adapter.

​
Runtime-context endpoints

Use aion_runtime_context_mcp_endpoints when endpoint selection depends on the current Aion request. This helper derives the principal selector from AionRuntimeContext unless you pass one explicitly. That selector scopes outgoing control-plane calls to the request’s daemon identity when one is present, or to the active environment otherwise. 
from aion.api import (
    CapabilityReference,
    CapabilitySubjectSource,
    RuntimeCapabilityReference,
)
from aion.mcp import aion_runtime_context_mcp_endpoints

endpoints = await aion_runtime_context_mcp_endpoints(
    runtime_context,
    capability_references=[
        CapabilityReference.global_mcp(),
    ],
    runtime_capability_references=[
        RuntimeCapabilityReference.primary_mcp(
            CapabilitySubjectSource.INCOMING_DISTRIBUTION
        ),
    ],
)
This connects both:
  • the fixed global control-plane MCP server
  • the primary MCP server for the current incoming request distribution
RuntimeCapabilityReference values are templates. They resolve only when the caller supplies an AionRuntimeContext; they do not read from thread-local state.

​
Synchronous setup

The single-endpoint and runtime-context endpoint helpers have synchronous equivalents for framework setup code: 
from aion.api import CapabilityReference
from aion.mcp import aion_mcp_endpoint_sync

endpoint = aion_mcp_endpoint_sync(CapabilityReference.global_mcp())

​
Local proxy

load_proxy reads MCP proxy configuration from aion.yaml and returns an ASGI app when local MCP proxying is configured. Proxy dependencies are imported lazily so endpoint-only code can import aion.mcp without loading ASGI proxy modules. 
from aion.mcp import load_proxy

app = load_proxy()