Claude Managed Agents

Run a background agent that reads Gmail and creates Google Calendar events — without managing any agent loop. Anthropic handles tool discovery, execution, retries, and session state. You provide the task.

Scalekit connects the agent to user-authorized tools via a Virtual MCP server. Before each run, you mint a short-lived session token and store it in that user’s own Anthropic vault. The agent accesses the MCP server using the vault credential.

• Create Gmail and Google Calendar connections in AgentKit > Connections. The samples use the connection names gmail and googlecalendar, so change them if yours differ. See Set up a connection.
• Have the .env file from the Quickstart, and add to it your Anthropic API key with access to the Managed Agents beta as ANTHROPIC_API_KEY, and your Anthropic environment ID as ANTHROPIC_ENVIRONMENT_ID.
• The samples load .env with load_dotenv() from python-dotenv.

The flow has three phases:

1. Build (one-time) — Create a Virtual MCP server and a Claude Managed Agent. Save mcp_id and agent_id.
2. Authorize user for external connections (once per user) — Authorize the user’s Gmail and Google Calendar accounts.
3. Run a session (per agent run) — Check connections, mint a session token, store it in that user’s own Anthropic vault, and start a session. Never share one vault across users: a session acts as whichever user’s token is in its vault.

pip install anthropic scalekit-sdk-python python-dotenv

Run this once to create your Virtual MCP server and Claude Managed Agent. Save the returned mcp_id and agent_id — you reuse them for every user and every session.

1
import os
2
import anthropic
3
from scalekit import ScalekitClient
4
from scalekit.actions.models.mcp_config import McpConfigConnectionToolMapping
5
from dotenv import load_dotenv
6

7
load_dotenv()
8

9
anthropic_client = anthropic.Anthropic()
10
scalekit_client = ScalekitClient(
11
    env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
12
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
13
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
14
)
15

16
GMAIL_TOOLS = ["gmail_fetch_mails"]
17
GCAL_TOOLS = [
18
    "googlecalendar_list_calendars",
19
    "googlecalendar_list_events",
20
    "googlecalendar_get_event_by_id",
21
    "googlecalendar_create_event",
22
    "googlecalendar_update_event",
23
]
24

25
vmcp_response = scalekit_client.actions.mcp.create_config(
26
    name="email-calendar-demo",
27
    connection_tool_mappings=[
28
        McpConfigConnectionToolMapping(
29
            connection_name="gmail",
30
            tools=GMAIL_TOOLS,
31
        ),
32
        McpConfigConnectionToolMapping(
33
            connection_name="googlecalendar",
34
            tools=GCAL_TOOLS,
35
        ),
36
    ],
37
)
38

39
mcp_id = vmcp_response.config.id
40
mcp_server_url = vmcp_response.config.mcp_server_url
41

42
agent = anthropic_client.beta.agents.create(
43
    name="Email Meeting Manager",
44
    model="claude-haiku-4-5",
45
    system=(
46
        "You are an email and calendar assistant. When invoked, you will:\n"
47
        "1. Fetch the single most recent unread email from Gmail.\n"
48
        "2. Summarize it in 2-3 sentences.\n"
49
        "3. Create a Google Calendar event titled 'Action Required: <email subject>' "
50
        "with your summary as the description."
51
    ),
52
    mcp_servers=[
53
        {
54
            "type": "url",
55
            "name": "email-calendar-mcp",
56
            "url": mcp_server_url,
57
        }
58
    ],
59
    tools=[
60
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
61
        {
62
            "type": "mcp_toolset",
63
            "mcp_server_name": "email-calendar-mcp",
64
            "default_config": {
65
                "enabled": True,
66
                "permission_policy": {"type": "always_allow"},
67
            },
68
        },
69
    ],
70
)
71

72
print("Add these to your .env file:")
73
print(f"SCALEKIT_MCP_CONFIG_ID={mcp_id}")
74
print(f"ANTHROPIC_AGENT_ID={agent.id}")

Run python builder.py once and add the two printed lines to your .env file. The next two scripts read them from there.

The agent definition references the mcp_server_url but carries no auth credentials. Authentication is injected at runtime via the Anthropic vault.

Each user authorizes their Gmail and Google Calendar accounts once. All future agent sessions for that user reuse those connections.

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4

5
load_dotenv()
6

7
scalekit_client = ScalekitClient(
8
    env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
9
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
10
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
11
)
12

13
mcp_id = os.environ["SCALEKIT_MCP_CONFIG_ID"]  # printed by builder.py
14
identifier = "user_123"  # your app's unique user ID
15

16
accounts_response = scalekit_client.actions.mcp.list_mcp_connected_accounts(
17
    config_id=mcp_id,
18
    identifier=identifier,
19
)
20

21
for account in accounts_response.connected_accounts:
22
    status = (account.connected_account_status or "").upper()
23
    if status != "ACTIVE":
24
        auth_response = scalekit_client.actions.get_authorization_link(
25
            identifier=identifier,
26
            connection_name=account.connection_name,
27
        )
28
        print(f"{account.connection_name} needs auth: {auth_response.link}")
29
    else:
30
        print(f"✓ {account.connection_name} is ACTIVE")

Surface the auth link in your app UI or send it via email. Users only need to do this once.

