Skip to main content
Aion supports Google ADK MCP access through aion-authoring-adk. The package builds on aion-mcp and returns ADK toolsets backed by Aion-authenticated MCP endpoints. Use MCP in ADK 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

SurfaceHow to reference itWhen to use it
Global control planeCapabilityReference.global_mcp()Stable Aion tools such as tool search and execute.
Fixed capabilityCapabilityReference.mcp(...)Subject and key are known at setup time.
Runtime capabilityRuntimeCapabilityReference.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.

​
Add Aion MCP tools to an ADK agent

Use aion_adk_mcp_toolset when tools should be resolved per request. 
from google.adk.agents import Agent

from aion.adk.mcp import aion_adk_mcp_toolset
from aion.adk.models import aion_lite_llm
from aion.api import (
    CapabilityReference,
    CapabilitySubjectSource,
    RuntimeCapabilityReference,
)

root_agent = Agent(
    name="twitter_research_agent",
    model=aion_lite_llm("model-id-from-control-plane"),
    tools=[
        aion_adk_mcp_toolset(
            capability_references=[
                CapabilityReference.global_mcp(),
            ],
            runtime_capability_references=[
                RuntimeCapabilityReference.primary_mcp(
                    CapabilitySubjectSource.INCOMING_DISTRIBUTION
                ),
            ],
        )
    ],
)
When ADK asks the toolset for tools, the Aion helper resolves:
  • the fixed global control-plane MCP server
  • the primary MCP server for the current incoming request distribution
  • bearer auth and principal selector headers for the request

​
Supplying runtime context

Runtime references need the current AionRuntimeContext. The ADK helper uses default_adk_runtime_context to read it from the ADK readonly context: 
readonly_context.aion_runtime_context
readonly_context.runtime_context
readonly_context.state["aion_runtime_context"]
readonly_context.state["runtime_context"]
If your ADK runtime stores the Aion context differently, pass context_provider: 
def aion_context_from_adk(readonly_context):
    return readonly_context.invocation_context.session.state["aion_runtime_context"]


toolset = aion_adk_mcp_toolset(
    context_provider=aion_context_from_adk,
    runtime_capability_references=[
        RuntimeCapabilityReference.primary_mcp(
            CapabilitySubjectSource.INCOMING_DISTRIBUTION
        ),
    ],
)
CapabilitySubjectSource.INCOMING_DISTRIBUTION means the incoming request distribution from the Aion Distribution extension payload. It is resolved from the current request context, not from global process state.

​
Fixed capability reference

Use a fixed reference when the endpoint is known before the request is handled. 
from aion.api import CapabilityReference, CapabilitySubject

fixed_twitter = CapabilityReference.mcp(
    CapabilitySubject.distribution("distribution-id"),
    key="mcp.twitter.distribution",
)

toolset = aion_adk_mcp_toolset(
    capability_references=[
        CapabilityReference.global_mcp(),
        fixed_twitter,
    ],
)
Pass an explicit principal_selector when no runtime context is available and the endpoint must be scoped to a runtime principal.

​
Direct McpToolset instances

If the runtime context is already available in setup code, use the synchronous helper to create direct ADK McpToolset instances. 
from aion.adk.mcp import aion_adk_mcp_toolsets_sync

toolsets = aion_adk_mcp_toolsets_sync(
    runtime_context,
    capability_references=[
        CapabilityReference.global_mcp(),
    ],
    runtime_capability_references=[
        RuntimeCapabilityReference.primary_mcp(
            CapabilitySubjectSource.INCOMING_DISTRIBUTION
        ),
    ],
)