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

# Using MCP with Google ADK

> Connect Google ADK agents to Aion control-plane and capability MCP servers.

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

| Surface              | How to reference it                           | When to use it                                     |
| -------------------- | --------------------------------------------- | -------------------------------------------------- |
| Global control plane | `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.          |

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.

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

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

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

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

```python theme={null}
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
        ),
    ],
)
```

## Related pages

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