Run executor.py for each agent run. It stops before starting a session if any connection isn’t ACTIVE, so the agent never runs with a tool it can’t call.

1. Set up the clients and the run

   Section titled “Set up the clients and the run”

   1
   import json
   2
   import os
   3
   import sys
   4
   from datetime import timedelta
   5
   from pathlib import Path
   6
   
   7
   import anthropic
   8
   from dotenv import load_dotenv
   9
   from scalekit import ScalekitClient
   10
   
   11
   load_dotenv()
   12
   
   13
   anthropic_client = anthropic.Anthropic()
   14
   scalekit_client = ScalekitClient(
   15
       env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
   16
       client_id=os.environ["SCALEKIT_CLIENT_ID"],
   17
       client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
   18
   )
   19
   
   20
   mcp_id = os.environ["SCALEKIT_MCP_CONFIG_ID"]  # printed by builder.py
   21
   agent_id = os.environ["ANTHROPIC_AGENT_ID"]  # printed by builder.py
   22
   identifier = "user_123"  # your app's unique user ID
   23
   prompt = "Process my most recent unread email."
   24
   
   25
   # Each user gets their own vault, created on their first run.
   26
   # This example keeps the IDs in a local file. In production, store them
   27
   # in your database, keyed by the user.
   28
   VAULTS_FILE = Path("vaults.json")
   29
   vaults = json.loads(VAULTS_FILE.read_text()) if VAULTS_FILE.exists() else {}
   30
   user_vault = vaults.get(identifier)

2. Check that connections are active

   Section titled “Check that connections are active”

   OAuth tokens for connected accounts can expire or be revoked, so check every connection before minting a token. If any isn’t ACTIVE, stop and send the user back through executor_setup.py.

   accounts_response = scalekit_client.actions.mcp.list_mcp_connected_accounts(
       config_id=mcp_id,
       identifier=identifier,
   )
   inactive = [
       a.connection_name
       for a in accounts_response.connected_accounts
       if (a.connected_account_status or "").upper() != "ACTIVE"
   ]
   if inactive:
       sys.exit(f"Not ACTIVE: {', '.join(inactive)}. Run executor_setup.py to reauthorize.")

3. Mint a session token and store it in the vault

   Section titled “Mint a session token and store it in the vault”

   Mint a short-lived session token and store it in this user’s Anthropic vault. Claude Managed Agents access the MCP server using the vault credential, not a direct bearer header, and the session acts as whichever user’s token is in the vault. So give each user their own vault, and never put two users’ tokens in the same one.

   1
   configs_response = scalekit_client.actions.mcp.list_configs(filter_id=mcp_id)
   2
   mcp_server_url = configs_response.configs[0].mcp_server_url
   3
   
   4
   token_response = scalekit_client.actions.mcp.create_session_token(
   5
       mcp_config_id=mcp_id,
   6
       identifier=identifier,
   7
       expiry=timedelta(hours=1),
   8
   )
   9
   token = token_response.token
   10
   
   11
   # Update this user's own credential, or create their vault on their first run.
   12
   # Never reuse one vault across users: a session acts as whoever's token is in it.
   13
   if user_vault:
   14
       vault_id = user_vault["vault_id"]
   15
       anthropic_client.beta.vaults.credentials.update(
   16
           user_vault["credential_id"],
   17
           vault_id=vault_id,
   18
           auth={"type": "static_bearer", "token": token},
   19
       )
   20
   else:
   21
       vault = anthropic_client.beta.vaults.create(display_name=f"email-calendar-{identifier}")
   22
       vault_id = vault.id
   23
       credential = anthropic_client.beta.vaults.credentials.create(
   24
           vault_id,
   25
           display_name="email-calendar-credential",
   26
           auth={
   27
               "type": "static_bearer",
   28
               "mcp_server_url": mcp_server_url,
   29
               "token": token,
   30
           },
   31
       )
   32
       vaults[identifier] = {"vault_id": vault_id, "credential_id": credential.id}
   33
       VAULTS_FILE.write_text(json.dumps(vaults, indent=2))

4. Start the session

   Section titled “Start the session”

   Pass vault_ids to the session so the agent can authenticate against the MCP server.

   1
   session = anthropic_client.beta.sessions.create(
   2
       agent=agent_id,
   3
       environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
   4
       vault_ids=[vault_id],
   5
   )
   6
   
   7
   with anthropic_client.beta.sessions.events.stream(session_id=session.id) as stream:
   8
       anthropic_client.beta.sessions.events.send(
   9
           session_id=session.id,
   10
           events=[{"type": "user.message", "content": [{"type": "text", "text": prompt}]}],
   11
       )
   12
       for event in stream:
   13
           if event.type == "agent.message":
   14
               for block in event.content:
   15
                   if block.type == "text":
   16
                       print(block.text, end="", flush=True)
   17
           elif event.type == "agent.mcp_tool_use":
   18
               print(f"\n→ {event.name}", flush=True)
   19
           elif event.type == "session.status_terminated":
   20
               break
   21
           elif event.type == "session.status_idle":
   22
               # The session also goes idle while it waits on you (requires_action).
   23
               # Stop only when it's idle for another reason, such as end_turn.
   24
               if event.stop_reason.type != "requires_action":
   25
                   break