Test, debug, and evaluate in Gemini Apps Developer Mode

Use Gemini Apps Developer Mode to interactively test your Model Context Protocol (MCP) server, diagnose schema or runtime errors, and benchmark tool quality before submitting your connected app for review in the Google Connected Console.

This guide covers the following tasks:

  • Enable Gemini Apps Developer Mode in Gemini, create a custom MCP app, and verify initial tool discovery.
  • Debug failed tool calls, sync updated schemas, and test authentication.
  • Simulate user environment context and configure client authentication.

For an introduction to the workspace layout and inspector tabs, see the Gemini Apps Developer Mode overview.

Enable Gemini Apps Developer Mode

If you are onboarding your MCP server in the Google Connected Console, your registered app is already available when you enable Gemini Apps Developer Mode, and you can skip Step 2. If you want to test a deployed HTTPS MCP server endpoint directly in Gemini before registering it in the console, follow both steps to enable Gemini Apps Developer Mode and connect your server as a custom MCP app.

Step 1: Enable Gemini Apps Developer Mode

  1. Open Gemini in your web browser.
  2. Click Settings > Gemini Apps Developer Mode (or go directly to gemini.google.com/devmode).

(Optional) Step 2: Create and test a custom MCP app

To connect your MCP server as a custom app in Gemini Apps Developer Mode, do the following:

  1. In the Choose an app dialog, click + Create new.
  2. In the Connect to an MCP server dialog, enter your server's public HTTPS endpoint in MCP Server URL (make sure your URL starts with https://, for example, https://your-app-link.com/mcp).
  3. If your server requires pre-registered OAuth credentials, click Additional settings > Show more to enter your OAuth Client ID and Client secret, then click Next.
  4. In the security and privacy confirmation dialog, review how Gemini interacts with your custom MCP server:
    • Tool execution: Gemini executes your MCP server's tools to trigger and run available functions to handle your requests.
    • Data retrieval and sharing: Gemini retrieves and manages resources, schemas, and context exposed by your MCP server's endpoints, and may share information it has access to based on your Google Account settings or when interacting with other connected apps.
    • Trust and disconnection: Make sure you trust the MCP server and review its privacy policy before proceeding. You can disconnect the server at any time from your Connected Apps page or delete its link from your Google Account connections.
  5. Select I understand and accept the security and privacy risks of connecting this custom app. Then, click Connect.
  6. In the Save your custom app dialog, enter a display name for your custom app, verify that your server's tools appear in the Available actions list, and click Connect.
  7. In the Gemini Apps Developer Mode side panel, select the Tool schemas tab to review information about each tool in your connected app, including parameter definitions, safety badges (Read-only, Destructive, Auth-required), Raw schema, and Response structure.
  8. In the left chat pane, enter natural-language or @mention prompts (for example, @MyApp show my profile), and monitor the Event Log tab to see how your tool is operating.

Debug tool calls

When a tool call fails or produces unexpected arguments, you can inspect the diagnostic telemetry, update your backend MCP server, and hot-reload the schema without clearing your conversation history.

To debug a failed tool call, do the following:

  1. In the right pane, select the Event Log tab.
  2. Click the failed event in the Telemetry list to expand its details and inspect the Tool call request payload and Tool result response:
    • Connection and network errors: Check the error messages and latency to verify that your endpoint is reachable.
    • Authentication errors: If the event returns 401 or 403, verify your OAuth token state or client credentials in the Authentication tab.
    • Schema validation mismatches: If the server returns an MCP invalid parameters error (-32602), compare the model-generated JSON arguments in Tool call against the parameter types, required properties, and format instructions in the Tool Schemas tab.
    • Server runtime exceptions: Inspect the JSON-RPC error code and message in Tool result to diagnose backend exceptions.
  3. To resolve the issue, update your MCP server implementation, or refine your tool and parameter descriptions. For guidance on writing clear tool schemas and error responses, see MCP Connected app integration standards.
  4. In the Tool Schemas tab, click Sync schema. Gemini re-fetches tools/list from your MCP server and updates the active tool definitions while preserving the current chat thread.
  5. Retry your query. In the Event Log tab, confirm that the replayed tool call returns 200 OK and renders the expected response in the chat preview.

Simulate environment context and authentication

You can test how your MCP tools respond to different user locations, time zones, locales, and authentication methods directly within the inspector pane.

Override environment context

To simulate user context for date-, time-, or locale-sensitive tools, do the following:

  1. In the right pane, select the Environment tab.
  2. Under Date and Time, select a Simulated Date and Simulated Time to test relative time expressions (such as "tomorrow morning" or "this Saturday afternoon").
  3. Under Preferences, select a Language to simulate the user locale (for example, en-US).
  4. Run a test prompt in the chat pane to evaluate your tool with the simulated context.
  5. To restore the default environment settings, click Reset.

Configure client authentication

To configure or switch the authentication method used during your Gemini Apps Developer Mode session, do the following:

  1. In the right pane, select the Authentication tab.
  2. Under Client Authentication Configuration, select one of the following authentication modes:
    • Dynamic Client Registration: Uses an OAuth flow to negotiate credentials automatically with your authorization server. For more information, see the OAuth 2.1 implementation guide. If applicable, enter your endpoint in Add a custom app link.
    • Manual Client Registration: Lets you provide a pre-registered Client ID and Client Secret manually. Expand Advanced Settings to configure additional flow overrides.
  3. Click Save, and wait for a Saved message to appear. Then, run a test prompt to verify that the authenticated tools succeed.

Additional resources