Version: v5.1

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#

Header spec (`_connection._headers`)#