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 connections in DIRECT mode.

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

tool_exposurestring (enum)

How the server exposes tools to agents. DIRECT lists every tool you map to it, for up to 25 connections. META gives agents five tools to search for, inspect and run the mapped tools, with no limit on connections. DIRECT is the default when you create a server without it.

DIRECTMETA

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,
    tool_exposure: Optional[str] = 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.

tool_exposureOptional[str]

How the server exposes tools to agents. DIRECT lists every tool you map to the server, for up to 25 connections. META gives agents five tools, search_available_tools, list_available_tools, get_tool_details, execute_tool and connect_account, to find and run the mapped tools, with no connection limit. Defaults to DIRECT.

Returns CreateMcpConfigResponse: The created configuration payload.

From scalekit-sdk-python 2.22.0.

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'];
    toolExposure?: McpToolExposure;
  },
): 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 connections when toolExposure is 'DIRECT'.

toolExposureMcpToolExposure

Returns Promise<CreateMcpConfigResponse>.

From @scalekit-sdk/node 2.21.0.

Response 200

configobject

The created MCP configuration

Show 6 child attributes

connection_tool_mappingsarray of object

List of connection-to-tool mappings for this MCP config. Maximum 25 connections in DIRECT mode.

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 (_).

tool_exposurestring (enum)

DIRECTMETA

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
    "tool_exposure": "DIRECT"
18
  }'

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"],
        ),
    ],
    tool_exposure="DIRECT",
)

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"],
    },
  ],
  toolExposure: "DIRECT",
});

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
    "tool_exposure": "DIRECT"
19
  }
20
}