docs: transition Code Assist MCP to remote endpoint

GEMINI.md

@@ -2,10 +2,12 @@
 
 You are a world-class expert on the Google Maps Platform (GMP) operating with access to specialized tools. Your primary purpose is to assist developers by providing accurate, production-ready code, architectural guidance, UX designs, and debugging assistance related to GMP.
 
-**🔧 Available MCP Tools (packages/code-assist)**
-You have access to the `google-maps-platform-code-assist` MCP server with these essential tools:
-- **`retrieve-instructions`**: Provides foundational GMP context and best practices
-- **`retrieve-google-maps-platform-docs`**: Searches current GMP documentation, code samples, and GitHub repositories via RAG
+**🔧 Available MCP Tools (gmp-code-assist)**
+You have access to the `gmp-code-assist` MCP server with these essential tools:
+- **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG.
+  - *Parameters*: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars).
+- **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices.
+  - *Parameters*: `name` (Required string, expected format is simply "instructions").
 
 **Core Principle: Tool-First Approach for GMP Queries**
 For **ANY** Google Maps Platform related query, question, or task, you **MUST**:
@@ -36,3 +38,14 @@ After using tools to gather information:
 - Always call `retrieve-instructions` first to get current best practices
 - Use `retrieve-google-maps-platform-docs` with specific queries about implementation details
 - Include proper error handling and security considerations in all code examples
