Skip to main content
Version: v5.2

Using Custom and System MCP Tools in Workflows

Overview​

Introduced in Platform version 5.2, an agent can now use MCP Tools directly by simply listing their names in the agent's _tools array. There is no need to configure the MCP Server, as was previously required. This page describes how to achieve this.

Mixing normal and MCP tools​

The _tools array can now mix normal (system or script) Tools and MCP Tools freely. During agent or team execution, the AI Service resolves every name and binds the name to the matching Tool. This simplifies agent configuration and improves usability through direct Tool-level integration.

Note: Tool names are kept unique across both the Tool and MCP Tool registries (within overlapping or global namespaces) by a database trigger. This means that a name listed in the _tools array always resolves to exactly one Tool.

How it works​

This new approach for using Custom and System MCP Tools works as follows:

  1. An agent lists Tool names directly in the _tools array. Normal Tools and MCP tools can be listed together.
  2. When the Team is run, the AI Service collects the requested names and looks them up in the Tool and MCP Tool registries. The AI Service then binds each name to the agent (System and User and Custom MCP tools are all supported).
  3. An entry is not required in _externalMcpServers for MCP tools which are referenced in this way.

Example _tools array​

No MCP Server configuration is required. You can now simply list MCP Tools directly in the _tools array as shown below.

{
  "_name": "Platform Ops Agent",
  "_userType": "platform_ops_agent",
  "_type": "user_agent",
  "_namespaces": ["building_1234"],
  "_config": { "_provider": "openai", "_model": "gpt-4o", "_temperature": 0 },
  "_background": "Answer questions across files, items, projects and workflows.",
  "_tools": [
    "GetAssetsTool",                 // normal / system tool
    "getFiles_IafFileSvc",           // MCP tool
    "getFileVersions_IafFileSvc",    // MCP tool
    "getNamedUserItems_IafItemSvc",  // MCP tool
    "getProjects_IafProj",           // MCP tool
    "getWorkflows_IafWorkflowSvc"    // MCP tool
  ]
}

Note: GetAssetsTool is a normal Tool. The *_Iaf* entries are MCP Tools served by the AISvc MCP Server. All are referenced by name with no _externalMcpServers entry.

Notes on uniqueness of Tool names​

A Tool name must be unique across both the Tool registry and the MCP Tool registry within overlapping global namespaces. This ensures that _tools references are never ambiguous. This is enforced by a database trigger and surfaced as a clear HTTP error on both creation paths.

Notes on creating a normal Tool​

If you attempt to create a normal Tool whose user_type, name, or tool_class conflicts with an existing MCP Tool name then you will get a 409 Conflict.

POST {{url}}/aisvc/api/v1/tools?_pageSize=100&nsfilter={{namespace}}

Notes on creating a MCP Tool​

If you attempt to create a MCP Tool whose name collides with an existing Tool's user_type, name, or tool_class then you will also get a 409 Conflict.

POST {{url}}/aisvc/api/v1/mcp-tools?nsfilter={{namespace}}

Notes on acceptance criteria​

Note the following acceptance criteria:

  • Agents can reference and use Custom MCP Tools directly without defining the Twinit MCP Server.
  • The system returns a 400 Bad Request error when an invalid Custom MCP Tool is provided or when the referenced Tool does not exist.
  • Custom MCP Tools are supported during Team execution workflows.
  • Existing MCP Server-based integrations continue to work without regression.
  • Proper validation and error messaging are displayed for unsupported or unauthorized Tool usage.
  • _tools can contain both normal Tools and MCP Tools in the same array; all are resolved, bound, and execute correctly.
  • Creating a normal Tool with a user_type, name, or tool_class that duplicates an existing Tool or MCP Tool (overlapping namespaces) results in a 409 error (422 error for same-namespace duplicate) with a clear message; "The tool is not created."
  • Creating an MCP Tool with a name that duplicates an existing MCP Tool or a Tool's user_type, name, or tool_class results in a 409 error (422 error for same-namespace duplicate) with a clear message; "The MCP tool is not created."
  • Because duplicates are blocked at creation, a _tools reference resolves to exactly one tool. If a duplicate or ambiguous definition is present, the agent run will fail with a clear error rather than binding the wrong tool.
  • The caller must have the required permission on every tool which the agent references. This includes both normal Tools and MCP Tools. If permission for any referenced tool is missing, the request will fail and provide a clear authorization error (403) rather than silently skipping the Tool.