Clarification Needed: OAuth2 Authorization Code Flow Requirements for MCP Server Integration

[priyayarrabolu-boop]

Hi team,

I’m working on integrating a third-party MCP server with the Google Agent Development Kit (ADK) and would like clarification on the exact OAuth2 setup required for Authorization Code flow.

Project Setup

• ADK agent integration with MCP server
• ADK agent deployed in Vertex AI Agent Engine
• Agent registered in Gemini Enterprise
• Tools config includes auth.oauth2 with authorization and token URLs

Problem

It’s unclear from the current documentation and GitHub discussions whether ADK supports fully automatic OAuth2 authorization-code handling, or if developers must still implement the full client-side OAuth2 callback flow in their MCP servers.

The following discussions/PRs suggest that ADK handles OAuth2 partially, but do not confirm end-to-end support for the Authorization Code flow:

• [Question] MCP tools with auth #2184
• Oauth2 Flow conflict with MCPToolSet discovery of tools #2116
• [Question] MCP tools with auth #2192
• PR MCPToolset: Add OAuth2 Client Credentials Flow with RFC 8414 Compliant Discovery #2061

From my testing:

• ADK can detect that a tool requires OAuth2
• ADK does not present an authorization URL in the ADK Web UI
• No redirect flow is initiated
• No access token is received
• It appears that ADK still expects a client-side redirect URL (/oauth/callback) and code→token exchange to be implemented manually

Key Questions

Could you please clarify:

1. Does ADK support fully automatic OAuth2 Authorization Code flow?

   • i.e., generating the authorization URL, handling the redirect, and exchanging the code for tokens without requiring a custom callback endpoint?

2. Or must developers still implement the full client-side OAuth2 callback flow
   including:

   • hosting the redirect URL
   • building /oauth/callback
   • doing the code→token exchange
   • passing the resulting token into ADK?

3. If the client-side callback is required, could you provide or point to an official end-to-end example that shows how this should be implemented for use with ADK + Vertex AI Agent Engine + Gemini Enterprise?

Any concrete guidance would be greatly appreciated.

Thank you!

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The ADK framework does not handle the OAuth2 Authorization Code flow fully automatically. Developers are required to implement the client-side portion of the flow to handle the redirect from the identity provider and pass the authorization code back to the ADK. Several end-to-end examples are available in the adk-python repository to guide this implementation.

---

Hi @priyayarrabolu-boop,

Thank you for your detailed question. Here is a clarification on the OAuth2 Authorization Code flow requirements when integrating with the Google Agent Development Kit (ADK).

1. Does ADK support fully automatic OAuth2 Authorization Code flow?

No, the ADK does not support a fully automatic Authorization Code flow where it handles the user-facing redirect and consent process without any client-side implementation. The ADK is designed to work with various "Agent Client applications" (like the ADK Web UI, a command-line interface, or a custom application). The responsibility of handling the interactive part of the OAuth2 flow—presenting the authorization URL to the user and capturing the redirect—lies with that client application. [1]

Once the user authorizes the application and is redirected back with an authorization code, the client application passes this code to the ADK. The ADK then handles the subsequent step of exchanging the authorization code for an access token and a refresh token with the identity provider. [1]

2. Or must developers still implement the full client-side OAuth2 callback flow?

Yes, developers must implement the client-side part of the OAuth2 callback flow. This typically involves:

1. Hosting a redirect URL in your client application that is registered with your OAuth2 provider.
2. Building a callback handler (e.g., /oauth/callback) that can receive the code and state query parameters from the identity provider upon successful user authorization.
3. Passing the full redirect URL (containing the code) back to the ADK framework. The ADK then takes over to complete the code-to-token exchange.

For example, in a command-line interface, the user might be prompted to manually visit the authorization URL and paste the resulting redirect URL back into the terminal. In a web-based client like the ADK Web UI, this redirect would be handled by the browser. [2]

3. Official End-to-End Examples

Yes, there are several official end-to-end examples in the adk-python GitHub repository that demonstrate how to implement this flow. These should provide a clear guide for your integration.

• OAuth Calendar Agent: This sample shows how to connect to the Google Calendar API using OAuth2 and demonstrates handling the redirect URI. You can find it in contributing/samples/oauth_calendar_agent/. [3]

• Integration Connector Agent with End-User Credentials: This example demonstrates using OAuth2 with Google Cloud Integration Connectors. The README provides context on how the ADK framework triggers and handles the OAuth flow. This sample is located in contributing/samples/integration_connector_euc_agent/. [4]

• OAuth2 Client Credentials Weather Agent: Although this sample primarily focuses on the Client Credentials flow, its included test server (oauth2_test_server.py) is also configured to handle the authorization_code grant type, making it a useful reference for building your own callback handler. You can find it at contributing/samples/oauth2_client_credentials/. [5]

These samples should provide the concrete guidance you need to implement the client-side callback flow for your MCP server.

I hope this clarifies the OAuth2 process with ADK!

---

References:
[1] ADK Custom Tools Authentication
[2] ADK CLI Auth Snippet
[3] OAuth Calendar Agent README
[4] Integration Connector EUC Agent README
[5] OAuth2 Client Credentials README

[priyayarrabolu-boop]

Hi,

Thank you for the detailed explanation regarding the OAuth2 Authorization Code flow with ADK and the references to the end-to-end examples.

We are planning to deploy our ADK agent to Vertex AI Agent Engine and then register it in Gemini Enterprise. We have some follow-up questions regarding the client-side OAuth2 setup:

1. For deployment to Vertex AI Agent Engine, do we need to implement a full client-side application (e.g., FastAPI or other web server) to handle the authorization redirect, or is there a way to use the ADK tool-side setup alone?

2. Referring to the documentation [here](https://google.github.io/adk-docs/tools-custom/authentication/#2-handling-the-interactive-oauthoidc-flow-client-side), should we follow Journey 1 or Journey 2 for our deployment scenario?

3. If a client-side setup is required, are there any specific considerations or adjustments to make it compatible with Vertex AI Agent Engine deployment?

We want to ensure that our OAuth2 setup is correct and fully functional for deployment, so any guidance or examples specific to this scenario would be extremely helpful.

Thank you for your support!