Build an email-to-meeting scheduling Outlook agent using Claude Agent SDK

TL;DR

• An email thread is attacker-controlled input. Anyone who knows your user's address can put text in the agent's context, which means the trigger surface of an email-to-meeting agent is also its attack surface.
• Per-user identity binding and a scoped tool surface are necessary and not sufficient here. ^{list_scoped_tools} controls which tools exist and ^execute_tool controls whose token runs them; neither controls the values the model passes, and attendee lists, timezones, and event bodies are all values.
• The Outlook connector exposes 126 tools. A scheduling agent needs 7. At roughly 200 tokens per tool definition that is about 25,200 tokens of surface reduced to about 1,400, and ^{outlook_send_message}, ^{outlook_forward_message}, ^{outlook_create_message_rule}, and ^{outlook_create_calendar_permission} are deliberately unreachable.
• In the Claude Agent SDK the argument gate must be a ^PreToolUse hook, not ^can_use_tool. Hooks run before every other step in the permission flow, while a tool auto-approved by an ^{allowed_tools} entry never reaches ^can_use_tool at all, and ^{permission_mode="dontAsk"} skips the callback entirely.
• Scalekit AgentKit supplies the identity gate and the surface gate, plus a per-tool audit record (^{result.execution_id}) tying every Outlook read and write back to the user who authorized it; the argument gate is code you own, and it runs on facts your code fetched rather than facts the model inferred.

A scheduling thread lands in a user's Outlook inbox. Four people, two proposed windows, one line at the bottom of a forwarded quote that reads like boilerplate. The agent reads the thread, checks the calendar, and creates a 45-minute event with a Teams link. The subject is right. The time is right. There are five attendees.

Nothing threw. The run was green. The Outlook audit log shows the event was created by the user, because it was: the token was correct, the scope was correct, the tenant was correct. The authorization model did exactly what it was told. The instruction just came from the wrong author.

Which half of this agent is allowed to reason

The job splits cleanly, and the split is the design.

Interpretation is a reasoning problem. Free-text scheduling requests are irregular: "sometime Thursday after standup," "the 2pm slot Priya suggested, but move it 30 min," "same time next week, add Marcus." Extracting intent, candidate windows, duration, and the attendee set from a thread of replies and quoted replies is exactly what a reasoning loop is good at. The Claude Agent SDK gives you that loop directly.

The mutation is not a reasoning problem. ^{outlook_create_calendar_event} sends invitations to real mailboxes. In a reasoning loop, Claude picks the next tool call and its arguments from whatever is in context, and the thread is in context. That makes every argument on the write call a value an outsider can influence.

Scalekit's earlier Gmail to Calendar scheduling build was a deterministic pipeline: fixed steps, fixed order, no model choosing what happens next. This build keeps the reasoning loop for interpretation and puts a deterministic gate in front of the write. The agent proposes; your code decides what may be created.

Per run, for one user:

• Read the target thread and its replies from that user's mailbox.
• Resolve the participant set from message headers, not from prose.
• Read the user's own calendar window and the free/busy of attendees who have granted visibility.
• Propose a slot, a duration, an attendee list, and a timezone.
• Create exactly one event, with a Teams link, after the gate approves the arguments.

What the user cannot do in Outlook, the agent must not be able to do. And what the thread author can ask for must stay strictly smaller than what the user could do.

Where the Claude Agent SDK's tool model stops

The SDK's tool primitive is ^{create_sdk_mcp_server}: define handlers with the ^@tool decorator, bundle them into an in-process MCP server, hand it to the agent. Clean model, single-user defaults.

The last two rows are the ones this build turns on. Rows one to three are the single-tenant-to-multi-tenant conversion covered in the deal-risk agent build; an inbound email trigger adds the argument problem on top.

Prerequisites

