Version: v5.2

External MCP Server Config

Overview

Use the External MCP Server Config API to create, update, retrieve, and delete external MCP server configurations. With this REST API, you can do the following:

Create External MCP servers
Update External MCP servers
Get External MCP servers
Get External MCP servers by ID
Delete External MCP servers by ID

Using the namespace filter

Note: The nsfilter (namespace filter) query parameter is mandatory for every API request. It sets the context, helping you look up resources within that namespace.

Example:

GET /aisvc/api/v1/externalmcpserverconfigs?nsfilter=your_namespace

Create External MCP servers

Endpoint

POST /aisvc/api/v1/externalmcpserverconfigs

Request

Query parameters

Parameter	Type	Description	Required
`nsfilter`	String	Filter by namespace.	Required

Body parameters

Parameter	Type	Description	Required
`_name`	String	Name of the external MCP server.	Required
`_description`	String	Description of the external MCP server.	Optional
`_userType`	String	Unique identifier for the external MCP server config.	Required
`_namespaces`	Array of String	Namespaces that contain this configuration.	Required
`_connection`	Object	Connection configuration.	Required
`_connection._url`	String	MCP server URL (must be `http` or `https`).	Required
`_connection._headers`	Object	Optional request headers to send to the MCP server. Each key is a header name and its value is a header spec object.	Optional

The request body is an array of external MCP server configuration objects.

Header spec (`_connection._headers`)

Field	Type	Description	Required
`type`	String	How the header value is resolved. Allowed values: `secret` or `literal`.	Required
`value`	Any	Header value. For `secret`, provide a secret name/key to resolve. For `literal`, provide the literal header value.	Required

Body example

[
  { 
    "_name": "Github External MCP",
    "_description": "Github external MCP server",
    "_userType": "github_mcp",
    "_namespaces": ["{{nsfilter}}"],
    "_connection": {
      "_url": "https://api.githubcopilot.com/mcp/",
      "_headers": {
        "Authorization": { "type": "secret", "value": "GITHUB_TOKEN" },
        "X-Retry": { "type": "literal", "value": "3" }
      }
    } 
  }
]

Note: The _connection field is stored as a JSONB type, which allows flexible headers and values (for example, mixing secrets and literal values).

Body example (Twinit MCP)

[
  {
    "_name": "Twinit MCP",
    "_description": "Twinit MCP server",
    "_userType": "twin_mcp_demo2",
    "_namespaces": [
      "AWSA_mkF4p9l0"
    ],
    "_connection": {
      "_url": "https://dev1-api.in.invicara.com/aisvc/api/v1/stateless/mcp/tools?nsfilter=AWSA_mkF4p9l0",
      "_headers": {
        "Authorization": {
          "type": "secret",
          "value": "TWINIT_TOKEN"
        }
      }
    }
  }
]

Response codes

Code	Description
`200`	Success
`400`	Bad Request

Response data example

{
  "_offset": 0,
  "_pageSize": 1,
  "_total": 1,
  "_list": [
    {
      "_id": "b28d99f9-10d8-4a3c-8ef7-c196077dd6c6",
      "_name": "GitHub External MCP",
      "_description": "GitHub Copilot external MCP server",
      "_userType": "github_mcp",
      "_namespaces": [
        "{{nsfilter}}"
      ],
      "_transport": "http",
      "_connection": {
        "_url": "https://api.githubcopilot.com/mcp/",
        "_headers": {
            "Authorization": {
                "type": "secret",
                "value": "GITHUB_TOKEN"
            },
          "X-Retry": {
                "type": "literal",
                "value": "3"
            }
        }
      },
      "_irn": "aisvc:externalmcpserverconfig:b28d99f9-10d8-4a3c-8ef7-c196077dd6c6",
      "_metadata": {
        "_createdAt": "1762757209069",
        "_updatedById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
        "_createdById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
        "_updatedAt": "1762757209069"
      }
    }
  ]
}

Update External MCP servers

Endpoint

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

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	ID of the external MCP server config.	Required

Query parameters

Parameter	Type	Description	Required
`nsfilter`	String	Filter by namespace.	Required

Body parameters

Parameter	Type	Description	Required
`_name`	String	Name of the external MCP server.	Optional
`_description`	String	Description of the external MCP server.	Optional
`_userType`	String	Unique identifier for the external MCP server config.	Optional
`_namespaces`	Array of String	Namespaces that contain this configuration.	Optional
`_connection`	Object	Connection configuration.	Optional
`_connection._url`	String	MCP server URL (must be `http` or `https`).	Optional
`_connection._headers`	Object	Optional request headers to send to the MCP server. Each key is a header name and its value is a header spec object.	Optional

Pass the external MCP server configuration fields you want to update in the request body.

Body example

{
  "_name": "Github MCP (updated)",
  "_description": "Updated Github external MCP server description",
  "_userType": "github_mcp",
  "_namespaces": ["{{nsfilter}}"],
  "_connection": {
    "_url": "https://api.githubcopilot.com/mcp/",
    "_headers": {
      "Authorization": { "type": "secret", "value": "CONF_TOKEN" },
      "X-Retry": { "type": "literal", "value": "5" }
    }
  }
}

Note: The _connection field is stored as a JSONB type, which allows flexible header values.

Response codes

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

Response data example

