Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Code mode on the public MCP
Status: implemented behind ai-code-mode. The agent guide's "Code mode on the
public MCP" section is the current behaviour; this document keeps the reasoning.
Sources:
- Code Mode: give agents an entire API in 1,000 tokens (Cloudflare)
- Code execution with MCP (Anthropic)
Goal
Give external MCP clients (Claude, ChatGPT, Cursor) the code mode that agent
sessions already have: write one JavaScript module against the real Macro SDK
instead of chaining many tool calls. Only users with the ai-code-mode flag
see it.
What exists
crates/code_execution: fresh Deno child per run, prebundled SDK, network limited to Macro service hosts, 30 s deadline.crates/agent_code_mode:ExecuteCode,DescribeCodeTools, execution journal, review stacks. Session-bound throughout:ExecutionIdentityneeds a session, turn and agent; the journal is keyed by session; turn Stop cancels; owner approval goes through the session'sNativeToolGate.- Docs selection (
select_documentation): once per turn, one Jevdecidecall over the last user message, one question per SDK entity (30). Keeps p ≥ 0.5, top 4, 48 KiB budget, falls back to an entity's overview when its full reference does not fit, 1 s deadline. The result goes into the system prompt. - Public MCP (
services/agent_harness_service/src/public_mcp): stateless, OAuth user id only,ai_tools::tools_for(AiHost::Mcp).
The MCP has no system prompt and never sees the user's message, so per-turn docs injection cannot carry over. The agent has to ask for docs itself.
Design
1. Docs for a task
DescribeCodeTools gains task: Option<String>: a description of what the
agent is about to do. When set, the server runs the same Jev selection over
that text and returns every relevant entity's reference.
Split select_documentation into:
select_entities(user, text, cognition, cancel) -> Vec<SdkDocumentation>: the Jev call and threshold, no rendering.- The existing prompt renderer (top 4, 48 KiB, 1 s) for agent sessions.
- A tool renderer: all entities over the threshold, a larger deadline (the agent is waiting on this call), and a byte budget sized for MCP tool-result limits, falling back to overviews past it. On Jev failure, return the compact catalog and say so.
The MCP instructions and the ExecuteCode description tell the agent to call
DescribeCodeTools({task}) before writing code. Nothing enforces it: an
uninformed program fails with an SDK error, and the agent can look up docs
then. Agent sessions get the task field too.
2. Flagged tool surface
Evaluate ai-code-mode for the OAuth user in initialize, list_tools and call_tool,
reusing agent_inmem::domain::tool_mode::FlaggedToolMode.
- Off: unchanged.
- On:
tools/listisExecuteCode,DescribeCodeToolsandReadCodeDocsonly (agent_code_mode::inbound::toolset::user_toolset). Individual Macro tools are not advertised.initialize(which, unlikeget_info, sees the request) replaces the standard tool-catalog instructions with code-mode instructions. call_toolrejectsExecuteCode/DescribeCodeToolsfor unflagged users. Hidden native tools stay callable; they are the same tools.
The public MCP is stateless, so each request loads flags. PostHogFeatureFlags
does not cache; add a short per-user TTL cache in front of it rather than a
PostHog call per tool call. Clients cache tool lists, so a flag change shows up
on reconnect.
3. User-scoped execution
A user-scoped entry point next to SessionCodeMode:
#[async_trait]
pub trait UserCodeMode: Send + Sync + 'static {
/// Execute as the authenticated user; no session, journal or reviews.
async fn execute(
&self,
user: &MacroUserIdStr<'static>,
request: ExecuteRequest,
cancel: CancellationToken,
) -> Result<UserExecutionReceipt, CodeModeError>;
}
- Credentials:
MacroApiTokenSigner::mint_for(user, 60), with no agent id, so writes are attributed to the user like every other MCP tool. NoNativeToolGate: the MCP client already asks the user before tool calls. - No journal: the MCP response is the record, and there is no UI to load a
saved execution into. The MCP
ExecuteCodetherefore dropsexecution_id. - No reviews: there is no session stream to present into.
mainreturns{data}; review references fail the run.session/executionare undefined (the bootstrap already handles absent ids). - Cancellation: the rmcp request token (
context.ct); no turn watcher. - Admission: a separate
ExecutionServicewith its own limits, sharing theDenoRunner, so MCP traffic cannot starve agent sessions. - Tool schema: a separate
ExecuteCodestruct and description for MCP (source,timeout_ms), sharing the runtime contract text.
Factor the run loop of CodeModeService::run (progress, activity, outcome
validation) into a helper both entry points call. The session path keeps its
journal, turn watch and gate.
4. Telemetry
Span code_mode.user_execution with status, activity count, timeout and source
bytes, never source, results or the user's email-bearing id. Span
code_mode.task_documentation with the selected and omitted entities, bytes and
selection status. Trace headers already reach SDK calls.
Decisions
- Email send and event creation. Only on the user's quoted approval. The
email and calendar routes refuse a program's
email.send, thread reply, unconfirmed draft send or schedule, andcalendar.createEvent; MCP code mode has no reviews, so a program usesemail.sendConfirmed,EmailMessage.forwardConfirmed,EmailDraft.send/scheduleorcalendar.createConfirmed, quoting the user's reply approving that action. The MCP client's approval of anExecuteCodecall does not show the user the email or event itself. - Tool-result budget. 32 KiB of references per task response. A first
local run at 80 KiB produced an 87K-character response that Claude Code moved
out of context into a file. Entities that do not fit whole fall back to their
namespace overview, then to
omitted; the overview was enough to write the program in that run. - Reviews. An empty
reviews: [](which the shared guides use) is dropped; any review reference fails the run. Thetemplatesandexamplesguides, which depend on reviews, are unavailable to MCP clients.