Create a Virtual MCP server

POST/api/v1/mcp/configs

Creates a new MCP configuration with a set of connections and tools.

This page as markdown Virtual MCP servers overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Body

namestringrequired

Unique name for the MCP configuration. Must be 1–100 characters. Allowed characters: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_).

connection_tool_mappingsarray of object

List of connection-to-tool mappings for this MCP config. Maximum 25 entries.

Show 2 child attributes

connection_namestringrequired

Developer-assigned connection name

toolsarray of string

List of tool names linked to this connection (empty = all tools)

descriptionstring

Description of the MCP configuration

scalekit_client.actions.mcp.create_config

Create a new MCP configuration from the supplied metadata and tool mappings.

scalekit_client.actions.mcp.create_config(
    name: str,
    description: Optional[str] = None,
    connection_tool_mappings: Optional[List[McpConfigConnectionToolMapping]] = None,
) -> CreateMcpConfigResponse

Parameters

namestrrequired

Human readable name for the configuration.

descriptionOptional[str]

Summary that surfaces in dashboards and APIs.

connection_tool_mappingsOptional[List[McpConfigConnectionToolMapping]]

Explicit mapping between connectors and tools.

Returns CreateMcpConfigResponse: The created configuration payload.

From scalekit-sdk-python 2.19.1.

scalekit.actions.mcp.createConfig

Creates a Virtual MCP server configuration. Create this once per agent role. The response carries a static config.mcpServerUrl that every user and every session reuses.

scalekit.actions.mcp.createConfig(
  params: {
    name: string;
    description?: string;
    connectionToolMappings?: MessageInitShape<typeof McpConfigSchema>['connectionToolMappings'];
  },
): Promise<CreateMcpConfigResponse>

Parameters

namestringrequired

Unique name. 1-100 characters, lowercase letters, digits, hyphens and underscores.

descriptionstring

Human-readable summary of what this server exposes.

connectionToolMappingsMessageInitShape<typeof McpConfigSchema>['connectionToolMappings']

Which connections, and which tools from each, to expose. Omit tools on a mapping to expose every tool for that connection. Maximum 25 mappings.

Returns Promise<CreateMcpConfigResponse>.

From @scalekit-sdk/node 2.18.0.

Response 200

configobject

The created MCP configuration

Show 5 child attributes

connection_tool_mappingsarray of object

List of connection-to-tool mappings for this MCP config. Maximum 25 entries.

Show 6 child attributes

connected_account_idstring

Connected account backing this connection in the MCP instance context

connected_account_statusstring

Authentication status for the connected account

connection_idstring

Unique ID of the connection

connection_namestring

Developer-assigned connection name

providerstring

Provider name for this connection

toolsarray of string

List of tool names linked to this connection (empty = all tools)

descriptionstring

Description of the MCP configuration

idstring

Unique ID of the MCP config

mcp_server_urlstring

The URL MCP clients connect to for this server. Every user and session shares it; the session token identifies the user.

namestring

Unique name for the MCP configuration. Must be 1–100 characters. Allowed characters: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_).

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - missing required fields or invalid connection/tool mappings

401Authentication required - missing or invalid access token

Used in

Request

1
curl -sS -X POST \
2
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs" \
3
  -H "Authorization: Bearer $TOKEN" \
4
  -H "Content-Type: application/json" \
5
  -d '{
6
    "name": "repo-assistant",
7
    "description": "Reads the user'\''s GitHub repositories and issues",
8
    "connection_tool_mappings": [
9
      {
10
        "connection_name": "github-connect",
11
        "tools": [
12
          "github_user_repos_list",
13
          "github_issues_list"
14
        ]
15
      }
16
    ]
17
  }'

from scalekit.actions.types import McpConfigConnectionToolMapping

result = scalekit_client.actions.mcp.create_config(
    name="repo-assistant",
    description="Reads the user's GitHub repositories and issues",
    connection_tool_mappings=[
        McpConfigConnectionToolMapping(
            connection_name="github-connect",
            tools=["github_user_repos_list", "github_issues_list"],
        ),
    ],
)

const result = await scalekit.actions.mcp.createConfig({
  name: "repo-assistant",
  description: "Reads the user's GitHub repositories and issues",
  connectionToolMappings: [
    {
      connectionName: "github-connect",
      tools: ["github_user_repos_list", "github_issues_list"],
    },
  ],
});

Response 200

1
{
2
  "config": {
3
    "id": "cfg_85630864460904897",
4
    "name": "repo-assistant",
5
    "description": "Reads the user's GitHub repositories and issues",
6
    "connection_tool_mappings": [
7
      {
8
        "connection_id": "conn_70219645518267719",
9
        "connection_name": "github-connect",
10
        "provider": "GITHUB",
11
        "tools": [
12
          "github_user_repos_list",
13
          "github_issues_list"
14
        ]
15
      }
16
    ],
17
    "mcp_server_url": "https://your-env.scalekit.dev/mcp/v3/servers/3d9f6a2e-7b41-4c8e-a5d2-0f1e8b6c4a93"
18
  }
19
}