• Python 3.10 or newer, and ^{pip install claude-agent-sdk scalekit-sdk-python protobuf python-dotenv}. Install ^protobuf explicitly on clean virtualenvs.
• An ^{ANTHROPIC_API_KEY}. The Python SDK drives the Claude Code runtime underneath.
• One Outlook connection created under AgentKit > Connections in the Scalekit dashboard, backed by your own Azure app registration. Under Supported account types choose accounts in any organizational directory and personal Microsoft accounts, and paste Scalekit's generated redirect URI as a Web redirect.
• Delegated Graph scopes on the connection: ^Mail.Read, ^{Calendars.ReadWrite}, ^User.Read, ^{offline_access}. ^Mail.Send is not on this list and should not be; the agent has no reason to send mail.
• The ^{connection_name} in your code must match the dashboard connection name exactly, suffix included. A mismatch routes to the wrong connection or returns not-found, and it is the most common integration failure.

One multi-tenant reality to plan for before writing code: a single multitenant app registration does not mean a single consent state. Tenants can disable user consent, in which case the first user from that customer gets ^AADSTS65001 (^{DelegationDoesNotExist}) or ^AADSTS90094 (^{AdminConsentRequired}) instead of a token, and someone with admin rights in their directory has to approve your app once. Treat per-tenant consent as an onboarding step with its own state, not an error to retry.

Resolve the acting identity and its tenant

Before any tool exists, the run needs to know which user it acts for and which customer organization that user belongs to. Both values are inputs to everything downstream.

^{get_or_create_connected_account} is idempotent: the first call creates the per-user record, later calls return it with current status. ^{organization_id} binds the account to a tenant, which is what keeps two customers' users from collapsing into one flat namespace. Status is read through ^{get_connected_account_details}, which returns metadata without auth credentials, so no token enters your process even during a health check.

The ^identifier is the user's stable ID, resolved server-side from your authenticated session or a verified JWT. Never accept it from client input; the whole tenant boundary rests on that value being trustworthy.

Retrieve the authorized tool surface

With the user resolved, retrieve the tools their connected account authorizes. ^{list_scoped_tools} returns that set in Anthropic's native tool format (name, description, JSON Schema), already bound to this identifier.

Two independent gates apply, and they answer different questions:

• Identity gate (Scalekit). ^{list_scoped_tools} returns only what this user's connected account authorizes. This decides which tools appear.
• Role gate (your code). A scheduling agent needs a specific read set plus exactly one write. Intersect the authorized surface with an explicit role allowlist. This decides which tools this agent may hold, independent of identity.

Surface reduction here is an accuracy and cost lever, not tidiness. The Outlook connector ships 126 tools; at roughly 200 tokens per definition, registering the catalog burns about 25,200 tokens before the agent does any work, and asks the model to choose from a decision space it was not designed to handle at that scale. Seven tools is about 1,400 tokens, a reduction of roughly 94%. The fix is not better prompting. It is surface reduction.

The role allowlist is also the security boundary. These 119 unregistered tools include ^{outlook_send_message}, ^{outlook_forward_message}, ^{outlook_permanently_delete_message}, ^{outlook_mailbox_settings_update}, ^{outlook_create_message_rule} (a persistent inbox rule is a standing exfiltration channel), and ^{outlook_create_calendar_permission} (grants another address delegate access to a calendar). An injected instruction cannot call a tool that was never registered. This is the same tool calling authentication principle that applies across all agent frameworks.

A third layer applies at execution time and is not visible in this code: because every call runs against the user's own delegated token, Graph's own record-level access control still applies. The tool surface is one boundary; the token is another.

Facts the agent must not infer

The gate that protects the write needs reference data, and every piece of it is a fact the model would otherwise guess. Your code fetches these by calling ^execute_tool directly; they never become agent tools, which keeps the registered surface at seven.

The participant set comes from headers, not prose

The only trustworthy attendee list is the one Outlook already has: ^from, ^toRecipients, and ^ccRecipients on the thread's messages. Prose in the body ("loop in the vendor team") is a request, not an authorization. Resolving the allowlist deterministically, in code, is what makes the later check possible.

Timezone and working hours come from the mailbox

^{outlook_mailbox_settings_get} takes no parameters and returns the mailbox timezone, working hours, and locale. That is the source of truth for ^{start_timezone} and ^end_timezone, not your server's clock and not the model's reading of "3pm." Graph reports mailbox timezone in Windows naming (^{Pacific Standard Time}) while ^{outlook_find_meeting_times} and ^{outlook_get_free_busy_schedule} take IANA identifiers (^{America/Los_Angeles}), so normalize once, in one place, and pass the normalized value everywhere.

