MCP Tools

Overview

In the AI Service, there are two kinds of MCP Tools

• System MCP Tools
• Custom MCP Tools

This page describes the main features of both tools and how to set them up.

System MCP Tools

System MCP Tools are generated from the Platform API package (@dtplatform/platformapi).

They are identified by the _type property being set to system_mcp_tool.

All READ operations in the package are eligible to be exposed as MCP Tools.

Examples of system MCP Tools include:

• getFileVersionCount_IafUsageMetrics - Gets file version count for a particular name space
• getGraphicsPermissions_IafPermission - Retrieves permissions for graphics resources.
• getGroup_IafNotication - Gets a notification group

Custom MCP Tools

Custom MCP Tools are tools which are created by application developers using the REST API:

POST /aisvc/api/v1/mcp-tools.

This references a script in the Item Service.

They are identified by the _type property being set to user_mcp_tool.

When invoked through MCP, the AI Service executes the referenced Item Service script via the ScriptWorker.

How to create a custom MCP tool

To create a custom MCP tool using the REST API, do the following:

1. Decide your script target
2. Create the user MCP Tool
3. Verify that the new MCP Tool exists
4. Use the MCP Tool

Step 1: Decide your script target

A user MCP Tool wraps an Item Service script as follows:

• _script._userType - the Item Service script namespace/userType
• _script._scriptName - the script name to execute

To create the script in the Item Service, refer to the format below.

async function findfileNameByID(input, libraries, ctx, callback) {
  const id = input.id;
  const { PlatformApi } = libraries;
  let res = await PlatformApi.IafFileSvc.getFile(id, ctx);
  return {
    sucess: true,
    file_name: res._name
  }
}

Step 2: Create the user MCP Tool

To create the user MCP Tool, use the endpoint below:

POST /aisvc/api/v1/mcp-tools?nsfilter=<YOUR_NS>

Use the body below, which must be an array.

[
  {
    "_name": "GetFileNameById",
    "_description": "Tool to get file name with id.",
    "_namespaces": ["<YOUR_NS>"],
    "_schema": {
      "type": "object",
      "properties": {
        "id": { "type": "string", "description": "pass the id for file" },
        "limit": { "type": "integer", "description": "Max results", "default": 25 }
      },
      "required": ["id"],
      "additionalProperties": false
    },
    "_script": { "_userType": "file_scripts", "_scriptName": "findfileNameByID" }
  }
]

MCPTool fields

Field	Description
_schema	Defines arguments for the MCP Tool (JSON schema format).​​
_script	Points to Item Service script (_userType) and function name (_scriptName).

To run the user MCP Tool, use a prompt such as the one listed below.

get the file name for id 753acd4a-3123-48c6-b441-6437e6996d82

Note the following validation rules:

• The tool name must match ^[a-zA-Z0-9_-]{1,64}$ (no spaces).
• The schema must be a JSON schema object with type: object.

Step 3: Verify that the new MCP Tool exists

Verify that the new tool exists by using the REST API call below.

GET /aisvc/api/v1/mcp-tools?nsfilter=<YOUR_NS>&_type=user_mcp_tool

Alternatively, you could search for the tool by name, using a search phrase such as the one listed below.

...&_name=GetAssetsByTag

Step 4. Use the MCP Tool

Finally, connect your MCP client using the prompt similar to the one below.

nsfilter=<YOUR_NS>

Then call the tool by name.

How to create a MCP Tool Filter resource

A MCP Tool filter is a saved, reusable tool-selection rule-set and can be referred to while configuring the MCP server in the MCP client.

To create a MCP Tool filter, use the endpoint below.

POST /aisvc/api/v1/mcptoolfilters?nsfilter=<YOUR_NS>

Use a body such as the sample one listed below. It must be an array.

[
  {
    "_name": "File + Item system tools only",
    "_description": "Demo filter that limits tool visibility to specific services.",
    "_userType": "demo_file_item_system_tools",
    "_namespaces": ["<YOUR_NS>"],
    "_criteria": {
      "_serviceName": { "$in": ["IafFileSvc", "IafItemSvc"] },
      "_type": "system_mcp_tool"
    }
  }
]

Supported values for _criteria property

Allowed fields

• _name
• _serviceName (from tool_config._serviceName) -_type (system_mcp_tool or user_mcp_tool)

Operators

Exact match:

"_type": "system_mcp_tool"

In-list:

"_serviceName": { "$in": ["IafFileSvc", "IafItemSvc"] }

Regex:

"_name": { "$regex": "^get.*_IafFileSvc$" }

How to use the MCP Tool filter in the MCP Server

You can use the MCP Tool filter by passing the filter=... parameter.

Refer to sample API call below.

https://dev1-api.in.invicara.com/aisvc/api/v1/stateless/mcp/tools?nsfilter=<YOUR_NS>&filter=demo_file_item_system_tools

The filter parameter can have the following values:

• filter=<filter UUID>
• filter=<filter _userType>

How to apply inline query parameters

If you do not want to create a saved filter resource, you can filter directly in the MCP URL.

Note the supported query parameters:

• _serviceName (repeatable) → { "_serviceName": { "$in": [...] } }
• _name (repeatable) → { "_name": { "$in": [...] } }
• _type (repeatable) → { "_type": { "$in": [...] } }

Examples

Refer to the examples below for a range of different scenarios.

Only tools from one service

.../stateless/mcp/tools?nsfilter=<YOUR_NS>&_serviceName=IafAISvc

Allow multiple services

.../stateless/mcp/tools?nsfilter=<YOUR_NS>&_serviceName=IafFileSvc&_serviceName=IafItemSvc

Allow only specific tool names

.../stateless/mcp/tools?nsfilter=<YOUR_NS>&_name=getFiles_IafFileSvc&_name=getNamedUserItems_IafItemSvc

Combined

.../stateless/mcp/tools?nsfilter=<YOUR_NS>&_type=system_mcp_tool&_serviceName=IafFileSvc&_serviceName=IafItemSvc

Notes on using inline parameters

When using inline parameters, note the following behavior:

• If filter=... is present then the inline query parameters are ignored (filter takes precedence).
• Inline criteria supports only strings and { "$in": [...] } notation. No $regex is allowed via query parameters).