Skip to main content
Version: v5.1

MCP Tools

Overview#

In the AI Service, there are two kinds of 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#

FieldDescription
_schemaDefines arguments for the MCP Tool (JSON schema format).​​
_scriptPoints 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).