Google ADK McpToolset: checking two structured document fixtures before adding a Runner

[ashevilleislove]

Disclosure: I maintain Ardaro. This example and write-up were prepared with AI assistance; the results below come from an executed, bounded Python test.

I wanted to check the shape of a remote MCP tool result before adding an ADK Runner or asking a model to interpret a construction document. Here is a small reproducible check using ADK's native McpToolset and McpTool.run_async.

The endpoint has two fixed, synthetic document fixtures. They take {} and require no account, wallet or payment. The receipt fixture illustrates text normalization, line items and arithmetic; the invoice fixture compares supplied invoice lines against purchase-order metadata. These are example responses, not an upload or OCR service.

Tested with Python 3.11.0, google-adk==2.9.0, mcp==1.30.0, httpx==0.28.1 and pydantic==2.13.5:

python -m pip install 'google-adk[mcp]==2.9.0' 'mcp==1.30.0' 'httpx==0.28.1' 'pydantic==2.13.5'

"""Invoke two native ADK McpTool objects without a model or runner."""
import asyncio
import hashlib
import json
import os

# This fixed-fixture endpoint is public and does not use a client certificate.
# Set only this example process; do not perform Google credential discovery.
os.environ['GOOGLE_API_USE_CLIENT_CERTIFICATE'] = 'false'

from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams

EXAMPLES = ('get_receipt_example', 'get_invoice_matching_example')

async def verify():
    toolset = McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url='https://agents.getardaro.com/mcp', timeout=30, sse_read_timeout=60),
        tool_filter=list(EXAMPLES),
    )
    fixtures = {}
    try:
        selected = {tool.name:tool for tool in await toolset.get_tools()}
        if set(selected) != set(EXAMPLES):
            raise RuntimeError('Expected exactly the two fixed example tools')
        for name in EXAMPLES:
            result = await selected[name].run_async(args={}, tool_context=None)
            if not isinstance(result, dict) or result.get('isError'):
                raise RuntimeError('Expected a successful MCP result dictionary')
            fixture = result.get('structuredContent')
            if not isinstance(fixture, dict) or fixture.get('synthetic_only') is not True:
                raise RuntimeError('Expected structured synthetic fixture')
            response = fixture.get('expected_response', fixture.get('response'))
            if response['status'] != 'review_required':
                raise RuntimeError('Review state missing')
            canonical = json.dumps(response['result'], sort_keys=True, separators=(',', ':'), ensure_ascii=False)
            identity = 'res_' + hashlib.sha256(canonical.encode()).hexdigest()
            if response['identities']['analysis_result_identity'] != identity:
                raise RuntimeError('Result identity mismatch')
            fixtures[name] = fixture
        return {'fixtures':fixtures,'selected_tools':sorted(selected),
                'invocation_method':'McpTool.run_async(args={}, tool_context=None)',
                'structured_content_preserved':True,'result_identities_valid':True}
    finally:
        await toolset.close()

if __name__ == '__main__':
    print(json.dumps(asyncio.run(asyncio.wait_for(verify(), timeout=90)), indent=2))

What the run established:

• ADK exposed exactly the two names in tool_filter.
• Both native tool invocations returned a dictionary with usable structuredContent, synthetic_only: true and review_required.
• Both result identities matched a SHA-256 digest of the canonical result JSON. This is a consistency check, not proof that a document or transaction is authentic.
• The network trace contained one initialize request (200), one initialized notification (202), one tools/list request (200) and the two fixture calls (200 each).

One connection detail: ADK 2.9.0 defaults to attempting client-certificate setup. My first bounded run blocked its separate Google credential-discovery HTTP attempt; ADK fell back and the fixture calls still passed. For this public endpoint I then explicitly set GOOGLE_API_USE_CLIENT_CERTIFICATE=false in this example process and reran successfully without that discovery warning. Do not copy that setting to an endpoint that requires a client certificate. ADK still emitted experimental-feature warnings for its authentication and graceful-error-handling paths.

tool_filter selects which tools the toolset exposes; it is not a general spending or network firewall. The audit wrapper for this run separately allowed only this endpoint, the MCP handshake and one empty-argument call to each fixture, rejecting payment/authorization headers and other HTTP clients.

This does not test an ADK Runner, model reasoning, authenticated sessions, arbitrary documents or paid tools. The examples remain advisory: matching supplied fields does not establish delivery, approve payment or write to accounting.

ADK MCP documentation · Fixed fixture evidence

If you validate MCP outputs before handing them to an ADK agent, I would be interested in which result-schema checks you keep at that boundary.