Use your coding agent
Section titled “Use your coding agent”Choose an icon to open a prefilled prompt. Select your project, review, and send.
View prompt
Read https://submilli.ai/docs/tutorials/connect-mastra/ as the source for this setup.
Inspect my project and follow this guide to create agent.ts. Reuse valid local Submilli connection settings and provider credentials. If SUBMILLI_SERVER, SUBMILLI_SERVER_TOKEN, or SUBMILLI_BLUEPRINT is missing, ask for that value or its local configuration source. Do not invent values, expose secrets, create a Blueprint, or change the server. Ask for missing provider credentials without printing them. Install only the missing dependencies shown in this guide. Preserve its tool restrictions and session cleanup. Run the file with --check to verify the connection without a model request. Leave the files ready for the exact Try it out command.
After setup, try it out.
Set up manually
Section titled “Set up manually”The files read this terminal’s environment; they do not automatically load
.env files. Use your running server’s base URL and registered Blueprint.
Replace these values before running the files:
export SUBMILLI_SERVER='your-server-base-url'export SUBMILLI_SERVER_TOKEN='your-server-token'export SUBMILLI_BLUEPRINT='your-registered-blueprint'export OPENAI_API_KEY='your-openai-api-key'This guide connects a Mastra agent to Submilli over MCP. The agent keeps its
model and loop in Mastra, while its TypeScript programs run on
submilli-server under a Blueprint your application selects.
Before you start:
- Run
submilli-serverand keepSUBMILLI_SERVER_TOKENexported. - Register a Blueprint, then set
SUBMILLI_BLUEPRINTto its registered name. The calculation below assumes the Blueprint has no required variables. The sample calls no external tools. - Install Node.js 22.13 or later and set the API key for your model provider.
Start the project
Section titled “Start the project”mkdir mastra-submilli && cd mastra-submillinpm init -ynpm pkg set type=modulenpm install @mastra/core @mastra/mcpnpm install --save-dev tsx typescript @types/nodeConnect the agent
Section titled “Connect the agent”Create agent.ts in the project directory and paste the code below:
import { Agent } from "@mastra/core/agent";import { MCPClient } from "@mastra/mcp";
const args = process.argv.slice(2);const checking = args.length === 1 && args[0] === "--check";const prompt = args.join(" ");if (!checking && !prompt.trim()) { throw new Error("Usage: npx tsx agent.ts '<message>' (or --check)");}
const server = process.env.SUBMILLI_SERVER ?? "http://127.0.0.1:8128";const blueprint = required("SUBMILLI_BLUEPRINT");
type Model = ConstructorParameters<typeof Agent>[0]["model"];
export async function answer( question: string, // Change this model ID to use another provider-supported model. model: Model = "openai/gpt-5-mini",): Promise<string> { const url = new URL(`${server}/mcp/${encodeURIComponent(blueprint)}`); const headers = { Authorization: `Bearer ${required("SUBMILLI_SERVER_TOKEN")}` }; let sessionId: string | null = null; const submilli = new MCPClient({ id: "submilli", servers: { submilli: { url, requestInit: { headers }, fetch: async (input, init) => { const response = await fetch(input, init); sessionId = response.headers.get("mcp-session-id") ?? sessionId; return response; }, }, }, });
try { const toolsets = await submilli.listToolsets(); if (toolsets.submilli === undefined) { throw new Error("submilli-server refused the connection"); }
if (checking) return "Connected to Submilli.";
const agent = new Agent({ id: "calculator", name: "Calculator", instructions: "Use Submilli to do calculations in TypeScript. Return the execution result.", model, });
const result = await agent.generate(question, { toolsets, maxSteps: 10, onStepFinish({ toolCalls, toolResults }) { if (toolCalls.length > 0) console.dir({ toolCalls, toolResults }, { depth: null }); }, }); return result.text; } finally { try { // disconnect() closes the transport, not the server's session. if (sessionId) { const response = await fetch(url, { method: "DELETE", headers: { ...headers, "Mcp-Session-Id": sessionId }, }); if (!response.ok && response.status !== 404) { throw new Error(`Could not close Submilli session: HTTP ${response.status}`); } } } finally { await submilli.disconnect(); } }}
function required(name: string): string { const value = process.env[name]; if (!value) throw new Error(`${name} is not set`); return value;}
console.log(await answer(prompt));Mastra receives Submilli’s tools in toolsets. Pass them to generate for
this request rather than putting a session-bound toolset on a shared agent.
Checking toolsets.submilli prevents the model from continuing without
Submilli if the MCP connection fails. The finally block deletes the server session, then closes the client
transport.
This configuration gives the model the tools returned by the one submilli
MCP server. It does not add Mastra tools or agents to the request. Mastra tools
can still be added directly when the application needs them, but those calls
bypass Submilli and keep Mastra’s own authorization and approval path. Current Submilli MCP connections do not support application-tool
callbacks. To let a TypeScript program call an application tool through
Submilli, use an HTTP session with the tools field on POST /v1/sessions,
grant tools.call in the Blueprint, and answer each suspended run through
POST /v1/runs/{run_id}/resume. See the HTTP API reference.
If the selected Blueprint declares required variables, add a
submilli-variables header whose values come from trusted application state,
as described in Your application.
Never take those values from the conversation.
Check the connection
Section titled “Check the connection”With the setup environment active, run this without a model request:
npx tsx agent.ts --checkLook for Connected to Submilli.. This checks the server and registered
Blueprint; the model runs only when you supply a message.
Try it out
Section titled “Try it out”npx tsx agent.ts \ 'Run this program through Submilli and report its result:export function main(): number { return 2 + 2; }'The step callback prints Mastra’s tool calls and results. Confirm a call to
Submilli’s execute tool and a result containing 4; the final answer
alone does not verify where the calculation ran.
This sample requires model-provider access for the Mastra conversation. The
TypeScript program itself only computes a value; it does not call a Package,
application tool, or external service.
For the division of responsibilities between Mastra, Submilli, and the Blueprint, see How Submilli works with harnesses.