Create a Virtual MCP server

Create one Virtual MCP server for each agent role. It lists the connections and tools the agent can use, and gives you a fixed URL that every user of that agent shares. You do this once, not once per user.

• A connection for each app the agent needs, in AgentKit > Connections. Set up a connection if you haven’t. These examples use github-connect, the GitHub connection new environments include.

• A client set up as in the Quickstart: actions in Python, scalekit in Node.js. For cURL, get an access token and keep it in TOKEN:

  TOKEN=$(curl -sS "$SCALEKIT_ENVIRONMENT_URL/oauth/token" \
    -d grant_type=client_credentials \
    -d client_id="$SCALEKIT_CLIENT_ID" \
    -d client_secret="$SCALEKIT_CLIENT_SECRET" | jq -r .access_token)

1. Choose the tools

   Section titled “Choose the tools”

   Pick the smallest set of tools the agent needs. Get exact names from tool search or the scoped tool list, or from each connector’s page in the connector catalog.

   If you leave out tools for a connection, the server gets every tool that connection has when you create it. Tools added to the connector later aren’t included.

2. Create the server

   Section titled “Create the server”

   Give the server a name that’s unique in the environment, and list the tools for each connection.

   • Python
   • Node.js
   • cURL

   from scalekit.actions.models.mcp_config import McpConfigConnectionToolMapping
   
   response = 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"],
           ),
       ],
   )
   config_id = response.config.id
   mcp_server_url = response.config.mcp_server_url
   print(config_id, mcp_server_url)

3. Save the ID and URL

   Section titled “Save the ID and URL”

   Store the server’s id and mcp_server_url in your configuration. You pass the ID when you mint session tokens, and the URL to your agent. For cURL, keep them in CONFIG_ID and MCP_SERVER_URL.

List servers by name to see the new server and its URL:

response = actions.mcp.list_configs(filter_name="repo-assistant")
for config in response.configs:
    print(config.id, config.name, config.mcp_server_url)

const { configs } = await scalekit.actions.mcp.listConfigs({ search: 'repo-assistant' });
for (const c of configs) console.log(c.id, c.name, c.mcpServerUrl);

curl -sS -G "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "filter.name=repo-assistant" |
  jq '.configs[] | {id, name, mcp_server_url}'

Then mint a session token and list the server’s tools from an MCP client.

To change the tools, send the full list for each connection. It replaces the old list.

actions.mcp.update_config(
    config_id=config_id,
    connection_tool_mappings=[
        McpConfigConnectionToolMapping(
            connection_name="github-connect",
            tools=["github_user_repos_list", "github_issues_list", "github_issue_get"],
        ),
    ],
)

await scalekit.actions.mcp.updateConfig({
  configId,
  connectionToolMappings: [
    {
      connectionName: 'github-connect',
      tools: ['github_user_repos_list', 'github_issues_list', 'github_issue_get'],
    },
  ],
});

curl -sS -X PUT "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs/$CONFIG_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_tool_mappings": [
      {"connection_name": "github-connect", "tools": ["github_user_repos_list", "github_issues_list", "github_issue_get"]}
    ]
  }' |
  jq '.config.connection_tool_mappings'

Change a server when no agent run is using it, because a run can lose a tool mid-conversation. For a larger change, create a new server and point your agent at its URL.

Deleting a server stops its URL from working immediately, including for session tokens already minted.

actions.mcp.delete_config(config_id=config_id)

await scalekit.actions.mcp.deleteConfig(configId);

curl -sS -X DELETE "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs/$CONFIG_ID" \
  -H "Authorization: Bearer $TOKEN"

The tool name doesn’t exist on that connection. Copy names from tool search or the scoped tool list.

The connection name doesn’t match AgentKit > Connections exactly.

Server names are unique in an environment. Choose another name, or update the existing server.