Version: v5.1

MCP Tools

The MCP Tool API lets you create, list, update, retrieve, and delete MCP tools that wrap Item Service scripts.

Note: The nsfilter query parameter is mandatory for every request. It sets the caller’s namespace context (used for scoping user tools). System mcp tools may still appear in results regardless of nsfilter.

List MCP Tools#

Endpoint#

GET /aisvc/api/v1/mcp-tools

Query parameters#

Parameter	Type	Description	Required
`nsfilter`	String	Namespace context for the request.	Required
`_offset`	Integer	Number of results to skip (must be a non-negative integer).	Optional
`_pageSize`	Integer	Page size (must be a non-negative integer).	Optional
`filter`	String	MCP tool filter identifier (UUID) or filter `userType`; when provided, other query filters are ignored.	Optional
`_name`	String	Exact Mcp tool name filter.	Optional
`_type`	String	Mcp Tool type filter (for example, `user_mcp_tool` or `system_mcp_tool`).	Optional
`_toolConfig._serviceName`	String	Filter by tool config service name such as IafFileSvc, IafItemSvc, IafPassSvc etc.Only Applicable to `system_mcp_tool`.	Optional
`_script._userType`	String	Filter by Item Service script `userType`.	Optional
`_script._scriptName`	String	Filter by Item Service script name.	Optional
`query`	String	Wildcard search over name and description.	Optional

Response codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response example#