Availability is an authorization boundary, not a data lookup

This is the part that surprises people. ^{outlook_find_meeting_times} checks free/busy on the primary calendars of the organizer and attendees, and it fails in specific, documented ways:

For a cross-organization thread, ^{attendeesUnavailableOrUnknown} is the normal result, not an error. The API is not withholding data; the attendee's tenant never granted your user visibility. ^{findMeetingTimes} is also unavailable on personal Outlook.com mailboxes, so a consumer user gets nothing from it at all. Community reports of persistent ^{AttendeesUnavailable} and ^{OrganizerUnavailable} on healthy calendars mean an empty result is never sufficient evidence of a conflict.

Reaching for the shared-calendar tools to close that gap is the trap. ^{outlook_list_shared_calendar_events} and ^{outlook_create_shared_calendar_event} target ^/users/{id} and require either delegated sharing granted by that person or ^{Calendars.ReadWrite} as an application permission. Application permission is org-wide mailbox access held by your app rather than by the user; it converts a least-privilege agent into one with more reach than any individual employee. Cross-tenant availability requires per-tenant authorization. There is no shortcut.

The correct behavior is to tell the agent so, in the system prompt, and to keep the fallback inside what the user can actually see: their own calendar view plus whatever free/busy is shared. For more on how access control for multi-tenant AI agents works at the token level, the patterns carry directly to this scenario.

Bind identity into every handler

The ^@tool handler signature is ^{async def handler(args)}. It receives the model's arguments and nothing else, so the acting user has to be captured in a closure when the tool is built, per run.

Build the server once at import time with a module-global identifier and every user's agent executes as that one identity. The server, and the identity baked into its handlers, is minted per run.

Two details at this layer are auth-specific. ^{actions.execute_tool} is a synchronous, blocking call, so offload it with ^{asyncio.to_thread} rather than stalling the loop. And when a user revokes the connection or a token cannot be refreshed, return ^{is_error: True} with a readable message instead of letting the exception escape: an uncaught exception stops the loop, while an ^is_error result lets Claude read the failure and continue. This is the same pattern described in the guide on how to handle token refresh for AI agents.

Gate the arguments, not just the tool

Everything so far constrains whose token runs and which tools exist. Neither constrains the values on the call, and the values are what an injected line in the thread can move: an extra address in ^{attendees_required}, a plausible body in ^body_content, a start time next quarter.

The Claude Agent SDK evaluates permissions in a fixed order: hooks, then deny rules, then ask rules, then permission mode, then allow rules, then ^can_use_tool. Two consequences decide where the gate lives.

• ^can_use_tool is the wrong place. A tool auto-approved by an ^{allowed_tools} entry never reaches the callback, and ^{permission_mode="dontAsk"} skips it entirely. A gate written there is silently bypassed in exactly the configuration a headless agent wants.
• ^PreToolUse is the right place. Hooks run before every other step, and a hook deny blocks the call even under ^{bypassPermissions}. That is the only position that sees every call regardless of mode and rules.

Each rule below maps to one named failure: attendee injection, body-as-exfiltration-channel, timezone drift, and duplicate invites from a retry.

Availability is worth a note on the same principle. Scalekit's identity gate and this argument gate are different objects: Scalekit answers whose credential and which tools, and this hook answers which values. That second answer is code you own, because the valid attendee set for a given thread is application logic, not connector configuration.

Assemble options and run the loop

Availability of built-in tools and auto-approval of MCP tools are two separate settings, and both need to be explicit. ^tools=[] sets the built-in availability set to empty, so ^Bash, ^Write, ^Edit, and ^WebFetch are not in the agent's context at all. ^{allowed_tools} auto-approves the seven derived names so the loop does not stall on prompts. ^{permission_mode="dontAsk"} turns anything unlisted into a hard deny rather than a silent fall-through.

Putting the write tool in ^{allowed_tools} is safe here precisely because the gate is a hook: hooks run before allow rules.

Change ^identifier and ^{organization_id} and the entire surface changes underneath: a different mailbox, a different calendar, a different timezone, a different consent state, with no change to the code.

