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-claude-agent-sdk/ 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. Prepare the files without running the agent or making 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'This guide connects a Claude Agent SDK agent to Submilli over MCP. The SDK keeps control of the agent loop, and Submilli executes the TypeScript programs 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 20 or later and configure the Claude Agent SDK with an Anthropic API key, Amazon Bedrock, Google Vertex AI, or a Claude Code login.
Start the project
Section titled “Start the project”mkdir claude-agent-submilli && cd claude-agent-submillinpm init -ynpm pkg set type=modulenpm install @anthropic-ai/claude-agent-sdk @modelcontextprotocol/sdknpm 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 { query, type Options } from "@anthropic-ai/claude-agent-sdk";import { Client } from "@modelcontextprotocol/sdk/client/index.js";import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
const prompt = process.argv.slice(2).join(" ");if (!prompt.trim()) throw new Error("Usage: npx tsx agent.ts '<message>'");
const server = process.env.SUBMILLI_SERVER ?? "http://127.0.0.1:8128";const blueprint = required("SUBMILLI_BLUEPRINT");const endpoint = new URL(`${server}/mcp/${encodeURIComponent(blueprint)}`);const requestInit = { headers: { Authorization: `Bearer ${required("SUBMILLI_SERVER_TOKEN")}` } };const transport = new StreamableHTTPClientTransport(endpoint, { requestInit });const client = new Client({ name: "claude-submilli", version: "1.0.0" });
try { await client.connect(transport); const catalog = await client.listTools(); if (!catalog.tools.some((tool) => tool.name === "submilli__typescript__execute")) { throw new Error("Submilli's execute tool is unavailable"); }
const mcp = new McpServer( { name: "submilli", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: client.getInstructions() }, ); mcp.server.setRequestHandler(ListToolsRequestSchema, (request) => client.listTools(request.params)); mcp.server.setRequestHandler(CallToolRequestSchema, (request) => client.callTool(request.params)); const options: Options = { // Change this model ID to use another supported Claude model. model: "claude-sonnet-5", systemPrompt: "Use Submilli to do calculations in TypeScript. Return the execution result.", mcpServers: { submilli: { type: "sdk", name: "submilli", instance: mcp } }, strictMcpConfig: true, allowedTools: ["mcp__submilli__*"], tools: [], settingSources: [], maxTurns: 10, }; const agent = query({ prompt, options }); try { for await (const message of agent) { // Keep the SDK events visible so the tool call and its result can be checked. console.dir(message, { depth: null }); if (message.type === "result" && message.is_error) { throw new Error("Claude reported an error; see the SDK result above"); } } } finally { agent.close(); await mcp.close(); }} finally { try { if (transport.sessionId) { // Initialization failures can auto-close the original transport. const cleanup = new StreamableHTTPClientTransport(endpoint, { requestInit, sessionId: transport.sessionId, }); if (transport.protocolVersion) cleanup.setProtocolVersion(transport.protocolVersion); try { await cleanup.terminateSession(); } finally { await cleanup.close(); } } } finally { await client.close(); }}
function required(name: string): string { const value = process.env[name]; if (!value) throw new Error(`${name} is not set`); return value;}strictMcpConfig limits MCP servers to the entry declared here.
allowedTools allows calls to that server without an interactive permission
prompt. The SDK can also give the agent shell, filesystem, web, and user-level
MCP tools that run outside Submilli. tools: [] and settingSources: [] keep
this example limited to the configured Submilli server.
The exact boundary in this example is one mcpServers.submilli entry, the
mcp__submilli__* allowlist, tools: [], and settingSources: []. No Claude
built-in tool or delegation tool is enabled. Direct Claude Agent SDK tools can
still be added when the application needs them, but those calls bypass
Submilli and keep the SDK’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.
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 script prints the SDK messages. Confirm that they contain a call to
Submilli’s execute tool and a tool result containing 4; the final
assistant text alone does not verify where the calculation ran. This example
uses the model provider for the agent conversation. The TypeScript program
itself only computes a value and calls no Package, application tool, or
external service.
A Blueprint applies only to programs executed through Submilli. If you enable other Claude Agent SDK tools, they keep the SDK’s own access and approval rules. See How Submilli works with harnesses for the full boundary.