Skip to content

MCP servers

June is an MCP client. You declare an MCP server in JSX, next to the steps that use it, and its tools join the agent as the ordinary AI SDK tools they are. june/mcp is a thin convenience over @ai-sdk/mcp: the AI SDK speaks the protocol and turns the server's tools into tools. June decides which agent gets them and how long the connection lives.

import { openai } from "june/sdk/openai";
import { Agent, Step } from "june";
import { defineMcpServer } from "june/mcp";

const Playwright = defineMcpServer({
  id: "playwright",
  transport: {
    type: "stdio",
    command: "bunx",
    args: [
      "@playwright/mcp@0.0.83",
      "--isolated",
      "--headless",
      "--no-webmcp",
      "--image-responses",
      "omit",
    ],
  },
});

export default function Check() {
  return (
    <Agent model={openai("gpt-5-mini")}>
      <Playwright />
      <Step id="check" prompt="Open the app and verify the flow." />
    </Agent>
  );
}

june run check.tsx runs it. There are no MCP flags, because the server is part of the workflow's source, and no .mcp.json is read. @ai-sdk/mcp is an optional peer: install it, bun add @ai-sdk/mcp, to import june/mcp; if it is missing the import says so.

What the model gets

Resolving <Playwright /> adds the tools client.tools() returns to the closest <Agent>, before any step in it runs. From there they are plain tools:

  • A step calls them through the same tool loop as a tool you wrote. June doesn't translate their schemas, wrap their execution, rename them, or add a second approval mechanism.
  • They show up in traces as ordinary tool calls, under the server's own tool names. Nothing in the trace, the runtime or the CLI knows they came from MCP.
  • Everything that works on capabilities works on them. <RequireApproval> makes each call wait for approval, <Namespace name="browser"> prefixes their names, and a bundle made with defineCapabilities can declare one beside other tools. Two tools with the same name, from a server and from anywhere else, fail with the same message any collision does.

MCP tools run without approval unless you ask, the same as any AI SDK tool without needsApproval. Wrap a server in <RequireApproval> if its tools have side effects you want to see first.

Visibility and lifetime are separate

Two scopes do two jobs, and neither implies the other:

AgentScope     which tools an agent's steps can see and call
ResourceScope  how long the live thing behind a tool stays alive

The server's tools belong to the <Agent> that declares it, and a nested <Agent> starts with none of them, even though both run against the same resource scope. Giving a nested agent the tools is the generic <Inherit> grant, not something MCP does.

import { openai } from "june/sdk/openai";
import { Agent, Step } from "june";
import { defineMcpServer } from "june/mcp";

const Docs = defineMcpServer({
  id: "docs",
  transport: { type: "stdio", command: "bunx", args: ["some-docs-mcp"] },
});

export default function Nested() {
  const model = openai("gpt-5-mini");
  return (
    <Agent model={model}>
      <Docs />
      <Step id="outer" prompt="Look something up." />
      <Agent model={model}>
        <Step id="inner" prompt="This agent has no docs tools." />
      </Agent>
    </Agent>
  );
}

How long the connection lives

A connection is a live, process-local value: a child process, and often a browser behind it. It belongs to a resource scope, not to a step, so it is never part of a snapshot.

one workflow run
└── run-owned ResourceScope
    └── MCP client

Chat or Studio session
└── session-owned ResourceScope
    └── MCP client and browser
        ├── turn 1's run
        ├── turn 2's run
        └── turn 3's run
  • A workflow run creates its own scope. The server is started the first time something in the run needs its tools, shared by everything in the run that declares it, and stopped, with the browser and any other process under it, before the run settles, whether it succeeded, failed, aborted or timed out.
  • A chat session can keep one for every turn: give the chat createResources: createResourceScope and each session owns one scope that all its turns borrow. A stateful server, such as a browser, then keeps its tabs and cookies from one turn to the next. Cancelling or failing a turn leaves it; session.close() stops it, and the CLI and Studio close their sessions when they exit. See Live resources.
  • Reopening a saved session restores the conversation, and starts a new connection: the scope is never written to the journal, so a page the old browser had open is gone.

A server that is declared twice in one run under one id must have the same configuration, or the second fails with a message that doesn't repeat the configuration.

Playwright as an example

Playwright MCP is the first server June is proven against because it is the hardest useful case: a child process with a browser under it, many tools, calls that depend on the ones before them, and a need to clean up. It is not a privileged integration, and June has no browser code. The flags in the example above are choices, not requirements:

  • --isolated keeps the session hermetic, with no profile shared with another run or your own browser;
  • --headless makes it work on a server or in CI;
  • --no-webmcp stops a page you visit from adding tools in the middle of a run;
  • --image-responses omit keeps base64 screenshots out of the model's context and the trace.

browser-check.tsx is the same server as a runnable example.

What you are trusting

A stdio server is a program on your machine, started with the permissions and environment of the June process, and June does not sandbox it.

  • The command and arguments are trusted configuration that you wrote. The model never chooses them, which is what separates an MCP server from <Bash />, where the model writes the command.
  • The server decides its tools' names, descriptions and schemas, and what each call does. A call can have side effects, and a tool's inputs and outputs may appear in the model's context and in traces.
  • env values in the config are passed to the process and are never shown in errors, traces or capability provenance.

Not included

June doesn't read .mcp.json, host an MCP server, support remote HTTP servers, OAuth, MCP resources or prompts, or reconnect a server that died. Those would be separate work, and none of them changes the model above.