Update MCP Gateways docs (#623)

* Update with VS Code

* update gateway images

Author: wdawson

app/en/get-started/quickstarts/call-tool-client/page.mdx

@@ -8,18 +8,18 @@ import { SignupLink } from "@/app/_components/analytics";
 import Image from "next/image";
 
 export const IMAGE_SCALE_FACTOR = 2;
-export const CREATE_MCP_GATEWAY_DARK_WIDTH = 1128;
-export const CREATE_MCP_GATEWAY_DARK_HEIGHT = 1644;
-export const CREATE_MCP_GATEWAY_LIGHT_WIDTH = 1136;
-export const CREATE_MCP_GATEWAY_LIGHT_HEIGHT = 1642;
-export const TOOL_PICKER_DARK_WIDTH = 2568;
-export const TOOL_PICKER_DARK_HEIGHT = 2174;
-export const TOOL_PICKER_LIGHT_WIDTH = 2568;
-export const TOOL_PICKER_LIGHT_HEIGHT = 2174;
-export const MCP_GATEWAY_URL_DARK_WIDTH = 2406;
-export const MCP_GATEWAY_URL_DARK_HEIGHT = 506;
-export const MCP_GATEWAY_URL_LIGHT_WIDTH = 2406;
-export const MCP_GATEWAY_URL_LIGHT_HEIGHT = 506;
+export const CREATE_MCP_GATEWAY_DARK_WIDTH = 921;
+export const CREATE_MCP_GATEWAY_DARK_HEIGHT = 1872;
+export const CREATE_MCP_GATEWAY_LIGHT_WIDTH = 921;
+export const CREATE_MCP_GATEWAY_LIGHT_HEIGHT = 1872;
+export const TOOL_PICKER_DARK_WIDTH = 2560;
+export const TOOL_PICKER_DARK_HEIGHT = 1518;
+export const TOOL_PICKER_LIGHT_WIDTH = 2560;
+export const TOOL_PICKER_LIGHT_HEIGHT = 1518;
+export const MCP_GATEWAY_URL_DARK_WIDTH = 2834;
+export const MCP_GATEWAY_URL_DARK_HEIGHT = 498;
+export const MCP_GATEWAY_URL_LIGHT_WIDTH = 2834;
+export const MCP_GATEWAY_URL_LIGHT_HEIGHT = 498;
 
 # Call a tool in your IDE/MCP Client
 
@@ -55,14 +55,14 @@ Create a coding agent using an MCP Gateway to call tools from multiple MCP serve
 
 <Image
   alt={"Create MCP Gateway"}
-  className="max-w-full dark:hidden"
+  className="max-w-full dark:hidden mt-4"
   src={"/images/mcp-gateway/create-mcp-gateway-light.png"}
   width={CREATE_MCP_GATEWAY_LIGHT_WIDTH / IMAGE_SCALE_FACTOR}
   height={CREATE_MCP_GATEWAY_LIGHT_HEIGHT / IMAGE_SCALE_FACTOR}
 />
 <Image
   alt={"Create MCP Gateway"}
-  className="hidden max-w-full dark:block"
+  className="hidden max-w-full dark:block mt-4"
   src={"/images/mcp-gateway/create-mcp-gateway-dark.png"}
   width={CREATE_MCP_GATEWAY_DARK_WIDTH / IMAGE_SCALE_FACTOR}
   height={CREATE_MCP_GATEWAY_DARK_HEIGHT / IMAGE_SCALE_FACTOR}
@@ -85,27 +85,28 @@ Feel free to select any tools you want to include in your specific use case.
 
 <Image
   alt={"Tool Picker"}
-  className="max-w-full dark:hidden"
-  src={"/images/mcp-gateway/tool-picker-light.png"}
+  className="max-w-full dark:hidden mt-4"
+  src={"/images/mcp-gateway/mcp-gateway-tool-filter-dev-light.png"}
   width={TOOL_PICKER_LIGHT_WIDTH / IMAGE_SCALE_FACTOR}
   height={TOOL_PICKER_LIGHT_HEIGHT / IMAGE_SCALE_FACTOR}
 />
 <Image
   alt={"Tool Picker"}
-  className="hidden max-w-full dark:block"
-  src={"/images/mcp-gateway/tool-picker-dark.png"}
+  className="hidden max-w-full dark:block mt-4"
+  src={"/images/mcp-gateway/mcp-gateway-tool-filter-dev-dark.png"}
   width={TOOL_PICKER_DARK_WIDTH / IMAGE_SCALE_FACTOR}
   height={TOOL_PICKER_DARK_HEIGHT / IMAGE_SCALE_FACTOR}
 />
 
 Once you've selected the tools you want to include in the gateway, click the "Use N tools" button in the tool picker, and then click the "Create MCP Gateway" button to create the gateway.
 
 <Callout type="info">
-  There is no limit to the number of tools you can select in an MCP Gateway.
-  However, be mindful of how the MCP clients will handle the large number of
-  tools. Some clients may not handle a large number of tools well, and may
-  consume a significant portion of the LLM's context window. As a rule of thumb,
-  we recommend keeping the number of tools in a single MCP Gateway below 80.
+  There is a large limit to the number of tools you can select in an MCP
+  Gateway. However, be mindful of how the MCP clients will handle the large
+  number of tools. Some clients may not handle a large number of tools well, and
+  may consume a significant portion of the LLM's context window. As a rule of
+  thumb, we recommend keeping the number of tools in a single MCP Gateway below
+  80.
 </Callout>
 
 ### Connect the MCP Gateway to an MCP client
@@ -119,15 +120,15 @@ Get the URL of your MCP Gateway by clicking the "Copy URL" button in the MCP Gat
 
 <Image
   alt={"MCP Gateway URL"}
-  className="max-w-full dark:hidden"
-  src={"/images/mcp-gateway/mcp-url-light.png"}
+  className="max-w-full dark:hidden mt-4"
+  src={"/images/mcp-gateway/project-mcp-gateways-light.png"}
   width={MCP_GATEWAY_URL_LIGHT_WIDTH / IMAGE_SCALE_FACTOR}
   height={MCP_GATEWAY_URL_LIGHT_HEIGHT / IMAGE_SCALE_FACTOR}
 />
 <Image
   alt={"MCP Gateway URL"}
-  className="hidden max-w-full dark:block"
-  src={"/images/mcp-gateway/mcp-url-dark.png"}
+  className="hidden max-w-full dark:block mt-4"
+  src={"/images/mcp-gateway/project-mcp-gateways-dark.png"}
   width={MCP_GATEWAY_URL_DARK_WIDTH / IMAGE_SCALE_FACTOR}
   height={MCP_GATEWAY_URL_DARK_HEIGHT / IMAGE_SCALE_FACTOR}
 />
@@ -157,41 +158,16 @@ Get the URL of your MCP Gateway by clicking the "Copy URL" button in the MCP Gat
   </Tabs.Tab>
   <Tabs.Tab>
 
-    1. Open the command palette and select **MCP: Add Server...**
+    1. Open the command palette (Mac: Cmd + Shift + p / Windows: Ctrl + Shift + p) and select **MCP: Add Server...**
     1. Choose **HTTP**
-    1. Paste the URL of your MCP Gateway. You may see a warning about Dynamic Client Registration. You can ignore this.
+    1. Paste the URL of your MCP Gateway.
     1. Give your MCP server a name, like `mcp-arcade`
-    1. Add the API key as the bearer token within the `Authorization` header, and the email address that you used to sign up for the Arcade account as the `Arcade-User-ID` header
-
-    Visual Studio Code will update your `mcp.json` file, but you will manually need to add the headers above:
-
-    ```json
-    {
-      "servers": {
-        "mcp-arcade": {
-          "url": "https://api.arcade.dev/mcp/<YOUR-GATEWAY-SLUG>",
-          "type": "http",
-          "headers": {
-            "Authorization": "Bearer {arcade_api_key}",
-            "Arcade-User-ID": "{arcade_user_id}"
-          }
-        }
-      }
-    }
-    ```
+    1. Visual Studio Code will update your `mcp.json` file.
+    1. Either in the `mcp.json` file or in the "Extensions" > "MCP Servers - Installed" pane, click the "Start" button next to your MCP server and follow the prompts to authenticate.
 
   </Tabs.Tab>
 </Tabs>
 
-<Callout type="info">
-  You can get an API key from the dashboard, following these instructions:
-  [Getting Your API Key](/get-started/setup/api-keys).
-
-The user ID is the email address that
-you used to sign up for the Arcade account.
-
-</Callout>
-
 ### Try it out
 
 1. Open your IDE's chat pane.

app/en/guides/create-tools/mcp-gateways/page.mdx

@@ -3,6 +3,14 @@ title: "MCP Gateways"
 description: "Comprehensive guide to using MCP Gateways"
 ---
 
+import Image from "next/image";
+
+export const IMAGE_SCALE_FACTOR = 2;
+export const TOOL_FILTER_LIGHT_WIDTH = 2052;
+export const TOOL_FILTER_LIGHT_HEIGHT = 1412;
+export const TOOL_FILTER_DARK_WIDTH = 2052;
+export const TOOL_FILTER_DARK_HEIGHT = 1412;
+
 # MCP Gateways
 
 MCP Gateways are a way to connect multiple MCP Servers to your agent, application, or IDE. MCP Gateways allow you to federate the tools from multiple MCP Servers into a single collection for easier management, control, and access. You can mix and match tools from different MCP Servers in the same project, and not all tools from a MCP server need to be available to the same LLM.
@@ -13,14 +21,31 @@ To configure an MCP Gateway, go to the [MCP Gateways dashboard](https://api.arca
 
 When configuring an MCP Gateway, you can select the tools you want to include in the Gateway from any MCP Servers available to the project:
 
-![MCP Gateway Configuration](/images/mcp-gateway-configuration.png)
+<Image
+  alt={"MCP Gateway Tool Filter"}
+  className="max-w-full dark:hidden mt-4"
+  src={"/images/mcp-gateway-tool-filter-light.png"}
+  width={TOOL_FILTER_LIGHT_WIDTH / IMAGE_SCALE_FACTOR}
+  height={TOOL_FILTER_LIGHT_HEIGHT / IMAGE_SCALE_FACTOR}
+/>
+<Image
+  alt={"MCP Gateway Tool Filter"}
+  className="hidden max-w-full dark:block mt-4"
+  src={"/images/mcp-gateway-tool-filter-dark.png"}
+  width={TOOL_FILTER_DARK_WIDTH / IMAGE_SCALE_FACTOR}
+  height={TOOL_FILTER_DARK_HEIGHT / IMAGE_SCALE_FACTOR}
+/>
 
 The options available when configuring an MCP Gateway are:
 
 - **Name**: The name of the MCP Gateway. Informative only.
-- **Description**: The description of the MCP Gateway. If set, this information will be returned to the LLM to hint at the purpose of the tools within the MCP Gateway.
+- **Description**: The description of the MCP Gateway. This is useful for humans and some MCP clients may surface this information to the user.
+- **LLM Instructions**: Optional instructions for the LLM about how to use the MCP Gateway.
 - **Slug**: The slug of the MCP Gateway. This is the URL slug that will be used to access the MCP Gateway. It must be unique.
-- **Allowed Tools**: If set, only the tools in the MCP Servers that are selected will be available to the MCP Gateway. If left blank, all tools from the MCP Servers available to the project will be available through the MCP Gateway.
+- **Authentication**: The authentication mode to use for the MCP Gateway. This determines how the MCP Gateway will authenticate requests to the MCP Servers. Users will still need to authenticate to the tools within the MCP Gateway as normal.
+  - **Arcade Auth**: To access the MCP Gateway, you'll need to authenticate with your Arcade account. We recommend using this authentication mode for MCP Gateways in development or testing phase, or for internal use when you know all the users will have Arcade accounts.
+  - **Arcade Headers**: To access the MCP Gateway, you'll need to authenticate with your Arcade account by passing an Arcade API key in the `Authorization` header and the user ID of your end-user in the `Arcade-User-ID` header. We recommend using this authentication mode for MCP Gateways in production when your agent or application has users without Arcade accounts.
+- **Allowed Tools**: A selection of tools in the Arcade Tool Catalog that will be available to the MCP Gateway.
 
 ## How to use MCP Gateways
 

app/en/guides/tool-calling/mcp-clients/visual-studio-code/page.mdx

@@ -10,19 +10,38 @@ In this guide, you'll learn how to connect Visual Studio Code to an Arcade MCP G
 ### Prerequisites
 
 1. Create an <SignupLink linkLocation="docs:claude-desktop-client">Arcade account</SignupLink>
-2. Get an [Arcade API key](/get-started/setup/api-keys)
-3. Create an [Arcade MCP Gateway](/guides/create-tools/mcp-gateways) and select the tools you want to use
+2. Create an [Arcade MCP Gateway](/guides/create-tools/mcp-gateways) and select the tools you want to use
 
 ### Set up Visual Studio Code
 
-3. Download and open [Visual Studio Code](https://code.visualstudio.com/download) (version 1.100.0 or higher)
+3. Download and open [Visual Studio Code](https://code.visualstudio.com/download) (version 1.107.0 or higher)
 4. Open the command palette and select **MCP: Add Server...**
 5. Choose **HTTP**
-6. Paste the URL of your MCP Gateway. You may see a warning about Dynamic Client Registration. You can ignore this.
+6. Paste the URL of your MCP Gateway.
 7. Give your MCP server a name, like `mcp-arcade`
-8. Add the API key as the bearer token within the `Authorization` header, and the email address that you used to sign up for the Arcade account as the `Arcade-User-ID` header
 
-Visual Studio Code will update your `mcp.json` file, but you will manually need to add the headers above:
+Visual Studio Code will update your `mcp.json` file.
+
+### Start the MCP Server in Visual Studio Code
+
+8. In the `mcp.json` file or in the "Extensions" > "MCP Servers - Installed" pane, click the "Start" button next to your MCP server.
+9. Visual Studio Code will prompt you to authenticate, and you may see a prompt about opening an external site: `cloud.arcade.dev`. You can safely allow both of these.
+10. If you see an Arcade login screen, authenticate with your Arcade account.
+11. You should see an Arcade consent screen asking you to authorize Visual Studio Code to access your Arcade account. Click "Allow" to continue.
+12. You should then see a webpage from Visual Studio Code saying the sign in was successful. You may see a prompt from your browser to open a link in Visual Studio Code. You can safely allow this.
+
+Your MCP Server should now be running and you can use it in Visual Studio Code.
+
+### Try it out
+
+13. Open your IDE's chat pane.
+14. Make sure you are in **Agent** mode
+15. Ask the agent to use a tool!
+
+</Steps>
+
+
+Note: if you are using the Arcade Header auth mode for your MCP Gateway, you will manually need to add the headers property in your `mcp.json` file:
 
 ```json
 {
@@ -39,4 +58,4 @@ Visual Studio Code will update your `mcp.json` file, but you will manually need
 }
 ```
 
-</Steps>
+You will not see the authentication prompts when you start the MCP Server in Visual Studio Code because the API Key is passed directly.

app/en/resources/glossary/page.mdx

@@ -177,8 +177,8 @@ To set your own credentials, set the requisite secret within the Arcade Dashboar
 ```mermaid
 graph TD
     A[Agent] --> B[Arcade Client]
-    B --> C[Arcade Engine]
-    C --> D[MCP Gateway]
+    B --> C[MCP Gateway]
+    C --> D[Arcade Engine]
     D --> E[MCP Server]
 ```
 
@@ -196,7 +196,7 @@ The Arcade Engine is also responsible for the OAuth flow for your agent's users.
 
 ### MCP Gateway
 
-MCP gateways are a feature of the Arcade Engine that allows you to add and combine multiple MCP servers in your project. The MCP gateway is responsible for routing tool execution requests to the correct MCP server, and for enforcing security and authorization decisions. You can mix and match tools from different MCP servers in the same project, and not all tools from a MCP server need to be available to the same LLM.
+MCP Gateways are a feature of the Arcade Engine that allows you to add and combine multiple MCP servers in your project. It allows your clients to speak MCP directly to Arcade and get all the functionality you'd expect from the Arcade Engine. The MCP Gateway is responsible for routing tool execution requests to the correct MCP server, and for enforcing security and authorization decisions. You can mix and match tools from different MCP servers in the same project, and not all tools from a MCP server need to be available to the same agent or LLM.
 
 ### Arcade MCP (Server Development Kit)