{
  "_id": "b28d99f9-10d8-4a3c-8ef7-c196077dd6c6",
  "_name": "GitHub External MCP server (updated)",
  "_description": "Updated GitHub Copilot external MCP server",
  "_userType": "github_mcp",
  "_namespaces": [
    "{{nsfilter}}"
  ],
  "_transport": "http",
  "_connection": {
    "_url": "https://api.githubcopilot.com/mcp/",
    "_headers": {
      "X-Retry": {
        "type": "literal",
        "value": 5
      },
      "Authorization": {
        "type": "secret",
        "value": "GITHUB_TOKEN"
      }
    }
  },
  "_irn": "aisvc:externalmcpserverconfig:b28d99f9-10d8-4a3c-8ef7-c196077dd6c6",
  "_metadata": {
    "_createdAt": "1762757209069",
    "_updatedById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
    "_createdById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
    "_updatedAt": "1764325185618"
  }
}

Get External MCP servers

Endpoint

GET /aisvc/api/v1/externalmcpserverconfigs

Request

Query parameters

Parameter	Type	Description	Required
`nsfilter`	String	Filter by namespace.	Required
`_offset`	Number	Number of results to skip.	Optional
`_pageSize`	Number	Number of results per page.	Optional
`_userType`	String	Filter by the external MCP server config's unique `_userType` identifier.	Optional
`_name`	String	Filter by name.	Optional
`_transport`	String	Filter by transport (currently `http`).	Optional
`query`	String	Wildcard search on the name and description.	Optional

Response codes

Code	Description
`200`	Success
`400`	Bad Request

Response data example

{
    "_list": [
        {
            "_id": "80255215-1e82-4642-a929-17bdb0fdda07",
            "_name": "AWS MCP",
            "_description": "AWS external MCP server",
            "_userType": "aws1",
            "_namespaces": [
                "AWSP_ckF5p8l0"
            ],
            "_transport": "http",
            "_connection": {
                "_url": "https://knowledge-mcp.global.api.aws",
                "_headers": {
                    "Authorization": {
                        "type": "secret",
                        "value": "AWS_TOKEN"
                    }
                }
            },
            "_irn": "aisvc:externalmcpserverconfig:80255215-1e82-4642-a929-17bdb0fdda07",
            "_metadata": {
                "_createdAt": "1763113788717",
                "_updatedById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
                "_createdById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
                "_updatedAt": "1763113788717"
            }
        },
        {
            "_id": "b28d99f9-10d8-4a3c-8ef7-c196077dd6c6",
            "_name": "GitHub External MCP server",
            "_description": "GitHub Copilot external MCP server",
            "_userType": "github_mcp",
            "_namespaces": [
                "AWSP_ckF5p8l0"
            ],
            "_transport": "http",
            "_connection": {
                "_url": "https://api.githubcopilot.com/mcp/",
                "_headers": {
                    "X-Retry": {
                        "type": "literal",
                        "value": 3
                    },
                    "Authorization": {
                        "type": "secret",
                        "value": "GITHUB_TOKEN"
                    }
                }
            },
            "_irn": "aisvc:externalmcpserverconfig:b28d99f9-10d8-4a3c-8ef7-c196077dd6c6",
            "_metadata": {
                "_createdAt": "1762757209069",
                "_updatedById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
                "_createdById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
                "_updatedAt": "1764325185618"
            }
        }
    ],
    "_offset": 0,
    "_pageSize": 2,
    "_total": 2
}

Get External MCP servers by ID

Endpoint

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

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	ID of the external MCP server config.	Required

Query parameters

Parameter	Type	Description	Required
`nsfilter`	String	Filter by namespace.	Required

Response codes

Code	Description
`200`	Success
`404`	Not Found

Response data example

{
  "_id": "80255215-1e82-4642-a929-17bdb0fdda07",
  "_name": "AWS MCP",
  "_description": "AWS external MCP server",
  "_userType": "aws1",
  "_namespaces": [
    "AWSP_ckF5p8l0"
  ],
  "_transport": "http",
  "_connection": {
    "_url": "https://knowledge-mcp.global.api.aws",
    "_headers": {
      "Authorization": {
        "type": "secret",
        "value": "AWS_TOKEN"
      }
    }
  },
  "_irn": "aisvc:externalmcpserverconfig:80255215-1e82-4642-a929-17bdb0fdda07",
  "_metadata": {
    "_createdAt": "1763113788717",
    "_updatedById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
    "_createdById": "c51e2d85-6a2a-4a08-8c71-c4e995594ac0",
    "_updatedAt": "1763113788717"
  }
}

Delete External MCP servers by ID

Endpoint

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

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	ID of the external MCP server config.	Required

Query parameters

Parameter	Type	Description	Required
`nsfilter`	String	Filter by namespace.	Required

Response codes

Code	Description
`204`	Success
`404`	Not Found

Overview​

Using the namespace filter​

Create External MCP servers​

Endpoint​

Request​

Query parameters​

Body parameters​

Header spec (_connection._headers)​

Body example​

Body example (Twinit MCP)​

Response codes​

Response data example​

Update External MCP servers​

Endpoint​

Request​

Path parameters​

Query parameters​

Body parameters​

Body example​

Response codes​

Response data example​

Get External MCP servers​

Endpoint​

Request​

Query parameters​

Response codes​

Response data example​

Get External MCP servers by ID​

Endpoint​

Request​

Path parameters​

Query parameters​

Response codes​

Response data example​

Delete External MCP servers by ID​

Endpoint​

Request​

Path parameters​

Query parameters​

Response codes​

Overview

Using the namespace filter

Create External MCP servers

Endpoint

Request

Query parameters

Body parameters

Header spec (`_connection._headers`)

Body example

Body example (Twinit MCP)

Response codes

Response data example

Update External MCP servers

Endpoint

Request

Path parameters

Query parameters

Body parameters

Body example

Response codes

Response data example

Get External MCP servers

Endpoint

Request

Query parameters

Response codes

Response data example

Get External MCP servers by ID

Endpoint

Request

Path parameters

Query parameters

Response codes

Response data example

Delete External MCP servers by ID

Endpoint

Request

Path parameters

Query parameters

Response codes