Aion MCP - Aion Docs

aion.mcp is the framework-neutral entry point to Aion MCP. It builds authenticated remote MCP endpoint metadata for Aion metatools and capability MCP servers, and it can load the local ASGI MCP proxy configured in aion.yaml. Use it directly when you want MCP endpoint URLs and headers without committing to a specific agent framework.

Install

The endpoint helpers are part of the base install:

pip install aionto-sdk

The local proxy needs an agent server extra. Calling load_proxy without one raises MissingOptionalDependency with the install commands. aion.mcp builds on aion.api for authentication and typed capability addressing.

MCP endpoint types

Aion exposes two broad MCP surfaces:

Surface	Reference shape	Path
Metatools (built-in, subjectless)	`CapabilityReference.global_mcp()`	`/mcp/capabilities/mcp.aion.metatools`
Primary capability MCP	`CapabilityReference.primary_mcp(subject)`	`/{subject}/mcp`
Concrete capability MCP	`CapabilityReference.mcp(subject, key=...)`	`/{subject}/mcp/capabilities/{key}`

The metatools MCP server exposes the stable Aion tools such as tool search and tool execute. 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.mcp import aion_mcp_endpoint

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

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

distribution_primary = await aion_mcp_endpoint(
    CapabilityReference.primary_mcp(
        CapabilitySubject.distribution("distribution-id")
    ),
    principal_selector=principal,
)

Each AionMcpEndpoint contains:

Field	Purpose
`name`	Stable server name for multi-server MCP clients.
`url`	Absolute Aion MCP endpoint URL.
`headers`	Bearer token and optional `Aion-Principal-Selector` header.
`transport`	MCP 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 metatools 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 aion.mcp from aion.yaml and returns an ASGI app proxying to the port it names:

aion:
  agents:
    support:
      path: "./agents/support.py:build_graph"
  mcp:
    port: 9000

from aion.mcp import load_proxy

app = load_proxy()

It returns None when there is no configuration file, no mcp section, or no port in it. A file that exists and is not a valid aion.yaml raises ConfigurationError: the same reader aion serve uses reads it, so a misspelled key fails by name here too rather than being read as “no proxy configured”. See aion.yaml Configuration. Under a base install the call raises MissingOptionalDependency:

aion.mcp.load_proxy requires optional dependencies.
Install one of the agent server extras:
  pip install "aionto-sdk[langgraph-server]"  # LangGraph agents
  pip install "aionto-sdk[adk-server]"        # Google ADK agents

Loading these endpoints as tools is framework-specific, and is documented under the framework you are writing for.

​Install

​MCP endpoint types

​Build one endpoint

​Runtime-context endpoints

​Synchronous setup

​Local proxy

​Related pages