Skip to main content

Custom MCP Tools

  • optional

A Template Package can include custom MCP tools to be created or updated in the AI service for the selected project during deployment. Each tool is listed in the manifest.mcpTools array. The manifest entry names the JSON definition file under mcpTools/; the file holds the tool configuration (and may duplicate or override fields also set in the manifest).

Custom MCP tool definition files must be placed inside the mcpTools folder in the ZIP archive. The file value should match the file path relative to mcpTools/ in the ZIP.

For each entry, the manifest row is merged with the JSON file as { ...fileTool, ...mcpToolDef }, so manifest values override the file when both define the same property.

Each manifest row must include:

  • name — tool name (maps to _name); used to detect an existing custom MCP tool in the project. Must match ^[a-zA-Z0-9_-]{1,64}$.
  • file — JSON filename (or path) under mcpTools/

Each definition file must contain a single JSON object (not an array). After merging, the tool must include:

  • _script — object with:
    • _userType — script collection / user type that contains the backend function
    • _scriptName — exported function name on that script
  • _schema — JSON Schema object describing the tool's input parameters

Optional fields:

  • _description — human-readable description of the tool

The referenced script must already exist when the MCP tool step runs—typically from manifest.scripts earlier in the same package, or already present in the project.

ifExists#

If a custom MCP tool with the same name already exists:

  • default (or omitted/empty): keep the existing tool unchanged and skip this manifest entry.
  • update — the existing tool is updated with the merged definition.
  • recreate — the existing tool is deleted, then created again from the definition.

Values are compared case-insensitively.

Any value other than default, update, or recreate fails validation.

Deploy behavior#

  • Scripts, file uploads, and file-linked knowledge bases run before custom MCP tools.
  • Custom MCP tools run before agents, so agents in the same package can reference tools created in this step.
  • mcpTools[].file is read from the ZIP mcpTools/ folder and merged with the manifest row before deploy actions.
  • Existing tools are matched by _name against user MCP tools (_type: user_mcp_tool) in the project.
  • If listing existing tools fails, the entire mcpTools step is skipped.
  • If ifExists has an invalid value, the entry fails validation.

Complete example#

// manifest.json{   "Template Name": "Success MCP Tools",   "Template Version": "1.0.0",   "mcpTools": [      {         "name": "GetCourseByTitle",         "file": "get-course-by-title.json",         "ifExists": "default"      },      {         "name": "AssetLookupMcpTool",         "file": "asset-lookup.json",         "ifExists": "update"      },      {         "name": "RecreateDemoMcpTool",         "file": "recreate-demo.json",         "ifExists": "recreate"      }   ]}
// Package ZIP layoutSuccess MCP Tools.zip /|-- mcpTools /|   |-- get-course-by-title.json|   |-- asset-lookup.json|   |-- recreate-demo.json|-- manifest.json
// mcpTools/get-course-by-title.json{   "_description": "Looks up courses by title.",   "_script": {      "_userType": "course_tools",      "_scriptName": "getCourseByTitle"   },   "_schema": {      "type": "object",      "properties": {         "title": {            "type": "string",            "description": "Course title"         },         "limit": {            "type": "integer",            "description": "Max results to return"         }      },      "required": ["title"]   }}

Field split: name and ifExists are typically supplied in the manifest; _description, _script, and _schema usually live in the JSON file (or in the manifest if you prefer overrides). Ensure the script named by _script._userType / _script._scriptName is deployed (or already exists) before this step.