Using MCP with Google ADK

Aion supports Google ADK MCP access through aion.adk.authoring, which 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

Surface	How to reference it	When to use it
Metatools (built-in)	`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.

Each surface is passed as a capability reference in the same list, the built-in metatools server included.

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.authoring import aion_adk_mcp_toolset, 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 built-in metatools 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.authoring 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
        ),
    ],
)

Python SDK

LangGraph

Google ADK

Using MCP with Google ADK

MCP surfaces

Add Aion MCP tools to an ADK agent

Supplying runtime context

Fixed capability reference

Direct `McpToolset` instances

​MCP surfaces

​Add Aion MCP tools to an ADK agent

​Supplying runtime context

​Fixed capability reference

​Direct McpToolset instances

​Related pages

MCP surfaces

Add Aion MCP tools to an ADK agent

Supplying runtime context

Fixed capability reference

Direct `McpToolset` instances

Related pages