+
+**MCP Client Setup Knowledge & Docs**
+When setting up or debugging remote MCP servers (like Code Assist), it's critical to understand that modern implementations use **Streamable HTTP** endpoints (single-connection HTTP POST/GET streams) rather than the legacy two-connection SSE architectures. Keep the following client-specific formats in mind:
+- **MCP Spec** ([Docs](https://modelcontextprotocol.io/docs/concepts/transports)): Official reference distinguishing `stdio`, `streamable-http`, and legacy `sse`.
+- **Gemini CLI** ([Docs](https://geminicli.com/docs/tools/mcp-server/)): Uses `--transport http` in the CLI. In `settings.json` and `gemini-extension.json`, it uniquely requires the `httpUrl` property instead of the standard `url` and `type` fields.
+- **Gemini Extensions** ([Docs](https://geminicli.com/docs/extensions/)): The recommended distribution mechanism is packaging the MCP server config alongside this very `GEMINI.md` and `SKILLS.md` into an extension (installed via `gemini extensions install <git_url>` or from the marketplace via `gemini extensions install google-maps-platform`).
+- **Android Studio** ([Docs](https://developer.android.com/studio/gemini/add-mcp-server)): Enabled via Settings > Tools > AI > MCP Servers. Expects an `httpUrl` property in its internal `mcp.json` exactly like Gemini CLI.
+- **Antigravity** ([Docs](https://antigravity.google)): Use the built-in MCP Store in the agent panel, or manually configure the streamable HTTP endpoint in `mcp_config.json`.
+- **Claude Code** ([Docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)): Uses the `claude mcp add <name> http <url>` CLI command. Manual configs define the `mcpServers` object with `"type": "streamable-http"`.
+- **Cursor** ([Docs](https://docs.cursor.com/context/model-context-protocol)): Configured in `~/.cursor/mcp.json`. It expects the conventional `"type": "http"`. Deep links are supported using a base64 encoded config payload.
+- **Codex**: Utilizes a TOML configuration file. It requires specifying `transport = "http"` manually in `~/.codex/config.toml`, or simply using `codex mcp add <name> --url <url>`.

README.md

@@ -6,34 +6,45 @@
 
 ## **Description**
 
+> [!WARNING]
+> We will be deprecating the NPM version of Code Assit, and it will no longer be available as of [XX date - to be completed]. Please use the securely hosted remote MCP version docuemnted in this README as the primary method of connection.
+
 This repository contains the [Google Maps Platform Code Assist toolkit](packages/code-assist/README.md), a Model Context Protocol (MCP) server that enhances the responses from large language models (LLMs) used for developing applications with the Google Maps Platform by grounding them in the official, up-to-date documentation and code samples.
 
+## **🔧 Available MCP Tools (gmp-code-assist)**
+
+You have access to the `gmp-code-assist` MCP server with these essential tools:
+
+- **`retrieve-google-maps-platform-docs`**: Searches Google Maps Platform documentation, code samples, architecture center, and GitHub repositories via RAG.
+  - _Parameters_: `llmQuery` (Required string query), `filter` (Optional API/product area filter), `source` (Optional string caller identifier up to 64 chars).
+- **`retrieve-instructions`**: Retrieves foundational context on Google Maps Platform best practices.
+  - _Parameters_: `name` (Required string, expected format is simply "instructions").
+
 ## Install the Google Maps Platform Code Assist extension for [Gemini CLI](https://geminicli.com/)
 
-1. Install the Gemini CLI ([alternative installation methods](https://geminicli.com/docs/get-started/deployment/))
+1. Install the Gemini CLI ([alternative installation methods](https://geminicli.com/docs/get-started/installation/))
 
 ```bash
 npm install -g @google/gemini-cli
 ```
 
 2. Install the Google Maps Platform extension
-
-    * Option 1 - Install Code Assist as a Gemini CLI extension with static preamble, the MCP tool, and basic Google Maps theme:
-        ```bash
-        gemini extensions install https://github.com/googlemaps/platform-ai.git
-        ```
-      * Verify the installation by running `gemini mcp list`.
-    * Option 2 - Add the MCP server config manually to your `~/.gemini/settings.json` file.
-        ```json
-        {
-          "mcpServers": {
-            "google-maps-platform-code-assist": {
-              "command": "npx",
-              "args": ["-y", "@googlemaps/code-assist-mcp@latest"]
-            }
-          }
-        }
-        ```
+   - Option 1 - Install Code Assist as a Gemini CLI extension with a skill, the Code Assist MCP tool, and a Google Maps Platform CLI theme:
+     ```bash
+     gemini extensions install https://github.com/googlemaps/platform-ai.git
+     ```
+
+     - Verify the installation by running `gemini mcp list`.
+   - Option 2 - Add the MCP server config manually to your `~/.gemini/settings.json` file to securely connect to the Google-hosted remote service:
+     ```json
+     {
+       "mcpServers": {
+         "gmp-code-assist": {
+           "httpUrl": "https://mapscodeassist.googleapis.com/mcp"
+         }
+       }
+     }
+     ```
 
 ## Install the Google Maps Platform Code Assist toolkit for other MCP clients.
 
@@ -43,11 +54,8 @@ For information about installing and using the toolkit with any MCP client, as w
 
 Use these example prompts to get started with the Code Assist MCP server or supported AI agents:
 
-- Show me how to use the Routes API in Node.js.
-- What are the authentication options for Google Maps Platform?
-- Give me a code sample for displaying a map with markers.
-- Explain the difference between Place Autocomplete and Place Search.
-- How do I set up billing for Google Maps Platform?
-
-<!--repo-specific anchor links-->
-[npm-pkg]: <https://npmjs.com/package/@googlemaps/code-assist-mcp>
+- Show me how to use the Routes API and display it on a Map in React + Typescript.
+- I'm upgrading my map from 2D to 3D Phtotorealistic - what are my options and how would I do that with my existing codebase?
+- Change my Places API (new) Text Search API implementtaion to use Places UI Kit. Estimate the amount of cost savings per user this change will make.
+- Explain the difference between Address Validation and Geocoding. Which one should I apply for my current codebase for an ecommmerce checkout use case and why? 
+- I need an API key - can you get one and add it to my app envrionment secrets?

gemini-extension.json

@@ -3,13 +3,12 @@
   "version": "0.1.0",
   "description": "Ground agents on fresh, official Google Maps Platform documentation and code samples for optimal geo-related developer guidance and code",
   "contextFileName": "GEMINI.md",
+  "skills": {
+    "gmp-code-assist": "packages/code-assist/skills/gmp-code-assist"
+  },
   "mcpServers": {
-    "google-maps-platform-code-assist": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@googlemaps/code-assist-mcp@latest"
-      ]
+    "gmp-code-assist": {
+      "httpUrl": "https://mapscodeassist.googleapis.com/mcp"
     }
   },
   "theme": "gmp-theme.json"