Skip to main content
Version: v5.1

AI Service as MCP client

Overview#

The AI Service can connect directly to external MCP servers from an agent. This page describes what is involved in this process.

How the AI Service connects to MCP servers#

The ExternalMCPServerConfig is a first-class resource which has been introduced to the AI Service to facilitate connections to the MCP server.

Note: In the platform, a first-class resource is a resource which has a namespaces array, an IRN, and accessing these resources requires using permissions.

The AI service connects to an MCP server, using the ExternalMCPServerConfig as follows:

  1. Users create an ExternalMCPServerConfig with the connection details.
  2. Agents reference these configurations via _externalMcpServers.
  3. During execution, the LLM automatically invokes appropriate tools from the external MCP server using streamable-HTTP transport.
  4. When result are returned, they are passed back to the LLM to generate the final answer.

ExternalMCPServerConfig structure#

To see an example of the ExternalMCPServerConfig structure, refer to the sample below. 

{  "_name": "Weather MCP",  "_description": "Weather MCP server",  "_userType": "weather_mcp",  "_namespaces": ["bialt1u7_so1R3g0j"],  "_connection": {    "_url": "https://mcp.open-mcp.org/api/server/open-weather@latest/mcp",    "_headers": {      "Authorization": {        "type": "secret",        "value": "WEATHER_MCP_TOKEN"      },      "X-Retry": {        "type": "literal",        "value": "3"      }    }  }}

ExternalMCPServerConfig fields#

FieldsDescription
_urlMCP server endpoint
_headersCustom headers (literal or secret). Secrets are fetched from the Passport Service. Values are stored encrypted in database.
Default transportStreamable HTTP

Sample agent configuration#

Refer to the sample agent configuration below.

Note the use of the _externalMcpServers field which references the _userType of ExternalMCPServerConfig.

{  "_name": "Temperature Recommendations",  "_background": "Generates optimal temperature recommendations by combining aggregated indoor temperature readings with real-time weather information obtained from weather MCP tools",  "_userType": "temp_recommendations",  "_type": "user_agent",  "_namespaces": ["bialt1u7_so1R3g0j"],  "_config": {    "model": "gpt-4o",    "provider": "openai"  },  "_tools": ["AggregateReadingsTool"],  "_externalMcpServers": [    {      "_userType": "weather_mcp",      "_filter": {        "_names": [          "get_weather",          "get_weather_by_datetime_range"        ]      }    }  ]}

Notes on configuration fields#

Keep the following in mind:

  • _externalMcpServers references the _userType of ExternalMCPServerConfig.
  • _filter allows you to select specific MCP tools (also supports wildcards).
  • During execution, the LLM considers:
    • _knowledgebases
    • _tools
    • _externalMcpServers

Authorization#

The agent in the AI service acts as an MCP client. When it accesses an external MCP server, authorization headers are required. These headers are already defined in ExternalMCPServerConfig, which is referenced by the agent.