Mastra

Connect a Mastra agent to Scalekit tools using MCP. Mastra has native MCP support via @mastra/mcp. Pass a Scalekit Virtual MCP Server URL and a session token, and Mastra handles tool discovery automatically.

Why MCP for Mastra

Mastra’s tool system uses Zod schemas internally. The MCP path skips manual schema conversion. Mastra discovers tools and their schemas directly from the Scalekit MCP server.

Install

npm install @scalekit-sdk/node @mastra/core @mastra/mcp @ai-sdk/openai

Create the Virtual MCP server

Create the server once per agent role, not once per user. The response includes a static mcp_server_url that every user and every session reuses.

# Backend (Python): run once, then save the values
from scalekit.actions.models.mcp_config import McpConfigConnectionToolMapping

vmcp_response = scalekit_client.actions.mcp.create_config(
    name="gmail-user-tools",
    connection_tool_mappings=[
        McpConfigConnectionToolMapping(
            connection_name="gmail",
            tools=["gmail_fetch_mails"],
        ),
    ],
)

config_id = vmcp_response.config.id
mcp_server_url = vmcp_response.config.mcp_server_url

See Set up and connect a Virtual MCP server for the full setup, including how to choose which tools to expose.

Mint a session token for the user

The server URL is static. The session token carries the user identity. Mint a fresh token before each agent run and pass it to your Mastra app.

# Backend (Python): run before each agent session
from datetime import timedelta

from scalekit.common.exceptions import (
    ScalekitNotFoundException,
    ScalekitUnauthorizedException,
    ScalekitServerException,
)

try:
    list_response = scalekit_client.actions.mcp.list_configs(filter_name="gmail-user-tools")
    mcp_server_url = list_response.configs[0].mcp_server_url
    config_id = list_response.configs[0].id

    token_response = scalekit_client.actions.mcp.create_session_token(
        mcp_config_id=config_id,
        identifier="user_123",
        expiry=timedelta(hours=1),
    )
    # Return mcp_server_url and token_response.token to the Mastra app for this user only
except ScalekitNotFoundException:
    # The server was deleted or renamed — recreate it, then retry
    raise
except ScalekitUnauthorizedException:
    # Scalekit client credentials are wrong or expired — fix the environment variables
    raise
except ScalekitServerException as e:
    # Unexpected platform error — do not start the agent without a token
    print(e.error_code, e.http_status)
    raise

Do not start the agent when minting fails. An agent that runs without a token calls every tool and gets a 401. See Error handling for the full exception list.

Set expiry longer than the expected agent run. create_session_token also mints replacements. Call it again whenever you need a new token.

Do not share one session token across users

The mcp_server_url is safe to share, because every user gets the same URL. The session token is different. Each token is scoped to one identifier, and any request carrying that token runs as that user. Mint a token per user on the server, and never put a token in client-side code.

Build the agent

Pass the static server URL to MCPClient, and the user’s session token as a bearer header in requestInit. Mastra fetches the tool list and schemas automatically:

import { Agent } from '@mastra/core/agent';
import { MCPClient } from '@mastra/mcp';
import { openai } from '@ai-sdk/openai';

// From your backend for the authenticated user — not a shared process-wide secret
const { mcpServerUrl, mcpToken } = await getMcpSessionForUser(currentUserId);

const mcp = new MCPClient({
  servers: {
    scalekit: {
      url: new URL(mcpServerUrl),
      requestInit: {
        headers: { Authorization: `Bearer ${mcpToken}` },
      },
    },
  },
});

const tools = await mcp.getTools();

const agent = new Agent({
  name: 'gmail_assistant',
  instructions: 'You are a helpful Gmail assistant.',
  model: openai('gpt-4o'),
  tools,
});

const result = await agent.generate('Fetch my last 5 unread emails and summarize them');
console.log(result.text);

await mcp.disconnect();