This page applies to Apigee and Apigee 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 the MCP API style. You can import MCP APIs from Apigee or register them manually. For more information, see Register MCP APIs.
Add MCP tools using the API
REST
To add a MCP tool to an API version, use the Create 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:
- In the Google Cloud console, go to the API hub > APIs page.
- Click the API for which you want to attach a specification file.
- Create a new API version or select an existing one.
- On the Versions page, click Add specification.
- In the Add specification file pane, configure the following:
- Specification file ID: Click Specify Unique ID to enter a custom ID. If omitted, one is generated automatically.
- Display name: Enter a name for the specification file.
- Specification file type: Select MCP Schema.
- Specification document: Click Browse to upload the MCP specification JSON file.
- Restrict upload of spec file containing errors: Don't select this checkbox.
- Click Create.
The MCP specification file is parsed and the tools are listed in the MCP Tools section of the version details page.
The following image shows the 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
- See the API reference documentation for the Operations API.
- Learn more about API specifications.
- Learn more about API operations and MCP tools.