docs: transition Code Assist MCP to remote endpoint (#64)

* docs: switch MCP to remote SSE and update marketplace integrations

* docs: refine MCP configuration instructions and CLI commands for clients

* docs: fix Codex TOML MCP configuration and refine Claude Code instructions

* docs: fix Gemini CLI MCP transport flags and JSON config

* chore: align gemini-extension.json and Codex TOML configurations with official schemas

* docs: fix transport terminology across clients to accurately reflect Streamable HTTP

* docs: append MCP configuration learnings and official client docs to GEMINI.md

* chore: remove orphaned text files

* fix(skills): add missing YAML frontmatter to google-maps-platform-dev SKILL.md for Gemini CLI discovery

* docs: add Android Studio setup instructions and clarify marketplace installation paths for Gemini CLI and Antigravity MCPs

* docs: sync MCP tool definitions, rename to gmp-code-assist, and add deprecation notice

Note: This PR is dependent on another upcoming PR that will deprecate all of the old self-hosted version code on NPM. We have added a notice in the README that the NPM version will be deprecated and will no longer be available as of [XX date - to be completed]. Users should use the securely hosted remote version as the primary connection method, as referenced in this README.

- Renamed skill and MCP server references to strictly use 'gmp-code-assist'
- Updated MCP tools descriptions in READMEs to perfectly match the 'retrieve-google-maps-platform-docs' and 'retrieve-instructions' endpoints.
- Removed arbitrary 'vibecoding' language for safer enterprise tone.
- Ensured total consistency across root README, package README, GEMINI.md, and skill specs.

* docs: strip redundant MCP schemas from skill.md and focus purely on RAG reasoning strategies

* docs: soften rigid commands in skill prompt with explanatory reasoning

* Update installation link in README.md

updated gemini cli commit link

* Update README.md

small readme updates on human copy review

* human review: README for clarity and updated usage 

Updated README.md to improve clarity and remove deprecated information.

* docs: deprecate code assist npm package, address PR feedback

* Revise deprecation notice in README

Updated deprecation notice for NPM version of Code Assist with specific date.

* retrieve-instructions first in tool list

* Revise benefits section in README.md

Updated benefits section to clarify features and support for various AI agents.

* Update deprecation date in package.json

Author: ryanbaumann

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-instructions`**: Retrieves foundational context on Google Maps Platform best practices.
+  - *Parameters*: `name` (Required string, expected format is simply "instructions").
+- **`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).
 
 **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]
+> The npm version of Google Maps Platform Code Assist is deprecated. It will no longer be available as of July 1, 2026. Please use the securely hosted remote MCP version documented 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"