api-gateway-mcp-server

API Gateway Remote MCP Server (Public Preview) This skill converts new or existing REST APIs on Google Cloud API Gateway into remote Model Context Protocol (MCP) servers ( , Public Preview ). By annotating an OpenAPI 3.x (3.0.x or 3.1.x) specification with and , API Gateway translates MCP JSON-RPC 2.0 requests ( , , , ) into standard HTTP REST requests to your backend while enforcing existing authentication and quota policies. Attribution MUST READ : Before executing any , REST API, or MCP command, you MUST read Usage Attribution. For commands executed directly in the terminal (never in gener…

)\n_OAS3_RE = re.compile(r'^3\\.[01]\\.\\d+

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)\n_HTTP_METHODS = frozenset(\n {'get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'}\n)\n_SUPPORTED_MCP_METHODS = frozenset({'get', 'post', 'put', 'patch', 'delete'})\n_MAX_TOOLS_PER_GATEWAY = 1000\n# Keys whose values are data, not schemas. A \"type\" list inside them is not a\n# schema type list. The check also skips vendor extensions (x-*).\n_NON_SCHEMA_KEYS = frozenset(\n {'const', 'default', 'enum', 'example', 'examples'}\n)\n\n\ndef _load_spec(path: str) -> dict[str, Any]:\n \"\"\"Reads the OpenAPI specification file at path as JSON or YAML.\"\"\"\n with open(path, 'r', encoding='utf-8') as f:\n content = f.read()\n try:\n data = json.loads(content)\n except json.JSONDecodeError:\n pass\n else:\n if isinstance(data, dict):\n return data\n if not _HAS_YAML:\n raise RuntimeError(\n 'PyYAML is required to parse YAML files. Install with: '\n 'pip install \"PyYAML>=6.0,\u003c7.0\"'\n )\n try:\n data = yaml.safe_load(content)\n except yaml.YAMLError as exc:\n raise ValueError(f'{path} is not valid JSON or YAML: {exc}') from exc\n if not isinstance(data, dict):\n raise ValueError(f'{path} did not parse as a YAML/JSON mapping.')\n return data\n\n\ndef _resolve(spec: dict[str, Any], obj: Any) -> Any:\n \"\"\"Follows local '#/...' $ref pointers. Returns obj if it cannot resolve.\"\"\"\n seen: set[str] = set()\n while isinstance(obj, dict) and isinstance(obj.get('$ref'), str):\n reference = obj['$ref']\n if not reference.startswith('#/') or reference in seen:\n return obj\n seen.add(reference)\n target: Any = spec\n for part in reference[2:].split('/'):\n part = part.replace('~1', '/').replace('~0', '~')\n if not isinstance(target, dict) or part not in target:\n return obj\n target = target[part]\n obj = target\n return obj\n\n\ndef _requirement_names(security: Any) -> list[set[str]]:\n \"\"\"Returns the scheme names of each non-empty security requirement.\"\"\"\n if not isinstance(security, list):\n return []\n return [\n {str(name) for name in requirement}\n for requirement in security\n if isinstance(requirement, dict) and requirement\n ]\n\n\ndef _or_with_api_key_error(\n security: Any, schemes: dict[str, Any], where: str\n) -> str | None:\n \"\"\"Returns an error if a security list has OR requirements with an API key.\n\n Args:\n security: The value of a \"security\" list.\n schemes: The security schemes from components.securitySchemes.\n where: The location of the \"security\" list, for the error message.\n\n Returns:\n The error message, or None if the security list is valid.\n \"\"\"\n requirements = _requirement_names(security)\n uses_api_key = False\n for requirement in requirements:\n for name in requirement:\n scheme = schemes.get(name)\n if isinstance(scheme, dict) and scheme.get('type') == 'apiKey':\n uses_api_key = True\n if len(requirements) > 1 and uses_api_key:\n return (\n f'The \"security\" list of {where} gives alternative (OR)'\n ' requirements, and one of them uses an API key scheme. API Gateway'\n ' does not support OR requirements with an API key. Put the schemes'\n ' in one requirement object (AND).'\n )\n return None\n\n\ndef _type_list_schemas(node: Any, location: str) -> list[tuple[str, str]]:\n \"\"\"Finds the schemas whose \"type\" is a list of more than one type.\n\n API Gateway rejects such a schema, for example `type: [\"string\", \"null\"]`,\n when you create the API config.\n\n Args:\n node: A part of the OpenAPI specification.\n location: The JSON pointer of node in the specification.\n\n Returns:\n The JSON pointer and the type list of each schema with more than one type.\n \"\"\"\n found: list[tuple[str, str]] = []\n if isinstance(node, dict):\n node_type = node.get('type')\n if isinstance(node_type, list) and len(node_type) > 1:\n found.append((location or '/', json.dumps(node_type)))\n for key, value in node.items():\n key_text = str(key)\n if key_text in _NON_SCHEMA_KEYS or key_text.startswith('x-'):\n continue\n escaped_key = key_text.replace('~', '~0').replace('/', '~1')\n found.extend(_type_list_schemas(value, f'{location}/{escaped_key}'))\n elif isinstance(node, list):\n for index, item in enumerate(node):\n found.extend(_type_list_schemas(item, f'{location}/{index}'))\n return found\n\n\ndef validate_mcp_spec(\n spec: dict[str, Any],\n) -> tuple[list[str], list[str], list[dict[str, str]]]:\n \"\"\"Returns (errors, warnings, exposed_tools) for an OpenAPI spec.\"\"\"\n errors: list[str] = []\n warnings: list[str] = []\n exposed_tools: list[dict[str, str]] = []\n\n openapi_version = str(spec.get('openapi', ''))\n if 'swagger' in spec:\n errors.append(\n 'OpenAPI 2.0 (swagger: \"2.0\") is not supported for API Gateway MCP.'\n ' Convert the specification to OpenAPI 3.0.x or 3.1.x (for example,'\n ' openapi: 3.0.4).'\n )\n elif not _OAS3_RE.match(openapi_version):\n errors.append(\n 'Expected openapi version 3.0.x or 3.1.x (for example, 3.0.4 or'\n f' 3.1.0), got \"{openapi_version}\".'\n )\n\n if 'x-google-allow' in spec:\n errors.append(\n 'Extension \"x-google-allow\" is not supported in OpenAPI 3.x and must '\n 'be removed.'\n )\n\n for location, type_list in _type_list_schemas(spec, ''):\n errors.append(\n f'The schema at {location} has more than one type ({type_list}). API'\n ' Gateway rejects a type list when you create the API config. Give the'\n ' schema one type.'\n )\n\n if 'x-google-management' in spec:\n warnings.append(\n 'Found the OpenAPI 2.0 extension \"x-google-management\". In OpenAPI'\n ' 3.x, move the metrics and quota settings into'\n ' \"x-google-api-management\".'\n )\n\n servers = spec.get('servers', [])\n if isinstance(servers, list):\n endpoint_count = sum(\n 1\n for server in servers\n if isinstance(server, dict) and 'x-google-endpoint' in server\n )\n if endpoint_count > 1:\n errors.append(\n f'Found {endpoint_count} servers with \"x-google-endpoint\"; API'\n ' Gateway permits at most one server with x-google-endpoint.'\n )\n\n management = spec.get('x-google-api-management')\n if not isinstance(management, dict):\n errors.append('Missing required root \"x-google-api-management\" mapping.')\n return errors, warnings, exposed_tools\n\n backends = management.get('backends')\n backend_names: set[str] = set()\n if not isinstance(backends, dict) or not backends:\n errors.append(\n '\"x-google-api-management.backends\" must define at least one named'\n ' backend.'\n )\n else:\n for backend_name, backend_config in backends.items():\n backend_names.add(str(backend_name))\n if not isinstance(backend_config, dict) or not backend_config.get(\n 'address'\n ):\n errors.append(\n f'Backend \"{backend_name}\" is missing a required \"address\".'\n )\n\n components = spec.get('components')\n schemes = (\n components.get('securitySchemes', {})\n if isinstance(components, dict)\n else {}\n )\n if not isinstance(schemes, dict):\n schemes = {}\n\n root_or_error = _or_with_api_key_error(\n spec.get('security'), schemes, 'the root'\n )\n if root_or_error:\n errors.append(root_or_error)\n\n mcp_config = management.get('mcp')\n global_mcp_enabled = False\n if isinstance(mcp_config, bool):\n global_mcp_enabled = mcp_config\n if mcp_config:\n warnings.append(\n 'tools/list is unauthenticated (\"mcp: true\"). Configure '\n 'x-google-api-management.mcp.tools-list.security with a JWT or API '\n 'key scheme for production.'\n )\n elif isinstance(mcp_config, dict):\n global_mcp_enabled = True\n tools_list = mcp_config.get('tools-list', {})\n if isinstance(tools_list, dict) and 'security' in tools_list:\n tools_list_security = tools_list.get('security')\n if (\n not isinstance(tools_list_security, dict)\n or len(tools_list_security) != 1\n ):\n errors.append(\n '\"x-google-api-management.mcp.tools-list.security\" must be a map '\n 'naming exactly one JWT or API key security scheme.'\n )\n else:\n scheme_name = str(next(iter(tools_list_security.keys())))\n scheme_def = schemes.get(scheme_name)\n is_jwt = isinstance(scheme_def, dict) and (\n scheme_def.get('type') == 'oauth2'\n and isinstance(scheme_def.get('x-google-auth'), dict)\n )\n is_api_key = (\n isinstance(scheme_def, dict) and scheme_def.get('type') == 'apiKey'\n )\n if not isinstance(scheme_def, dict):\n errors.append(\n 'tools-list.security references unknown security scheme'\n f' \"{scheme_name}\" not defined under components.securitySchemes.'\n )\n elif not is_jwt and not is_api_key:\n errors.append(\n f'tools-list.security scheme \"{scheme_name}\" must be a JWT scheme'\n ' (type \"oauth2\" with an \"x-google-auth\" configuration) or an API'\n ' key scheme (type \"apiKey\").'\n )\n elif is_api_key:\n if (\n scheme_def.get('in') != 'header'\n or str(scheme_def.get('name', '')).lower() != 'x-api-key'\n ):\n warnings.append(\n f'tools-list.security names API key scheme \"{scheme_name}\",'\n ' but tools/list reads API keys only from the \"x-api-key\"'\n ' header. Define the scheme with \"in: header\" and \"name:'\n ' x-api-key\".'\n )\n else:\n root_requirements = _requirement_names(spec.get('security'))\n if not any(\n scheme_name in requirement for requirement in root_requirements\n ):\n errors.append(\n f'tools-list.security names JWT scheme \"{scheme_name}\", but the'\n ' root \"security\" list does not reference it. API Gateway'\n f' rejects this config. Add \"{scheme_name}: []\" to the root'\n ' \"security\" list (in the same requirement object as an API'\n ' key scheme, if there is one).'\n )\n elif all(\n scheme_name in requirement for requirement in root_requirements\n ):\n warnings.append(\n f'The root \"security\" list requires \"{scheme_name}\" on every'\n ' REST operation that does not set its own \"security\". Tell the'\n ' user that the gateway rejects REST callers without this JWT.'\n )\n else:\n warnings.append(\n f'The root \"security\" list names \"{scheme_name}\" as one of'\n ' several alternatives. REST operations that do not set their'\n ' own \"security\" accept any of the alternatives.'\n )\n else:\n warnings.append(\n 'x-google-api-management.mcp does not configure tools-list.security; '\n 'tools/list will be unauthenticated.'\n )\n\n root_backend = spec.get('x-google-backend')\n if isinstance(root_backend, dict):\n errors.append(\n 'Root \"x-google-backend\" must be a string referencing a backend in '\n 'x-google-api-management.backends, not an inline OpenAPI 2.0 object.'\n )\n elif (\n isinstance(root_backend, str)\n and backend_names\n and root_backend not in backend_names\n ):\n errors.append(\n f'Root x-google-backend \"{root_backend}\" is not defined in '\n 'x-google-api-management.backends.'\n )\n\n seen_names: set[str] = set()\n router_operations: list[str] = []\n explicit_opt_in = False\n implicit_tool_count = 0\n paths = spec.get('paths', {})\n if isinstance(paths, dict):\n for path_str, path_item in paths.items():\n if not isinstance(path_item, dict):\n continue\n if 'x-google-mcp-tool' in path_item:\n errors.append(\n f'Path \"{path_str}\" declares \"x-google-mcp-tool\" at the path level.'\n ' It must only be specified at the individual operation level.'\n )\n path_parameters = path_item.get('parameters')\n for raw_method, operation in path_item.items():\n method = str(raw_method).lower()\n if method not in _HTTP_METHODS or not isinstance(operation, dict):\n continue\n label = f'{method.upper()} {path_str}'\n if not str(operation.get('operationId') or '').strip():\n errors.append(\n f'Operation {label} has no operationId. API Gateway requires an'\n ' operationId on every operation, with or without MCP.'\n )\n mcp_tool = operation.get('x-google-mcp-tool')\n if 'x-google-model-router' in operation:\n router_operations.append(label)\n if mcp_tool is True or isinstance(mcp_tool, dict):\n explicit_opt_in = True\n continue\n if 'security' in operation:\n operation_or_error = _or_with_api_key_error(\n operation.get('security'), schemes, f'operation {label}'\n )\n if operation_or_error:\n errors.append(operation_or_error)\n operation_backend = operation.get('x-google-backend', root_backend)\n if isinstance(operation.get('x-google-backend'), dict):\n errors.append(\n f'Operation {label} uses an inline \"x-google-backend\" object'\n ' instead of a string backend name.'\n )\n elif (\n isinstance(operation_backend, str)\n and backend_names\n and operation_backend not in backend_names\n ):\n errors.append(\n f'Operation {label} references undefined backend'\n f' \"{operation_backend}\".'\n )\n\n if mcp_tool is not None and not isinstance(mcp_tool, (bool, dict)):\n errors.append(\n f'Operation {label} has invalid x-google-mcp-tool type (must be'\n ' boolean or object).'\n )\n continue\n if mcp_tool is False:\n continue\n explicit = mcp_tool is True or isinstance(mcp_tool, dict)\n if explicit:\n explicit_opt_in = True\n elif not global_mcp_enabled:\n continue\n\n if method not in _SUPPORTED_MCP_METHODS:\n if explicit:\n errors.append(\n f'Operation {label} explicitly opts into MCP, but HTTP method'\n f' {method.upper()} is not supported (only GET, POST, PUT,'\n ' PATCH, DELETE).'\n )\n continue\n\n if not operation_backend:\n if explicit:\n errors.append(\n f'Operation {label} opts into MCP, but it has no'\n ' x-google-backend. Each exposed operation needs a backend.'\n )\n else:\n warnings.append(\n f'Operation {label} has no x-google-backend, so it is not'\n ' eligible as an MCP tool.'\n )\n continue\n\n parameters = []\n for parameter_list in (path_parameters, operation.get('parameters')):\n if isinstance(parameter_list, list):\n parameters.extend(\n _resolve(spec, parameter) for parameter in parameter_list\n )\n for parameter in parameters:\n if not isinstance(parameter, dict):\n continue\n parameter_name = str(parameter.get('name', ''))\n if str(parameter.get('in', '')).lower() == 'header' and (\n parameter_name.lower().startswith('x-google-')\n ):\n errors.append(\n f'Operation {label} binds a header parameter to reserved'\n f' prefix \"{parameter_name}\".'\n )\n schema = _resolve(spec, parameter.get('schema'))\n if isinstance(schema, dict) and (\n schema.get('type') in ('array', 'object')\n or 'items' in schema\n or 'properties' in schema\n ):\n warnings.append(\n f'Operation {label} parameter \"{parameter_name}\" is not a'\n ' primitive type. API Gateway supports only primitive types in'\n ' request parameters. Change it to a primitive type, or set'\n ' \"x-google-mcp-tool: false\" on the operation.'\n )\n\n if isinstance(mcp_tool, dict) and 'name' in mcp_tool:\n raw_name = mcp_tool['name']\n if not isinstance(raw_name, str) or not _TOOL_NAME_RE.match(raw_name):\n errors.append(\n f'x-google-mcp-tool.name on {label} must be a string that'\n f' matches [A-Za-z0-9_.-]{{1,128}}, got {raw_name!r}.'\n )\n continue\n tool_name = raw_name\n else:\n tool_name = str(operation.get('operationId') or '')\n if not tool_name:\n # Reported above: every operation needs an operationId.\n continue\n if not _TOOL_NAME_RE.match(tool_name):\n errors.append(\n f'Tool name \"{tool_name}\" (the operationId of {label}) does not'\n ' match [A-Za-z0-9_.-]{1,128}. Set x-google-mcp-tool.name.'\n )\n if tool_name in seen_names:\n errors.append(f'Duplicate MCP tool name \"{tool_name}\".')\n seen_names.add(tool_name)\n\n override_description = (\n mcp_tool.get('description') if isinstance(mcp_tool, dict) else None\n )\n tool_description = str(\n override_description\n or operation.get('description')\n or operation.get('summary')\n or ''\n ).strip()\n if not tool_description:\n errors.append(\n f'Exposed MCP operation {label} (\"{tool_name}\") has no'\n ' resolvable description or summary.'\n )\n\n responses = operation.get('responses', {})\n if isinstance(responses, dict) and (\n '204' in responses or 204 in responses\n ):\n warnings.append(\n f'Operation {label} (\"{tool_name}\") declares an HTTP 204'\n ' response. MCP does not support operations that return an empty'\n ' body. Return 200 with a JSON body, or set'\n ' \"x-google-mcp-tool: false\".'\n )\n\n if not explicit:\n implicit_tool_count += 1\n exposed_tools.append({\n 'name': tool_name,\n 'method': method.upper(),\n 'path': path_str,\n })\n\n if global_mcp_enabled or explicit_opt_in:\n for label in router_operations:\n errors.append(\n f'Operation {label} uses \"x-google-model-router\". MCP and model'\n ' routing cannot be used in the same API configuration.'\n )\n if 'ai' in management and not router_operations:\n warnings.append(\n '\"x-google-api-management.ai\" configures model routing. MCP and model'\n ' routing cannot be used in the same API configuration. Remove the'\n ' \"ai\" block, or move model routing to a separate API config.'\n )\n if isinstance(mcp_config, dict) and implicit_tool_count:\n warnings.append(\n 'x-google-api-management.mcp is an object, so MCP also exposes'\n f' {implicit_tool_count} operation(s) that do not set'\n ' x-google-mcp-tool. Check exposed_tools, and set'\n ' \"x-google-mcp-tool: false\" on operations that agents must not call.'\n )\n\n if not exposed_tools:\n warnings.append(\n 'No operations resolved as exposed MCP tools; /mcp will expose 0 tools.'\n )\n elif len(exposed_tools) > _MAX_TOOLS_PER_GATEWAY:\n errors.append(\n f'This file exposes {len(exposed_tools)} MCP tools. A gateway serves at'\n f' most {_MAX_TOOLS_PER_GATEWAY:,} MCP tools.'\n )\n\n return errors, warnings, exposed_tools\n\n\ndef main(argv: list[str] | None = None) -> int:\n parser = argparse.ArgumentParser(\n description=(\n 'Validate an OpenAPI specification against Google Cloud API Gateway '\n 'MCP Public Preview constraints.'\n )\n )\n parser.add_argument(\n '--spec',\n required=True,\n help='Path to the OpenAPI YAML or JSON specification file to validate.',\n )\n args = parser.parse_args(argv)\n\n try:\n spec = _load_spec(args.spec)\n errors, warnings, exposed_tools = validate_mcp_spec(spec)\n except (OSError, RuntimeError, ValueError) as exc:\n print(f'Error: {exc}', file=sys.stderr)\n return 2\n\n status = 'FAIL' if errors else 'PASS'\n report = {\n 'status': status,\n 'spec': args.spec,\n 'exposed_tool_count': len(exposed_tools),\n 'exposed_tools': exposed_tools,\n 'errors': errors,\n 'warnings': warnings,\n }\n print(json.dumps(report, indent=2))\n if errors:\n print(\n f'MCP OpenAPI validation failed with {len(errors)} error(s).',\n file=sys.stderr,\n )\n return 1\n return 0\n\n\nif __name__ == '__main__':\n sys.exit(main())\n","content_type":"text/x-python; charset=utf-8","language":"python","size":22552,"content_sha256":"35b7029a122a7fc7fbe7d828372ffbe9dcf4b55c9073b101ea9c24d89f7b2c36"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"API Gateway Remote MCP Server (Public Preview)","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill converts new or existing REST APIs on Google Cloud API Gateway into remote Model Context Protocol (MCP) servers (","type":"text"},{"text":"POST https://{default_hostname}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Public Preview","type":"text","marks":[{"type":"strong"}]},{"text":"). By annotating an OpenAPI 3.x (3.0.x or 3.1.x) specification with ","type":"text"},{"text":"x-google-api-management.mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"x-google-mcp-tool","type":"text","marks":[{"type":"code_inline"}]},{"text":", API Gateway translates MCP JSON-RPC 2.0 requests (","type":"text"},{"text":"initialize","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"notifications/initialized","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tools/call","type":"text","marks":[{"type":"code_inline"}]},{"text":") into standard HTTP REST requests to your backend while enforcing existing authentication and quota policies.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Attribution","type":"text"}]},{"type":"paragraph","content":[{"text":"MUST READ","type":"text","marks":[{"type":"strong"}]},{"text":": Before executing any ","type":"text"},{"text":"gcloud","type":"text","marks":[{"type":"code_inline"}]},{"text":", REST API, or MCP command, you MUST read ","type":"text"},{"text":"Usage Attribution","type":"text","marks":[{"type":"link","attrs":{"href":"references/attribution.md","title":null}}]},{"text":". For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix ","type":"text"},{"text":"gcloud","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"CLOUDSDK_METRICS_REQUEST_ATTRIBUTION=\"agent-skills/1.0 (skill:api-gateway-mcp-server)\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and append ","type":"text"},{"text":"agent-skills/1.0 (skill:api-gateway-mcp-server)","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"User-Agent","type":"text","marks":[{"type":"code_inline"}]},{"text":" headers.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install the Google Cloud CLI and the validator dependency:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install the ","type":"text"},{"text":"Google Cloud CLI","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt","title":null}}]},{"text":". Then update it to the latest version with ","type":"text"},{"text":"gcloud components update","type":"text","marks":[{"type":"code_inline"}]},{"text":". An old CLI can fail when it uploads an OpenAPI 3.x API config.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install Python 3.10 or later and ","type":"text"},{"text":"PyYAML","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the local OpenAPI MCP validator script:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"pip install \"PyYAML>=6.0,\u003c7.0\"","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Authenticate your environment:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Local CLI session: ","type":"text"},{"text":"gcloud auth login","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Application Default Credentials (SDKs / ADK): ","type":"text"},{"text":"gcloud auth application-default login","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select or create a project, confirm billing, and pick a supported gateway location:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select an existing project (","type":"text"},{"text":"gcloud config set project {project_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":") or create one (","type":"text"},{"text":"gcloud projects create {project_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm that an active billing account is linked to ","type":"text"},{"text":"{project_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":". API Gateway has a free monthly allowance of API calls for each billing account, but you still need an active billing account to deploy. Calls above the allowance and network data transfer out are charged. For current prices, see ","type":"text"},{"text":"API Gateway pricing","type":"text","marks":[{"type":"link","attrs":{"href":"https://cloud.google.com/api-gateway/pricing","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"us-central1","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the default ","type":"text"},{"text":"--location","type":"text","marks":[{"type":"code_inline"}]},{"text":" for gateway commands. For the other supported regions, see ","type":"text"},{"text":"API Gateway deployment model","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.cloud.google.com/api-gateway/docs/deployment-model.md.txt","title":null}}]},{"text":".","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Enable the required Google Cloud APIs:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"gcloud services enable \\\n apigateway.googleapis.com \\\n servicemanagement.googleapis.com \\\n servicecontrol.googleapis.com \\\n --project={project_id}","type":"text"}]},{"type":"paragraph","content":[{"text":"For API hub discovery (optional), enable the API hub API in the API hub host project: ","type":"text"},{"text":"gcloud services enable apihub.googleapis.com --project={hub_project_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":". To query Agent Registry (optional), also run ","type":"text"},{"text":"gcloud services enable agentregistry.googleapis.com --project={project_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify the IAM roles (use the most restrictive role for each step):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"To create and update the API, API configs, and gateways: API Gateway Admin (","type":"text"},{"text":"roles/apigateway.admin","type":"text","marks":[{"type":"code_inline"}]},{"text":") on ","type":"text"},{"text":"{project_id}","type":"text","marks":[{"type":"code_inline"}]},{"text":". To run the ","type":"text"},{"text":"gcloud services enable","type":"text","marks":[{"type":"code_inline"}]},{"text":" commands: Service Usage Admin (","type":"text"},{"text":"roles/serviceusage.serviceUsageAdmin","type":"text","marks":[{"type":"code_inline"}]},{"text":") on that project.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"To reference the gateway service account in an API config: Service Account User (","type":"text"},{"text":"roles/iam.serviceAccountUser","type":"text","marks":[{"type":"code_inline"}]},{"text":") on ","type":"text"},{"text":"{gateway_sa_name}@{project_id}.iam.gserviceaccount.com","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For a Cloud Run backend: grant the gateway service account the Cloud Run Invoker role (","type":"text"},{"text":"roles/run.invoker","type":"text","marks":[{"type":"code_inline"}]},{"text":") on the service.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"To mint test ID tokens as a caller service account: Service Account Token Creator (","type":"text"},{"text":"roles/iam.serviceAccountTokenCreator","type":"text","marks":[{"type":"code_inline"}]},{"text":") on ","type":"text"},{"text":"{caller_sa_email}","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reference: ","type":"text"},{"text":"Configure the development environment","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.cloud.google.com/api-gateway/docs/configure-dev-env.md.txt","title":null}}]},{"text":".","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Decision Matrix: MCP Server Configuration and Client Integration","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Task","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Required Mechanism","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Critical Guardrail","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Detailed Reference","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Migrate OpenAPI 2.0 (","type":"text"},{"text":"swagger: \"2.0\"","type":"text","marks":[{"type":"code_inline"}]},{"text":") or author OpenAPI 3.x for MCP","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Root ","type":"text"},{"text":"x-google-api-management.mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" + named ","type":"text"},{"text":"backends","type":"text","marks":[{"type":"code_inline"}]},{"text":" + operation-level ","type":"text"},{"text":"x-google-mcp-tool","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"NEVER add MCP extensions to an OpenAPI 2.0 spec. ","type":"text"},{"text":"Rationale:","type":"text","marks":[{"type":"strong"}]},{"text":" MCP is not supported for OpenAPI 2.0. Use OpenAPI 3.0.x or 3.1.x, and deploy the spec with ","type":"text"},{"text":"gcloud api-gateway api-configs create","type":"text","marks":[{"type":"code_inline"}]},{"text":". Keep all MCP operations in one OpenAPI document: if an API config has several documents, API Gateway serves the MCP tools of only one of them.","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OpenAPI 2.0 to 3.x Migration","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-v2-to-v3-mcp-migration.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Optimize tool names, descriptions, and schemas for LLM tool selection","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"x-google-mcp-tool","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code_inline"}]},{"text":") + described ","type":"text"},{"text":"requestBody","type":"text","marks":[{"type":"code_inline"}]},{"text":" properties","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Every operation MUST have an ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":", with or without MCP. Every exposed tool MUST resolve to a unique name that matches ","type":"text"},{"text":"[A-Za-z0-9_.-]{1,128}","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"x-google-mcp-tool.name","type":"text","marks":[{"type":"code_inline"}]},{"text":", or else the ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":"), a non-empty description, and a non-empty response body (","type":"text"},{"text":"HTTP 204","type":"text","marks":[{"type":"code_inline"}]},{"text":" is unsupported). Only ","type":"text"},{"text":"GET","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"PUT","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"PATCH","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"DELETE","type":"text","marks":[{"type":"code_inline"}]},{"text":" operations can be tools, and a gateway serves at most 1,000 tools. API Gateway rejects complex nested schemas when you create the API config, but a simple nested object body works. In OpenAPI 3.1, give each schema one ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code_inline"}]},{"text":", because API Gateway also rejects a type list such as ","type":"text"},{"text":"type: [\"string\", \"null\"]","type":"text","marks":[{"type":"code_inline"}]},{"text":". Describe each property, and check each tool's ","type":"text"},{"text":"inputSchema","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" after you deploy.","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OpenAPI Agent Tool Optimizer","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-agent-tool-optimizer.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Secure ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" and hide internal/admin routes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"x-google-api-management.mcp.tools-list.security","type":"text","marks":[{"type":"code_inline"}]},{"text":" (exactly one JWT or API key scheme; a JWT scheme is also listed in root ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":") + ","type":"text"},{"text":"x-google-mcp-tool: false","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" is unauthenticated by default. It accepts one JWT scheme, or one API key scheme sent in the ","type":"text"},{"text":"x-api-key","type":"text","marks":[{"type":"code_inline"}]},{"text":" header. API Gateway rejects a config whose JWT ","type":"text"},{"text":"tools-list.security","type":"text","marks":[{"type":"code_inline"}]},{"text":" scheme is missing from the root ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" list, and that root entry also requires the JWT on every REST operation without its own ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":". If the root list already has an API key scheme, add the JWT to the same requirement object (AND): API Gateway does not support alternative (OR) requirements with an API key. An ","type":"text"},{"text":"mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" object (for ","type":"text"},{"text":"tools-list","type":"text","marks":[{"type":"code_inline"}]},{"text":") also enables MCP for every eligible operation, so opt out each operation that agents must not use. ","type":"text"},{"text":"x-google-mcp-tool: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" hides a route from MCP only; keep REST ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" on admin routes.","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OpenAPI 2.0 to 3.x Migration","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-v2-to-v3-mcp-migration.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Connect Google ADK (","type":"text"},{"text":"McpToolset","type":"text","marks":[{"type":"code_inline"}]},{"text":") and discover in API hub / Agent Registry","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"McpToolset","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"StreamableHTTPConnectionParams","type":"text","marks":[{"type":"code_inline"}]},{"text":") + API hub project attachment","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No separate registration step is needed. After you attach the API Gateway project to API hub, the MCP server appears in API hub as ","type":"text"},{"text":"{your_api} (MCP)","type":"text","marks":[{"type":"code_inline"}]},{"text":" and in Agent Registry automatically.","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ADK and API Hub Discovery","type":"text","marks":[{"type":"link","attrs":{"href":"references/adk-and-api-hub-discovery.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verify ","type":"text"},{"text":"/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" JSON-RPC lifecycle and troubleshoot ","type":"text"},{"text":"-32601","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"-32602","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"-32000","type":"text","marks":[{"type":"code_inline"}]},{"text":" errors","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"POST https://{default_hostname}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"MCP-Protocol-Version: 2025-11-25","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keep ","type":"text"},{"text":"/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the host root: a ","type":"text"},{"text":"servers","type":"text","marks":[{"type":"code_inline"}]},{"text":" base path (such as ","type":"text"},{"text":"/v2","type":"text","marks":[{"type":"code_inline"}]},{"text":") applies to REST paths only, and ","type":"text"},{"text":"{basepath}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns HTTP 404. Nest JSON request bodies under ","type":"text"},{"text":"params.arguments.body","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"{\"body\": {...}}","type":"text","marks":[{"type":"code_inline"}]},{"text":"). NEVER combine ","type":"text"},{"text":"x-google-api-management.mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"x-google-model-router","type":"text","marks":[{"type":"code_inline"}]},{"text":" in one config. ","type":"text"},{"text":"Rationale:","type":"text","marks":[{"type":"strong"}]},{"text":" API Gateway does not allow MCP and model routing in the same API config.","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MCP Verification and Troubleshooting","type":"text","marks":[{"type":"link","attrs":{"href":"references/mcp-limitations-and-troubleshooting.md","title":null}}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution Workflow and Validation Loop","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Upgrade and annotate the OpenAPI 3.x specification:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The references in this skill contain the conversion rules: the ","type":"text"},{"text":"Swagger 2.0 Construct Conversion Map","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-v2-to-v3-mcp-migration.md#swagger-20-construct-conversion-map","title":null}}]},{"text":" covers each Swagger 2.0 construct, and the ","type":"text"},{"text":"Complete Converted Example","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-v2-to-v3-mcp-migration.md#complete-converted-example","title":null}}]},{"text":" shows a finished spec with a Google ID token scheme. Use them before you search other sources.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow ","type":"text"},{"text":"OpenAPI 2.0 to 3.x Migration","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-v2-to-v3-mcp-migration.md","title":null}}]},{"text":" and ","type":"text"},{"text":"OpenAPI Agent Tool Optimizer","type":"text","marks":[{"type":"link","attrs":{"href":"references/openapi-agent-tool-optimizer.md","title":null}}]},{"text":" to set ","type":"text"},{"text":"openapi","type":"text","marks":[{"type":"code_inline"}]},{"text":" to a 3.0.x or 3.1.x version (the examples use ","type":"text"},{"text":"3.0.4","type":"text","marks":[{"type":"code_inline"}]},{"text":"), remove unsupported OpenAPI 2.0 fields (","type":"text"},{"text":"x-google-allow","type":"text","marks":[{"type":"code_inline"}]},{"text":"), define ","type":"text"},{"text":"x-google-api-management.backends","type":"text","marks":[{"type":"code_inline"}]},{"text":" (with ","type":"text"},{"text":"jwtAudience","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"disableAuth","type":"text","marks":[{"type":"code_inline"}]},{"text":"), configure ","type":"text"},{"text":"x-google-api-management.mcp.tools-list.security","type":"text","marks":[{"type":"code_inline"}]},{"text":" with exactly one JWT or API key scheme (add a JWT scheme to the root ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" list too, in the same requirement object as any API key scheme), author ","type":"text"},{"text":"x-google-mcp-tool","type":"text","marks":[{"type":"code_inline"}]},{"text":" descriptions stating ","type":"text"},{"text":"when and why","type":"text","marks":[{"type":"em"}]},{"text":" to invoke each tool, and opt out administrative routes (","type":"text"},{"text":"x-google-mcp-tool: false","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Before you deploy, give the user a short summary that states each of these points, and get approval:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP is not supported for OpenAPI 2.0, so you converted the spec to OpenAPI 3.x.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Which operations you exposed as tools, and which you opted out with ","type":"text"},{"text":"x-google-mcp-tool: false","type":"text","marks":[{"type":"code_inline"}]},{"text":". Opted-out operations stay on REST.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" uses a JWT scheme, the root ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" entry makes every REST operation without its own ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" require the JWT. The gateway rejects REST callers without it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The MCP endpoint is ","type":"text"},{"text":"https://{default_hostname}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":", at the host root even when the spec sets a ","type":"text"},{"text":"servers","type":"text","marks":[{"type":"code_inline"}]},{"text":" base path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The limits that apply: only ","type":"text"},{"text":"GET","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"PUT","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"PATCH","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"DELETE","type":"text","marks":[{"type":"code_inline"}]},{"text":" operations can be tools, a gateway serves at most 1,000 tools, request parameters must be primitive types, API Gateway rejects complex nested schemas and OpenAPI 3.1 type lists (such as ","type":"text"},{"text":"type: [\"string\", \"null\"]","type":"text","marks":[{"type":"code_inline"}]},{"text":") when you create the API config, tools cannot return ","type":"text"},{"text":"HTTP 204","type":"text","marks":[{"type":"code_inline"}]},{"text":", and MCP is stateless with UTF-8 text responses only.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Give the same points when the user only asks for the converted spec or for advice, without a deploy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Preserve exact quota metric names in ","type":"text"},{"text":"x-google-api-management.metrics","type":"text","marks":[{"type":"code_inline"}]},{"text":" across API configs so existing gateways do not fail with HTTP 500 ","type":"text"},{"text":"Failed to call Service Control Quota","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run the deterministic MCP OpenAPI validation loop before creating the API config:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Execute ","type":"text"},{"text":"scripts/validate_mcp_openapi.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" on ","type":"text"},{"text":"{candidate_openapi_spec}","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec}","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"scripts/validate_mcp_openapi.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" exits with code ","type":"text"},{"text":"1","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"status: \"FAIL\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"), fix every reported error in ","type":"text"},{"text":"{candidate_openapi_spec}","type":"text","marks":[{"type":"code_inline"}]},{"text":" (such as OpenAPI 2.0 syntax, ","type":"text"},{"text":"x-google-allow","type":"text","marks":[{"type":"code_inline"}]},{"text":", path-level ","type":"text"},{"text":"x-google-mcp-tool","type":"text","marks":[{"type":"code_inline"}]},{"text":", undefined backend names, an operation without an ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":", missing descriptions, invalid or duplicate tool names, a header parameter with the reserved ","type":"text"},{"text":"x-google-","type":"text","marks":[{"type":"code_inline"}]},{"text":" prefix, a ","type":"text"},{"text":"tools-list.security","type":"text","marks":[{"type":"code_inline"}]},{"text":" scheme that is neither an ","type":"text"},{"text":"oauth2","type":"text","marks":[{"type":"code_inline"}]},{"text":" JWT nor an ","type":"text"},{"text":"apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":" scheme, a JWT ","type":"text"},{"text":"tools-list.security","type":"text","marks":[{"type":"code_inline"}]},{"text":" scheme missing from the root ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" list, alternative (OR) security requirements with an API key, or an ","type":"text"},{"text":"x-google-model-router","type":"text","marks":[{"type":"code_inline"}]},{"text":" operation in an MCP spec) and re-run the script until it exits with code ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"status: \"PASS\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"). If it exits with code ","type":"text"},{"text":"2","type":"text","marks":[{"type":"code_inline"}]},{"text":", fix the file path or YAML syntax error printed to stderr.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read every warning (such as an ","type":"text"},{"text":"HTTP 204","type":"text","marks":[{"type":"code_inline"}]},{"text":" response, a request parameter that is not a primitive type, or operations that an ","type":"text"},{"text":"mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" object exposes by default). Fix it, or tell the user why you keep it.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Create the API (if new), create the API config, deploy the gateway, and enable the managed service (request human approval before updating a production gateway):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"gcloud api-gateway apis create {api_id} --project={project_id}\n\ngcloud api-gateway api-configs create {config_id} \\\n --api={api_id} \\\n --openapi-spec={candidate_openapi_spec} \\\n --backend-auth-service-account={gateway_sa_name}@{project_id}.iam.gserviceaccount.com \\\n --project={project_id}\n\ngcloud api-gateway gateways update {gateway_id} \\\n --api={api_id} \\\n --api-config={config_id} \\\n --location={region} \\\n --project={project_id}\n\ngcloud services enable $(gcloud api-gateway apis describe {api_id} --project={project_id} --format=\"value(managedService)\") --project={project_id}","type":"text"}]},{"type":"paragraph","content":[{"text":"(For a brand-new gateway, run ","type":"text","marks":[{"type":"em"}]},{"text":"gcloud api-gateway gateways create {gateway_id} ...","type":"text","marks":[{"type":"code_inline"},{"type":"em"}]},{"text":" instead of ","type":"text","marks":[{"type":"em"}]},{"text":"gateways update","type":"text","marks":[{"type":"code_inline"},{"type":"em"}]},{"text":").","type":"text","marks":[{"type":"em"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run one ","type":"text"},{"text":"api-configs create","type":"text","marks":[{"type":"code_inline"}]},{"text":" at a time per API. Wait for it to finish before you start the next one, because API Gateway creates only one config for an API at a time. A complex API config can take up to ten minutes to create.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If clients use API keys from other projects, enable the managed service in each of those projects too. API Gateway rejects an API key unless the API is enabled in the project that created the key.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify the JSON-RPC 2.0 lifecycle and connect ADK / API hub:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Send every probe to ","type":"text"},{"text":"https://{default_hostname}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":", even when the spec sets a ","type":"text"},{"text":"servers","type":"text","marks":[{"type":"code_inline"}]},{"text":" base path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"An HTML ","type":"text"},{"text":"404 Page not found","type":"text","marks":[{"type":"code_inline"}]},{"text":" means that the gateway may not be deployed correctly. Check that the gateway state is ","type":"text"},{"text":"ACTIVE","type":"text","marks":[{"type":"code_inline"}]},{"text":" and that the last create or update finished, and retry before you change the config. During a gateway update, some requests can still reach the previous API config. A JSON 404 (","type":"text"},{"text":"The current request is not defined by this API.","type":"text","marks":[{"type":"code_inline"}]},{"text":") means that the active config does not define the path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" requires a JWT, mint a Google ID token whose audience is in ","type":"text"},{"text":"x-google-auth.audiences","type":"text","marks":[{"type":"code_inline"}]},{"text":": ","type":"text"},{"text":"gcloud auth print-identity-token --impersonate-service-account={caller_sa_email} --audiences={jwt_audience}","type":"text","marks":[{"type":"code_inline"}]},{"text":". If ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" requires an API key, send it in the ","type":"text"},{"text":"x-api-key","type":"text","marks":[{"type":"code_inline"}]},{"text":" header.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run the ","type":"text"},{"text":"initialize","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"notifications/initialized","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"tools/call","type":"text","marks":[{"type":"code_inline"}]},{"text":" verification probes in ","type":"text"},{"text":"MCP Verification and Troubleshooting","type":"text","marks":[{"type":"link","attrs":{"href":"references/mcp-limitations-and-troubleshooting.md","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Connect Google ADK (","type":"text"},{"text":"McpToolset","type":"text","marks":[{"type":"code_inline"}]},{"text":") and verify automatic catalog discovery in Apigee API hub (","type":"text"},{"text":"{your_api} (MCP)","type":"text","marks":[{"type":"code_inline"}]},{"text":") and Agent Registry using ","type":"text"},{"text":"ADK and API Hub Discovery","type":"text","marks":[{"type":"link","attrs":{"href":"references/adk-and-api-hub-discovery.md","title":null}}]},{"text":".","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Pre-Deployment Checklist","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Specification version is ","type":"text"},{"text":"openapi: 3.0.x","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"3.1.x","type":"text","marks":[{"type":"code_inline"}]},{"text":" (not ","type":"text"},{"text":"swagger: \"2.0\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"), omits ","type":"text"},{"text":"x-google-allow","type":"text","marks":[{"type":"code_inline"}]},{"text":", and does not contain ","type":"text"},{"text":"x-google-model-router","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"python3 scripts/validate_mcp_openapi.py --spec={candidate_openapi_spec}","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns ","type":"text"},{"text":"status: \"PASS\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" (exit code ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Every operation has an ","type":"text"},{"text":"operationId","type":"text","marks":[{"type":"code_inline"}]},{"text":", and all MCP operations are in one OpenAPI document.","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"x-google-api-management.mcp.tools-list.security","type":"text","marks":[{"type":"code_inline"}]},{"text":" names exactly one scheme: an ","type":"text"},{"text":"oauth2","type":"text","marks":[{"type":"code_inline"}]},{"text":" JWT scheme with ","type":"text"},{"text":"x-google-auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" that the root ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" list also references, or an ","type":"text"},{"text":"apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":" scheme with ","type":"text"},{"text":"in: header","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"name: x-api-key","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"tools/list","type":"text","marks":[{"type":"code_inline"}]},{"text":" uses a JWT scheme, the user knows that REST operations without their own ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" now require that JWT.","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Administrative, health-check, and ","type":"text"},{"text":"HTTP 204","type":"text","marks":[{"type":"code_inline"}]},{"text":" endpoints are opted out with ","type":"text"},{"text":"x-google-mcp-tool: false","type":"text","marks":[{"type":"code_inline"}]},{"text":", and opted-out admin paths remain protected on REST.","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"MCP clients call ","type":"text"},{"text":"https://{default_hostname}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":" (not ","type":"text"},{"text":"{basepath}/mcp","type":"text","marks":[{"type":"code_inline"}]},{"text":"), nest ","type":"text"},{"text":"tools/call","type":"text","marks":[{"type":"code_inline"}]},{"text":" JSON request bodies inside ","type":"text"},{"text":"params.arguments.body","type":"text","marks":[{"type":"code_inline"}]},{"text":", and send ","type":"text"},{"text":"MCP-Protocol-Version: 2025-11-25","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resource Cleanup","type":"text"}]},{"type":"paragraph","content":[{"text":"To avoid ongoing charges when tearing down a test or staging environment, request human approval and delete the gateway, API config, API, and service account in dependency order:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}\ngcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}\ngcloud api-gateway apis delete {api_id} --project={project_id}\ngcloud iam service-accounts delete {gateway_sa_name}@{project_id}.iam.gserviceaccount.com --project={project_id}","type":"text"}]}]},"metadata":{"date":"2026-11-02","name":"api-gateway-mcp-server","author":"@skillopedia","source":{"stars":21790,"repo_name":"skills","origin_url":"https://github.com/google/skills/blob/HEAD/skills/cloud/api-gateway-mcp-server/SKILL.md","repo_owner":"google","body_sha256":"0349386766c2732c95e26e41fbec5860e722db20554500a47028d189627399fd","cluster_key":"b672277506f5fbc1a0a9000f4013f1a299a4fa93ac121d1f3f74af8ddf826252","clean_bundle":{"format":"clean-skill-bundle-v1","source":"google/skills/skills/cloud/api-gateway-mcp-server/SKILL.md","text_bytes":65451,"source_commit":"dc266e019a32621845b6b2bb81084b3c9657774c","skills_sh_rank":13919,"attachment_count":6,"text_attachments":6,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/cloud/api-gateway-mcp-server/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"integrations-apis","category_label":"Integrations"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"integrations-apis","metadata":{"version":"1.0.1","category":"AiAndMachineLearning"},"import_tag":"skills-sh-top20k-2026-11","description":"Configures Google Cloud API Gateway to act as a remote Model Context Protocol (MCP) server (Public Preview) that exposes REST APIs as agent tools over HTTP (POST /mcp). Use when migrating OpenAPI 2.0 specs to OpenAPI 3.x for MCP, annotating specs with x-google-api-management.mcp and x-google-mcp-tool, securing tools/list with JWTs or API keys, connecting Google ADK (McpToolset) or Apigee API hub and Agent Registry, or troubleshooting MCP JSON-RPC errors (-32601, -32602, -32000). Do not use for Apigee X proxy bundles, outbound LLM model routing, or GKE Gateway API."}},"renderedAt":1793666098420}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.