Connect a framework to protected tools

python -m pip install https://docs.soterias.io/downloads/api-preview/soterias_local-0.1.0rc5%2Bapi2-cp311-abi3-win_amd64.whl

npm install https://docs.soterias.io/downloads/api-preview/soterias-core-0.1.0-rc.5-api.2.tgz
npm install --save-dev typescript@5.8.3 @types/node@24

import asyncio
import json
import os
from pathlib import Path
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from soterias_frameworks import AccountingMcpClient

import fs from 'node:fs';
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { tool } from '@langchain/core/tools';
import * as z from 'zod/v4';

# %% Connect your framework to the caller-owned MCP session
# This optional package adds adapters; the native SDK and host remain separate.
url = os.environ["SOTERIAS_MCP_URL"]
request = Path(os.environ["SOTERIAS_REQUEST"]).read_text(encoding="utf-8")
framework = os.environ.get("SOTERIAS_FRAMEWORK", "custom")


async def main():
    headers = {"Authorization": "Bearer " + os.environ["SOTERIAS_MCP_TOKEN"]}
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            client = AccountingMcpClient(session)

// %% Connect a LangChain tool to the caller-owned MCP session
// TypeScript uses the official MCP client; Soterias's optional adapters are Python.
const client = new Client({ name: 'invoice-framework', version: '1.0.0' });
try {
  await client.connect(new StreamableHTTPClientTransport(new URL(process.env.SOTERIAS_MCP_URL!),
    { requestInit: { headers: { Authorization: 'Bearer ' + process.env.SOTERIAS_MCP_TOKEN },
      redirect: 'error', credentials: 'omit' } }));

            # %% Choose a framework surface without changing the secured backend
            # These direct tool calls need no model key and preserve native refusals.
            if framework == "custom":
                result = await client.execute(request)
                if not result.ok:
                    raise RuntimeError("Protected operation refused")
                outcome = result.outcome.model_dump()
            elif framework == "langchain":
                from soterias_frameworks.langchain import langchain_accounting_tool
                outcome = json.loads(await langchain_accounting_tool(client).ainvoke(
                    {"requestJson": request}))
            elif framework == "langgraph":
                from langchain_core.messages import AIMessage
                from langgraph.graph import END, MessagesState, StateGraph
                from soterias_frameworks.langchain import langgraph_accounting_node
                graph = StateGraph(MessagesState)
                graph.add_node("accounting", langgraph_accounting_node(client))
                graph.set_entry_point("accounting")
                graph.add_edge("accounting", END)
                messages = await graph.compile().ainvoke({"messages": [
                    AIMessage(content="", tool_calls=[{"name": "execute_accounting",
                        "id": "invoice-42", "args": {"requestJson": request}, "type": "tool_call"}])]})
                outcome = json.loads(messages["messages"][-1].content)
            elif framework == "crewai":
                from soterias_frameworks.crewai import crewai_accounting_tool
                result = await crewai_accounting_tool(client).arun(requestJson=request)
                outcome = result.model_dump()
            else:
                raise ValueError("Choose custom, langchain, langgraph or crewai")

  // %% Wrap the actual protected host tool
  // The host owns credentials, policy and exact approval. The wrapper cannot sign.
  const accounting = tool(async ({ requestJson }) => {
    const result = await client.callTool({ name: 'execute_accounting', arguments: { requestJson } });
    if (result.isError) throw new Error('Protected operation refused');
    const content = result.content.find(block => block.type === 'text');
    if (!content || content.type !== 'text') throw new Error('Expected an accounting outcome');
    return content.text;
  }, { name: 'execute_accounting', description: 'Submit one exact protected accounting request.',
    schema: z.object({ requestJson: z.string().min(1).max(65536) }).strict() });

            # %% Inspect the original protected outcome
            # Do not cache or automatically retry these effect tools.
            print(json.dumps({"status": outcome["status"], "framework": framework,
                              "target_observed": outcome["targetObserved"]}))


asyncio.run(main())

  // %% Invoke the tool directly before adding a model or graph
  // This test needs no model key. Do not cache or automatically retry effect tools.
  const outcome = JSON.parse(await accounting.invoke({
    requestJson: fs.readFileSync(process.env.SOTERIAS_REQUEST!, 'utf8'),
  }));
  console.log(JSON.stringify({ status: outcome.status, framework: 'langchain', target_observed: outcome.targetObserved }));
} finally { await client.close(); }

import fs from 'node:fs';
import path from 'node:path';
import { security } from '@soterias/core';
import { listenAccountingHttp } from '@soterias/mcp-server/accounting-http';

// %% Open the operator-selected native owner
// Enrollment, tool review, warrants and exact operation approval happen beforehand.
const root = process.env.SOTERIAS_ROOT;
const read = name => fs.readFileSync(path.join(root, name));
const owner = security.Host.open({ root, custody: process.env.SOTERIAS_CUSTODY,
  configuration: read('configuration.json'),
  checkpoint: fs.readFileSync(process.env.SOTERIAS_CHECKPOINT),
  passphrase: Buffer.from(process.env.SOTERIAS_UNLOCK) });

// %% Start a loopback host with authenticated native admission
// The agent cannot replace the policy, custody or signed approval through a tool call.
let listener;
try {
  listener = await listenAccountingHttp(owner, {
    transportPolicy: read('transport-policy.json'),
    operationApproval: read('operation-approval.json'),
  });
  const token = owner.issueTransportCredential().toString('base64url');
  fs.writeFileSync(process.env.SOTERIAS_CONNECTION,
    JSON.stringify({url: listener.url, token}), {flag: 'wx', mode: 0o600});
} catch (error) { owner.close(); throw error; }

// %% Retain the acknowledged checkpoint when shutting down
// Keep this output independently of the writable host and signing custody.
let stopping;
function stop() {
  stopping ??= (async () => {
    await listener.close();
    fs.writeFileSync(process.env.SOTERIAS_NEXT_CHECKPOINT, listener.checkpoint(),
      {flag: 'wx', mode: 0o600});
  })();
  return stopping;
}
for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => {
  void stop().catch(() => { process.stderr.write('host_shutdown_failed\n'); process.exitCode = 1; });
});
// A parent process can close this control stream for orderly local shutdown.
process.stdin.resume();
process.stdin.once('end', () => { void stop(); });

import fs from 'node:fs';
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

// %% Connect to an operator-configured protected MCP host
// The token is scoped to execution. Reviewer keys never enter this client.
const client = new Client({ name: 'invoice-assistant', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(new URL(process.env.SOTERIAS_MCP_URL),
  { requestInit: { headers: { Authorization: 'Bearer ' + process.env.SOTERIAS_MCP_TOKEN },
    redirect: 'error', credentials: 'omit' } });
try {
  await client.connect(transport);

  // %% Execute through the native host's real accounting tool
  // The host selects routes and approval evidence; the tool receives a request.
  const requestJson = fs.readFileSync(process.env.SOTERIAS_REQUEST, 'utf8');
  const result = await client.callTool({ name: 'execute_accounting', arguments: { requestJson } });
  if (result.isError) throw new Error('Protected tool refused the request');
  const content = result.content.find(block => block.type === 'text');
  if (!content || content.type !== 'text') throw new Error('Expected an accounting outcome');
  const outcome = JSON.parse(content.text);

  // %% Inspect the outcome instead of treating transport success as business success
  // Verify original receipts separately with your own retained trust.
  console.log(JSON.stringify({ status: outcome.status, target_observed: outcome.targetObserved }));
} finally { await client.close(); }