Synapsor
Log inGet access
All docs
Docs
Core Concepts

Agent framework adapters

Expose reviewed Synapsor capabilities as safe tools for MCP, OpenAI Agents SDK, LangGraph, CrewAI, or your own loop.

Overview

MCP in plain English: MCP says here is a tool, the model can call it. A Synapsor MCP adapter says here is a safe tool created from a reviewed Synapsor capability; it has session binding, RBAC, evidence, workflow-run linkage, compact handles, and no raw SQL escape hatch.

Without a Synapsor adapter, a developer may manually write get_customer, search_policy, issue_refund, update_ticket, save_memory, and write_audit_log tools, then manually rebuild auth, tenant filters, approval, audit, evidence, retries, idempotency, and memory.

With a Synapsor adapter, the developer defines reviewed capabilities and exposes them safely. The model gets a normal framework tool, but the call stays inside Synapsor's session, RBAC, evidence, proposal, branch, and replay boundary.

There are two adapter modes. Mode A exposes individual capabilities as tools when the agent framework should orchestrate the run. Mode B exposes an entire workflow as one tool when the developer wants a simpler integration and a Synapsor run envelope.

Adapters do not expose raw SQL. They map reviewed capabilities to framework tool names and resource URI templates, so an agent framework can call Synapsor without escaping the Synapsor trust contract.

Use this when MCP, OpenAI Agents SDK, LangGraph, CrewAI, or a custom orchestrator should discover safe tools from capabilities. The framework still decides what to call next; Synapsor validates session bindings, invokes the capability, records evidence/proposal lookup ids, and links the call into the run graph when you pass run_id and step_key.

Adapter definitions are tenant-scoped and visible through synapsor_agent_adapters and synapsor_agent_adapter_tools.

MCP in plain English

MCP says: here is a tool, the model can call it.

A Synapsor MCP adapter says: here is a safe tool created from a reviewed Synapsor capability. It has session binding, RBAC, evidence, workflow-run linkage, compact handles, and no raw SQL escape hatch.

The agent framework still sees a normal tool. The database keeps the call inside the reviewed Synapsor boundary.

Without Synapsor adapter

A developer may manually write many raw tools, then rebuild authorization, tenant filters, evidence capture, approvals, audit logs, retries, idempotency, and memory around those tools.

That works for prototypes, but it spreads trust logic across tool descriptions, app routes, workers, vector search glue, provider logs, and prompt text.

manual-tools.ts
server.tool("get_customer", ...);
server.tool("search_policy", ...);
server.tool("issue_refund", ...);
server.tool("update_ticket", ...);
server.tool("save_memory", ...);
server.tool("write_audit_log", ...);

With Synapsor adapter

The developer defines reviewed capabilities and exposes them safely. The model gets an MCP, OpenAI Agents SDK, LangGraph, CrewAI, or custom framework tool, but the call stays inside Synapsor's session, RBAC, evidence, proposal, branch, and replay boundary.

Adapters map reviewed capabilities and workflows to framework tool names. They do not expose raw SQL.

safe-tools.sql
CREATE AGENT ADAPTER mcp.support_agent
TYPE MCP

EXPOSE CAPABILITY support.answer_ticket_question
  AS TOOL 'support_answer_ticket_question'
  INLINE EVIDENCE handles_only

EXPOSE CAPABILITY billing.propose_refund
  AS TOOL 'propose_refund'
  MODE propose_only

EXPOSE RESOURCE evidence_bundle
  AS URI 'synapsor://evidence/{evidence_bundle_id}'

SESSION BIND tenant_id FROM AUTH CLAIM 'tenant_id'
SESSION BIND principal FROM AUTH CLAIM 'sub'
DENY RAW SQL
REQUIRE EVIDENCE;

Two adapter modes

Mode A exposes individual capabilities as tools when the agent framework should orchestrate everything.

Mode B exposes an entire workflow as one tool when the developer wants a simpler integration. Synapsor starts the run, enforces the workflow contract, and returns run, evidence, proposal, and next-action handles.

adapter-modes.sql
-- Mode A: expose individual capabilities as tools.
EXPOSE CAPABILITY billing.propose_refund
  AS TOOL 'propose_refund'
  MODE propose_only;

-- Mode B: expose an entire workflow as one safe tool.
EXPOSE WORKFLOW support.ticket_refund_flow
  AS TOOL 'resolve_support_ticket';

Workflow-as-tool response

When a framework calls a whole workflow as one adapter tool, the response should be a compact envelope that the app can render, store, retry, or hand to a reviewer. The model should not invent these handles; they come from Synapsor.

Use the run_id for follow-up steps, evidence_bundle_id for inspection, proposal_id for preview or approval, and next_allowed_actions for UI decisions.

workflow-tool-response.json
{
  "run_id": "run_123",
  "status": "waiting_approval",
  "evidence_bundle_id": "evb_456",
  "proposal_id": "wrp://prop_789",
  "branch": "wf_support_ticket_refund_run_123",
  "next_allowed_actions": [
    "approve",
    "reject",
    "request_more_info"
  ]
}

Developer notes

  • Expose capabilities, not run_sql tools.
  • Keep tenant/principal values in trusted session bindings.
  • Return compact evidence lookup records for model-facing tools.
  • Pass run_id and step_key when the tool call belongs to a durable workflow run.