MCP Tool Filters

The MCP Tool Filter API lets you create, list, update, retrieve, and delete MCP tool filters. These filters can be referenced from the MCP Tool List endpoint via filter (UUID or filter _userType) to apply a reusable set of tool-selection criteria.

Note: The nsfilter query parameter is mandatory for every request. It sets the caller’s namespace context and is automatically applied for scoping results and operations.

List MCP Tool Filters

Endpoint

GET /aisvc/api/v1/mcptoolfilters

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
_name	String	Exact filter name match.	Optional
_userType	String	Exact filter userType match.	Optional
query	String	Wildcard search over filter name and description.	Optional

Response codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Create MCP Tool Filters

Endpoint

POST /aisvc/api/v1/mcptoolfilters

Query parameters

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

Body parameters

Request body must be an array of MCP tool filter objects.

Parameter	Type	Description	Required
_namespaces	Array of strings	Must contain at least one namespace and must be within the nsfilter context.	Required
_name	String	Filter name (max 50 chars).Value must be unique.	Required
_description	String	Filter description.	Optional
_userType	String	Filter identifier used by callers (max 50 chars; must match ^\\w+$).Value must be unique	Required
_criteria	Object	Tool-selection criteria; must contain at least one supported field.	Required

_criteria format

Note: _criteria is an object where keys are the allowed fields:

• _name (MCP tool name)
• _serviceName (MCP tool config service name; that is, _toolConfig._serviceName from mcp tool resource with type system_mcp_tool).
• _type (MCP tool type, for example user_mcp_tool or system_mcp_tool)

Each field value supports:

• value for exact match
• { "$in": ["value1", "value2"] } for exact match in a list
• { "$regex": "pattern" } for case-insensitive regular-expression match

Constraints:

• Only one operator per field (either $in or $regex), or a string value.
• Unsupported fields/operators are rejected with 400.

Response codes

Code	Description
201	Created
400	Bad Request
404	Not Found

Request example

[  {    "_name": "Asset Tools",    "_description": "Tools that target the Asset item service.",    "_userType": "asset_tools",    "_namespaces": ["building_1234"],    "_criteria": {      "_serviceName": { "$in": ["IafFileSvc","IafItemSvc"] },      "_name": "getFiles_IafFileSvc"    }  }]

Response example

{  "_offset": 0,  "_pageSize": 1,  "_total": 1,  "_list": [    {      "_id": "2f0f7b7e-2f7e-4c7d-a62b-8b8f8e0a2c0a",      "_name": "Asset Tools",      "_description": "Tools that target the Asset item service.",      "_userType": "asset_tools",      "_namespaces": ["building_1234"],      "_criteria": {        "_serviceName": { "$in": ["IafFileSvc", "IafItemSvc"] },        "_name": "getFiles_IafFileSvc"      },      "_metadata": {        "_createdAt": 1738100000000,        "_updatedAt": 1738100000000,        "_createdById": "user-123",        "_updatedById": "user-123"      },      "_irn": "irn:mcp_tool_filter:2f0f7b7e-2f7e-4c7d-a62b-8b8f8e0a2c0a"    }  ]}

Get MCP Tool Filter by ID

Endpoint

GET /aisvc/api/v1/mcptoolfilters/{id}

Path parameters

Parameter	Type	Description	Required
id	UUID	MCP tool filter 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": "2f0f7b7e-2f7e-4c7d-a62b-8b8f8e0a2c0a",  "_name": "Asset Tools (User)",  "_description": "Tools that target the Asset item service.",  "_userType": "asset_tools",  "_namespaces": ["building_1234"],  "_criteria": {    "_serviceName": { "$in": ["IafFileSvc", "IafItemSvc"] },    "_name": "getFiles_IafFileSvc"  },  "_metadata": {    "_createdAt": 1738100000000,    "_updatedAt": 1738100000000,    "_createdById": "user-123",    "_updatedById": "user-123"  },  "_irn": "irn:mcp_tool_filter:2f0f7b7e-2f7e-4c7d-a62b-8b8f8e0a2c0a"}

Update MCP Tool Filter

Endpoint

PUT /aisvc/api/v1/mcptoolfilters/{id}

Path parameters

Parameter	Type	Description	Required
id	UUID	MCP tool filter 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	Filter name (max 50 chars).Value must be unique.	Required
_description	String	Filter description .	Optional
_userType	String	Filter identifier (max 50 chars; must match ^\\w+$). Value must be unique.	Required
_criteria	Object	Tool-selection criteria (see _criteria format above).	Required

Response codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Delete MCP Tool Filter

Endpoint

DELETE /aisvc/api/v1/mcptoolfilters/{id}

Path parameters

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

Query parameters

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

Response codes

Code	Description
204	No Content (deleted)
400	Bad Request
404	Not Found

Response body

// empty response body