{  "_offset": 0,  "_pageSize": 1,  "_total": 1,  "_list": [    {      "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",      "_irn": "aisvc:mcp-tool:d8a53325-dbb5-4a2d-a655-ef5fa74591d3",      "_name": "AssetLookupMcpTool",      "_description": "Searches assets by free-text query so agents can quickly find matches.",      "_namespaces": ["building_1234"],      "_type": "user_mcp_tool",      "_toolConfig": null,      "_schema": {        "type": "object",        "properties": {          "query": {            "type": "string",            "description": "Free-text string used to match asset names, tags, or metadata."          },          "maxResults": {            "type": "number",            "description": "Optional maximum number of assets to return."          }        },        "required": ["query"]      },      "_script": {        "_userType": "asset_scripts",        "_scriptName": "assetLookup"      },      "_metadata": {        "_createdAt": 1757178319536,        "_updatedAt": 1757178319536,        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b"      }    }  ]}

Create MCP Tools#

Endpoint#

POST /aisvc/api/v1/mcp-tools

Query parameters#

Parameter	Type	Description	Required
`nsfilter`	String	Namespace context for the call	Required

Body parameters#

The request body must be an array of MCP tool objects.

Parameter	Type	Description	Required
`_namespaces`	Array	Must contain at least one namespace and must be within the `nsfilter` context.	Required
`_name`	String	Must match `^[a-zA-Z0-9_-]{1,64}$` (no spaces; max 64 chars). Value must be unique.	Required
`_description`	String	Mcp Tool description.	Optional
`_schema`	Object	JSON schema for tool input; must be an object schema with `type: "object"`.	Required
`_script`	Object	Object that identifies the Item Service script with script `_userType` and `_scriptName`.	Required
`_toolConfig`	Object \| null	Optional tool configuration object; omit to keep default behavior; send `null` for none.	Optional

Note:_type cannot be set by clients; created MCP tools are always user_mcp_tool.

Response codes#

Code	Description
`201`	Created
`400`	Bad Request
`404`	Not Found

Request example#

[  {    "_name": "AssetLookupMcpTool",    "_description": "Provides a namespace-scoped asset search tool based on free-text input.",    "_namespaces": ["building_1234"],    "_schema": {      "type": "object",      "properties": {        "query": {          "type": "string",          "description": "Free-text string used to filter assets by name, tag, or metadata value."        },        "maxResults": {          "type": "number",          "description": "Optional maximum number of records returned by the tool."        }      },      "required": ["query"]    },    "_script": {      "_userType": "asset_scripts",      "_scriptName": "assetLookup"    }  }]

Response example#

{  "_offset": 0,  "_pageSize": 1,  "_total": 1,  "_list": [    {      "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",      "_irn": "aisvc:mcp-tool:d8a53325-dbb5-4a2d-a655-ef5fa74591d3",      "_name": "AssetLookupMcpTool",      "_description": "Searches assets by free-text query so agents can quickly find matches.",      "_namespaces": ["building_1234"],      "_type": "user_mcp_tool",      "_toolConfig": null,      "_schema": {        "type": "object",        "properties": {          "query": {            "type": "string",            "description": "Free-text string used to match asset names, tags, or metadata."          },          "maxResults": {            "type": "number",            "description": "Optional maximum number of assets to return."          }        },        "required": ["query"]      },      "_script": {        "_userType": "asset_scripts",        "_scriptName": "assetLookup"      },      "_metadata": {        "_createdAt": 1757178319536,        "_updatedAt": 1757178319536,        "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",        "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b"      }    }  ]}

Get MCP Tool by ID#

Endpoint#

GET /aisvc/api/v1/mcp-tools/{id}

Path parameters#

Parameter	Type	Description	Required
`id`	UUID	MCP tool identifier.	Required

Query parameters#

Parameter	Type	Description	Required
`nsfilter`	String	Namespace context for the call	Required

Response codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Response example#

{  "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",  "_irn": "aisvc:mcp-tool:d8a53325-dbb5-4a2d-a655-ef5fa74591d3",  "_name": "AssetLookupMcpTool",  "_description": "Searches assets by free-text query so agents can quickly find matches.",  "_namespaces": ["building_1234"],  "_type": "user_mcp_tool",  "_toolConfig": null,  "_schema": {    "type": "object",    "properties": {      "query": {        "type": "string",        "description": "Free-text string used to match asset names, tags, or metadata."      },      "maxResults": {        "type": "number",        "description": "Optional maximum number of assets to return."      }    },    "required": ["query"]  },  "_script": {    "_userType": "asset_scripts",    "_scriptName": "assetLookup"  },  "_metadata": {    "_createdAt": 1757178319536,    "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",    "_updatedAt": 1757178319536,    "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b"  }}

Update MCP Tool#

Endpoint#

PUT /aisvc/api/v1/mcp-tools/{id}

Path parameters#

Parameter	Type	Description	Required
`id`	UUID	MCP tool identifier.	Required

Query parameters#

Parameter	Type	Description	Required
`nsfilter`	String	Namespace context for the call	Required

Body parameters#

Parameter	Type	Description	Required
`_namespaces`	Array of strings	Required by validation; must be within `nsfilter` context; ignored on update (existing namespaces are preserved).	Required
`_name`	String	Must match `^[a-zA-Z0-9_-]{1,64}$`. Value must be unique.	Required
`_description`	String	Tool description.	Optional
`_schema`	Object	JSON schema for tool input; must be an object schema with `type: "object"`.	Required
`_script`	Object	Object that identifies the Item Service script with script `_userType` and `_scriptName`.	Required
`_toolConfig`	Object \| null	Optional; omit to keep existing; send `null` to clear.	Optional

Note: Only user_mcp_tool resources can be updated; system tools are rejected with 403.

Response codes#

Code	Description
`200`	Success
`400`	Bad Request
`404`	Not Found

Request example#

{  "_name": "AssetLookupMcpTool_Updated",  "_description": "Returns assets that match a free-text query with optional result limits.",  "_namespaces": ["building_1234"],  "_schema": {    "type": "object",    "properties": {      "query": {        "type": "string",        "description": "Free-text string used to search asset names, tags, or metadata."      },      "maxResults": {        "type": "number",        "description": "Optional maximum number of assets returned in a single response."      }    },    "required": ["query"]  },  "_script": {    "_userType": "asset_scripts",    "_scriptName": "assetLookup"  }}

Response example#

{  "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",  "_irn": "aisvc:mcp-tool:d8a53325-dbb5-4a2d-a655-ef5fa74591d3",  "_name": "AssetLookupMcpTool_Updated",  "_description": "Returns assets that match a free-text query with optional result limits.",  "_namespaces": ["building_1234"],  "_type": "user_mcp_tool",  "_toolConfig": null,  "_schema": {    "type": "object",    "properties": {      "query": {        "type": "string",        "description": "Free-text string used to search asset names, tags, or metadata."      },      "maxResults": {        "type": "number",        "description": "Optional maximum number of assets returned in a single response."      }    },    "required": ["query"]  },  "_script": {    "_userType": "asset_scripts",    "_scriptName": "assetLookup"  },  "_metadata": {    "_createdAt": 1757178319536,    "_updatedAt": 1757681000123,    "_createdById": "70699091-77de-4ee3-8a3f-034ec8746a3b",    "_updatedById": "70699091-77de-4ee3-8a3f-034ec8746a3b"  }}

Delete MCP Tool#

Endpoint#

DELETE /aisvc/api/v1/mcp-tools/{id}

Path parameters#

Parameter	Type	Description	Required
`id`	UUID	MCP tool identifier.	Required

Query parameters#

Parameter	Type	Description	Required
`nsfilter`	String	Namespace context for the call	Required

Note: System MCP tools cannot be deleted; the API returns 403.

Response#

Codes#

Code	Description
`204`	No Content
`400`	Bad Request
`404`	Not Found

Response body#

// empty response body