> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ezforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini / Google ADK Integration Guide

> Connect the Google Agent Development Kit (ADK) to an ezForge Ready MCP server using StreamableHTTP and OAuth 2.1

## Overview

The [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) supports MCP servers as external tool sources via `MCPToolset`. Connect it to an ezForge Ready MCP server to give Gemini agents access to a business's data and capabilities.

## Prerequisites

* An ezForge Ready business with a deployed MCP server
* Your MCP server URL (format: `https://<slug>.mcp.ezforge.ai`)
* `google-adk` Python package installed (`pip install google-adk`)
* A Google AI Studio API key or Vertex AI project

## Connecting via the Google ADK

```python theme={null}
import asyncio
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPServerParams

async def main():
    mcp_params = StreamableHTTPServerParams(
        url="https://<slug>.mcp.ezforge.ai",
    )

    tools, exit_stack = await MCPToolset.from_server(
        connection_params=mcp_params,
    )

    agent = LlmAgent(
        model="gemini-2.0-flash",
        name="business_agent",
        instruction="You help users discover information about this business.",
        tools=tools,
    )

    response = await agent.run("What services are available and what are the prices?")
    print(response.text)
    await exit_stack.aclose()

asyncio.run(main())
```

Replace `<slug>` with your business slug.

## Transport: StreamableHTTP

ezForge Ready servers use the **StreamableHTTP** transport for Gemini ADK connections. The `/.well-known/mcp-server-metadata` endpoint advertises this via:

```json theme={null}
{
  "agentDiscovery": {
    "geminiConnectionType": "StreamableHTTP"
  }
}
```

Pass the base MCP server URL to `StreamableHTTPServerParams` — do **not** append `/sse`.

## OAuth 2.1 Authentication

ezForge Ready servers require OAuth 2.1 with PKCE. The ADK `MCPToolset` performs discovery and token acquisition automatically.

Discovery chain:

1. `GET https://<slug>.mcp.ezforge.ai/.well-known/oauth-protected-resource` → authorization server URL (RFC 9728)
2. `GET <authorization-server>/.well-known/oauth-authorization-server` → token and authorization endpoints (RFC 8414)

If you need to pass an existing access token (e.g., for server-to-server use), use the `headers` parameter of `StreamableHTTPServerParams`:

```python theme={null}
mcp_params = StreamableHTTPServerParams(
    url="https://<slug>.mcp.ezforge.ai",
    headers={"Authorization": f"Bearer {access_token}"},
)
```

## Tool Schema Mapping

The Google ADK automatically converts MCP JSON Schema tool definitions to Gemini `FunctionDeclaration` format. The type mapping is:

| JSON Schema type | Gemini type |
| ---------------- | ----------- |
| `string`         | `STRING`    |
| `number`         | `NUMBER`    |
| `integer`        | `INTEGER`   |
| `boolean`        | `BOOLEAN`   |
| `array`          | `ARRAY`     |
| `object`         | `OBJECT`    |

All ezForge Ready tool parameters use these types. No custom conversion is needed.

## Agent Discovery

Discover Ready businesses via the ezForge directory and construct the `StreamableHTTPServerParams` dynamically:

```python theme={null}
import httpx
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPServerParams

async def connect_to_business(slug: str):
    async with httpx.AsyncClient() as http:
        meta = (await http.get(
            "https://ezforge.ai/.well-known/mcp-server-metadata",
            params={"subdomain": f"{slug}.mcp.ezforge.ai"},
        )).json()

    tools, exit_stack = await MCPToolset.from_server(
        connection_params=StreamableHTTPServerParams(
            url=meta["mcpServerUrl"],
        )
    )
    return tools, exit_stack
```

## Available Tools

See the [Claude Integration Guide](/ready/agent-guides/claude) for the full tool reference. All tools work identically across Claude, ChatGPT, and Gemini — the MCP protocol is agent-agnostic.

## Troubleshooting

**`MCPToolset` import error** — ensure you are on `google-adk >= 0.2.0`. Earlier versions did not include MCP support.

**Connection timeout** — ezForge Ready servers have a 30-minute session TTL. If your ADK session is idle for longer, reconnect by calling `MCPToolset.from_server()` again.

**Tool call returns `null` result** — check that the business's vertical template is deployed and that the requested tool exists for that vertical. Use `get_business_info` to confirm the server is reachable before calling vertical-specific tools.

**OAuth discovery fails** — ensure `EZFORGE_MCP_PUBLIC_URL` is reachable from the network where the ADK is running. The ADK fetches `/.well-known/oauth-protected-resource` during initialization; if this URL is blocked, authentication will fail silently.