Two production notes on the Teams link. The join URL lives on ^{onlineMeeting.joinUrl}; ^{onlineMeetingUrl} is null for Teams events and is being deprecated, which is why step 4 of the prompt reads back the event. And ^{isOnlineMeeting} fails quietly rather than erroring: personal Outlook.com mailboxes return ^{isOnlineMeeting: false} with ^{onlineMeetingProvider: unknown}, as do organizational calendars whose ^{allowedOnlineMeetingProviders} does not include the requested provider. Developers have also reported cases where naming ^{teamsForBusiness} explicitly suppressed a link that appeared when the field was omitted entirely. A silent false is the expected failure mode; verify, do not assume.

What breaks without this

FAQs

Does ^{list_scoped_tools} stop an injected instruction?

It stops the injected instruction from reaching a tool that is not registered, which removes send, forward, delete, rule creation, and calendar-permission grants from the attack entirely. It does not stop an injected instruction from changing the arguments of a tool that is registered. That is the argument gate's job, and the two are not substitutes.

Why a ^PreToolUse hook rather than ^can_use_tool?

Because auto-approved calls never reach ^can_use_tool. Any tool named as a bare entry in ^{allowed_tools} is approved at the allow-rule step, and ^{permission_mode="dontAsk"} skips the callback for everything else. Hooks run first in the evaluation order and a hook deny holds in every permission mode, so a hook is the only position that sees every call.

Can one ^{ClaudeSDKClient} serve every user?

No. The identity is baked into the tool handler closures and into the server passed in ^{ClaudeAgentOptions}, and the gate closes over that user's participant set and mailbox timezone. Reuse the process; mint the surface, the options, and the hook per run, per user.

A user revokes Outlook access mid-run. What happens?

The next ^execute_tool for that connection fails, the handler returns ^{is_error: True}, and the system prompt tells Claude to report and stop rather than route around it. Other users' connections are unaffected, and the event is in the auth logs.

Do Outlook tokens ever reach the model?

No. Tokens live in Scalekit's vault and are resolved server-side inside ^execute_tool. ^{get_connected_account_details} is used for status checks specifically because it returns metadata without credentials. The agent sees tool results, never a credential.

How do I prove after the fact which user authorized a given invite?

Every ^execute_tool response carries an ^execution_id, and Scalekit's auth logs record the authorizing user, the tool, and the result, queryable for 90 days. Log the ^execution_id alongside the created event ID so a single lookup connects the invite to the authorization that permitted it. See audit trails for agent auth for the event categories a security review expects.

Should I use a Virtual MCP server instead of in-process registration?

Both work. The in-process pattern here gives the tightest control over the surface and the exact point where identity binds, plus a hook position for argument checks. A Virtual MCP server moves the surface out of your process, with one server definition per agent role and a short-lived session token minted per run; it fits better when you do not want to host anything and want per-run tokens rather than per-run tool registration. Argument-level authorization stays yours in both.

Where does human approval fit?

Where a wrong invite is expensive: external attendees, executive calendars, anything customer-facing. Return ^"ask" from the hook instead of ^"allow" for calls matching those conditions and resolve them through your own approval path. Scalekit's write-up on human-in-the-loop tool calling covers where the pause belongs relative to the tool call.

Next steps to build this agent

• Create the Outlook connection in AgentKit > Connections, register your multitenant Azure app, and grant only ^Mail.Read, ^{Calendars.ReadWrite}, ^User.Read, and ^{offline_access}. Copy the exact connection name into ^.env.
• Run ^{ensure_authorized} for one user, complete the consent link it prints, and confirm the status reads ^ACTIVE before touching any Graph endpoint.
• Register the seven-tool surface and print the count. If it is not seven, fix the role gate before running the loop.
• Test the argument gate directly, without the model: call the hook with an ^{attendees_required} value containing an address outside the header set and confirm it denies; then confirm a clean payload comes back with ^body_content, ^{start_timezone}, and ^{onlineMeetingProvider} rewritten.
• Send yourself a scheduling thread with an injected instruction in the body, run the agent, and verify in the Scalekit auth logs that no send tool was called and no unauthorized attendee reached the invite.