> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Create a Virtual MCP server

`POST /api/v1/mcp/configs`

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

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 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_mappings` | array of object | No | List of connection-to-tool mappings for this MCP config. Maximum 25 entries. |
| `connection_tool_mappings.connection_name` | string | Yes | Developer-assigned connection name. |
| `connection_tool_mappings.tools` | array of string | No | List of tool names linked to this connection (empty = all tools). |
| `description` | string | No | Description of the MCP configuration. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `config` | object | The created MCP configuration. |
| `config.connection_tool_mappings` | array of object | List of connection-to-tool mappings for this MCP config. Maximum 25 entries. |
| `config.connection_tool_mappings.connected_account_id` | string | Connected account backing this connection in the MCP instance context. |
| `config.connection_tool_mappings.connected_account_status` | string | Authentication status for the connected account. |
| `config.connection_tool_mappings.connection_id` | string | Unique ID of the connection. |
| `config.connection_tool_mappings.connection_name` | string | Developer-assigned connection name. |
| `config.connection_tool_mappings.provider` | string | Provider name for this connection. |
| `config.connection_tool_mappings.tools` | array of string | List of tool names linked to this connection (empty = all tools). |
| `config.description` | string | Description of the MCP configuration. |
| `config.id` | string | Unique ID of the MCP config. |
| `config.mcp_server_url` | string | The URL MCP clients connect to for this server. Every user and session shares it; the session token identifies the user. |
| `config.name` | string | Unique name for the MCP configuration. Must be 1–100 characters. Allowed characters: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_). |

**Errors**

- `400`: Invalid request - missing required fields or invalid connection/tool mappings
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "repo-assistant",
    "description": "Reads the user'\''s GitHub repositories and issues",
    "connection_tool_mappings": [
      {
        "connection_name": "github-connect",
        "tools": [
          "github_user_repos_list",
          "github_issues_list"
        ]
      }
    ]
  }'
```

**Response**

```json
{
  "config": {
    "id": "cfg_85630864460904897",
    "name": "repo-assistant",
    "description": "Reads the user's GitHub repositories and issues",
    "connection_tool_mappings": [
      {
        "connection_id": "conn_70219645518267719",
        "connection_name": "github-connect",
        "provider": "GITHUB",
        "tools": [
          "github_user_repos_list",
          "github_issues_list"
        ]
      }
    ],
    "mcp_server_url": "https://your-env.scalekit.dev/mcp/v3/servers/3d9f6a2e-7b41-4c8e-a5d2-0f1e8b6c4a93"
  }
}
```

**Python SDK:** `scalekit_client.actions.mcp.create_config`

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

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

Example:

```python
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"],
        ),
    ],
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `str` | Yes | Human readable name for the configuration. |
| `description` | `Optional[str]` | No | Summary that surfaces in dashboards and APIs. |
| `connection_tool_mappings` | `Optional[List[McpConfigConnectionToolMapping]]` | No | Explicit mapping between connectors and tools. |

Returns `CreateMcpConfigResponse`: The created configuration payload.

**Node.js SDK:** `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.

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

Example:

```ts
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"],
    },
  ],
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Unique name. 1-100 characters, lowercase letters, digits, hyphens and underscores. |
| `description` | `string` | No | Human-readable summary of what this server exposes. |
| `connectionToolMappings` | `MessageInitShape<typeof McpConfigSchema>['connectionToolMappings']` | No | 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>`.

**Used in**

- [Claude Managed Agents](https://docs.scalekit.com/agentkit/examples/claude-managed-agents/)
- [Create a Virtual MCP server](https://docs.scalekit.com/agentkit/mcp/configure-mcp-server/)
- [Mastra](https://docs.scalekit.com/agentkit/examples/mastra/)


Part of [Virtual MCP servers](https://docs.scalekit.com/agentkit/reference/virtual-mcp-servers/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |