> ## 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.

# aion-mcp

> Framework-neutral MCP endpoint and proxy utilities for Aion.

`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

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

| Surface              | Reference shape                             | Typical path             |
| -------------------- | ------------------------------------------- | ------------------------ |
| Global control plane | `CapabilityReference.global_mcp()`          | `/mcp`                   |
| Keyed system MCP     | `CapabilityReference.global_mcp(key=...)`   | `/mcp/{systemKey}`       |
| Capability MCP       | `CapabilityReference.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

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

| 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.

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

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

```python theme={null}
from aion.mcp import load_proxy

app = load_proxy()
```

## Related pages

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