Manage MCP tools

This pageapplies toApigee andApigee hybrid.

This page describes how to add and manage MCP tools for MCP APIs. MCP APIs are designed for AI agents, and are registered with theMCP API style. You can import MCP APIs from Apigee or register them manually. For more information, seeRegister MCP APIs.

Add MCP tools using the API

REST

To add a MCP tool to an API version, use theCreate operations API.

curl --location 'https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/apis/API_ID/versions/VERSION_ID/operations?api_operation_id=TOOL_ID' \--header "Authorization: Bearer $(gcloud auth print-access-token)" \--header 'Content-Type: application/json; charset=utf-8' \--data '{    "details": {      "description": "DESCRIPTION",      "documentation": {        "externalUri": "EXTERNAL_URI"      },      "deprecated": false,      "mcpTool": {        "name": "TOOL_NAME",        "title": "TOOL_TITLE",        "description": "TOOL_DESCRIPTION",        "annotations": {          "title": "TOOL_ANNOTATION_TITLE",          "readOnlyHint": false,          "destructiveHint": false,          "idempotentHint": true,          "openWorldHint": false,          "additionalHints": {            "custom_hint": "TOOL_ANNOTATION_CUSTOM_HINT"          }        },        "inputSchema": {        "jsonSchema": {            "type": "object",          "properties": {            "input_param": {              "type": "string"            }          }        }      },      "outputSchema": {        "jsonSchema": {           "type": "object",          "properties": {            "output_result": {              "type": "string"            }          }        }      }      }    }  }'

Replace the following:

  • PROJECT: your Google Cloud project ID.
  • LOCATION: the location of your API.
  • API_ID: the ID of your API.
  • VERSION_ID: the ID of the API version.
  • TOOL_ID: the ID of the tool.
  • DESCRIPTION: a description of the tool.
  • EXTERNAL_URI: a URI that provides more information about the tool.
  • TOOL_NAME: the name of the tool. This field is required and must not be empty. It's used to generate the operation ID.
  • TOOL_TITLE: a human-readable title for the tool.
  • TOOL_DESCRIPTION: a description of what the tool does.
  • TOOL_ANNOTATION_TITLE: an annotation title for the tool.
  • TOOL_ANNOTATION_CUSTOM_HINT: a custom hint for the tool.

Example

curl --location 'https://apihub.googleapis.com/v1/projects/apihub-test-api/locations/us-central1/apis/apihub-test-api/versions/1/operations?api_operation_id=get-weather' \--header "Authorization: Bearer $(gcloud auth print-access-token)" \--header 'Content-Type: application/json; charset=utf-8' \--data '{    "details": {      "description": "Fetches the current weather for a given location.",      "documentation": {        "externalUri": "https://www.example.com/weather"      },      "deprecated": false,      "mcpTool": {        "name": "get-weather",        "title": "Get Weather",        "description": "Fetches the current weather for a given location.",        "annotations": {          "title": "Weather Tool",          "readOnlyHint": true,          "destructiveHint": false,          "idempotentHint": true,          "openWorldHint": true,          "additionalHints": {            "apiProvider": "Some Weather API"          }        },        "inputSchema": {          "jsonSchema": {            "type": "object",            "properties": {              "location": {                "type": "string",                "description": "The city and state, e.g., San Francisco, CA"              }            },            "required": [              "location"            ]          }        },        "outputSchema": {          "jsonSchema": {            "type": "object",            "properties": {              "temperature": {                "type": "number"              },              "unit": {                "type": "string"              },              "description": {                "type": "string"              }            }          }        }      }    }  }'

Add MCP tools using a specification file

MCP tools are automatically extracted from the MCP specification file when you add it to a version of a registered MCP API.

Console

To add MCP tools using a specification file, do the following:

  1. In the Google Cloud console, go to theAPI hub> APIs page.

    Go to APIs

  2. Click the API for which you want to attach a specification file.
  3. Create a new API version or select an existing one.
  4. On theVersions page, clickAdd specification.
  5. In theAdd specification file pane, configure the following:
  6. ClickCreate.

    7. The MCP specification file is parsed and the tools are listed in theMCP Tools section of the version details page.

The following image shows theMCP Tools section of the version details page:

MCP tools section of the version details page

MCP specification file schema

JSON schema

The following JSON schema shows the structure of a valid MCP specification file.

{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the tool. This field is REQUIRED and must not be empty. It's used to generate the operation ID."},"title":{"type":"string","description":"A human-readable title for the tool. Optional."},"description":{"type":"string","description":"A description of what the tool does. Optional."},"inputSchema":{"type":"object","description":"A JSON Schema object describing the input parameters for the tool. Optional. Can be any valid JSON object.","additionalProperties":true},"outputSchema":{"type":"object","description":"A JSON Schema object describing the output structure of the tool. Optional. Can be any valid JSON object.","additionalProperties":true},"annotations":{"type":"object","description":"Optional annotations for the tool.","properties":{"title":{"type":"string","description":"Annotation title. Optional."},"readOnlyHint":{"type":"boolean","description":"Hint indicating if the tool is read-only. Optional."},"destructiveHint":{"type":"boolean","description":"Hint indicating if the tool can have destructive side effects. Optional."},"idempotentHint":{"type":"boolean","description":"Hint indicating if the tool is idempotent. Optional."},"openWorldHint":{"type":"boolean","description":"Hint indicating if the tool interacts with the open world. Optional."},"additionalHints":{"type":"object","description":"A map of additional string key-value hints. Optional.","additionalProperties":{"type":"string"}}},"additionalProperties":false}},"required":["name"],"additionalProperties":false},"description":"A list of tool objects. This array is REQUIRED at the top level."},"resources":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Optional array of resource objects. The parser doesn't strictly define their content."},"prompts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Optional array of prompt objects. The parser doesn't strictly define their content."},"errors":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Optional array of error objects. The parser doesn't strictly define their content."}},"required":["tools"],"additionalProperties":false}

Example

The following example shows a valid MCP specification file using the sample JSON schema.

{"tools":[{"name":"get-weather","title":"Get Weather","description":"Fetches the current weather for a given location.","inputSchema":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g., San Francisco, CA"}},"required":["location"]},"outputSchema":{"type":"object","properties":{"temperature":{"type":"number"},"unit":{"type":"string"},"description":{"type":"string"}}},"annotations":{"title":"Weather Tool","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true,"additionalHints":{"apiProvider":"Some Weather API"}}},{"name":"send-email","title":"Send Email","description":"Sends an email."},{"name":"tool with spaces and Upper"}],"resources":[],"prompts":[],"errors":[]}

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.