MCP Tools

Norn can list and call Model Context Protocol tools directly inside .norn sequences. The same deterministic MCP runtime is shared by the VS Code extension and the CLI, so editor runs and terminal runs behave the same way.

Configure norn.config.json

MCP servers are configured in the mcp.servers section of norn.config.json. The alias names under servers are the names you reference in run mcp list and run mcp call.

norn.config.json

{
  "_comment": [
    "Alias names under servers are what you reference in run mcp list/call.",
    "You do not need both localTools and remoteTools. Keep only the entries your project uses."
  ],
  "version": 1,
  "mcp": {
    "servers": {
      "localTools": {
        "_comment": [
          "Use stdio when Norn should launch a local MCP server process for you.",
          "Optional field you can add here: cwd"
        ],
        "transport": "stdio",
        "command": ["node", "./tools/mcp-server.js"]
      },
      "remoteTools": {
        "_comment": [
          "Use http when the MCP server is already hosted elsewhere.",
          "Optional fields you can define here: headers, timeoutMs"
        ],
        "transport": "http",
        "url": "https://mcp.example.com/mcp",
        "headers": {
          "Authorization": "Bearer {{$env.mcpToken}}"
        },
        "timeoutMs": 5000
      }
    }
  }
}

stdio launches a local MCP server process. http connects to a hosted MCP endpoint. Relative paths resolve from the location of norn.config.json, and the nearest config file to the active .norn file wins.

List and Call Tools

time-tools.norn

test sequence TimeTools
    var tools = run mcp list localTools
      var result = run mcp call localTools get_current_time("UTC")

    assert tools.count > 0
    assert tools[0].name exists
    assert result.isError == false
    assert result.structuredContent.currentTime exists
end sequence

run mcp list <alias> returns an array of tool definitions. run mcp call <alias> <tool>(...) accepts named arguments or positional arguments bound in the tool's input-schema order, and returns a result object you can assert on or capture into variables.

After a successful run mcp list <alias>, Norn caches the discovered tool metadata in .norn-cache next to the resolved norn.config.json. VS Code can then suggest cached tool names and named parameter properties for later run mcp call lines.

Result Shape

MCP tool calls return a deterministic result envelope with these commonly used fields:

content - raw MCP content blocks
structuredContent - parsed structured tool output when provided
text - concatenated text blocks for quick assertions
isError - whether the tool reported an error
server and tool - the resolved alias and tool name

.norn

var result = run mcp call remoteTools summarize_text("hello world")

assert result.isError == false
assert result.text contains "hello"
assert result.structuredContent.summary exists

If a tool advertises an outputSchema, Norn validates structuredContent against it before the result is exposed to the sequence.

Deterministic Session Behavior

One MCP client session is reused per resolved config file plus server alias for the duration of a sequence run.
Imported or nested sequences reuse the same session when they resolve to the same alias.
All MCP sessions are closed automatically when the outermost sequence finishes or fails.
tools/list pagination is drained automatically through nextCursor.

VS Code Setup

The extension can scaffold norn.config.json for you. Use the Project Setup section in the Norn sidebar, or right-click a folder in the Explorer and choose Create MCP Starter Config.