Architecture

ToolMesh is a Go middleware that orchestrates, authorizes, and secures the execution of tool calls between AI agents and backend infrastructure.

Execution Pipeline

Every tool call passes through a fail-closed pipeline:

Agent ──▶ MCP Server ──▶ Auth ──▶ Executor
                          │          │
                          │          ├─▶ OpenFGA: Check(user, can_execute, tool)
                  OAuth 2.1/PKCE     │     └─ denied → Error: unauthorized
                  API Key            │
                  Password           ├─▶ CredentialStore: Get(credential, tenant)
                          │          │
                          ▼          ├─▶ Gate pre: Evaluate(input)
                   UserContext       │
                   (user, plan,      ├─▶ Backend: Execute(tool, params)
                    roles,           │     ├─ MCP Client → external MCP server
                    callerID)        │     └─ REST Proxy → HTTP call via DADL
                                     │
                                     ├─▶ Gate post: Evaluate(output)
                                     │
                                     └─▶ Audit: Record(entry)

If any step rejects (AuthZ, Gate), the entire execution stops. No partial results leak through.

The Six Pillars

Pillar	Implementation	Backed by
Any Backend	MCP servers (HTTP/STDIO) + REST APIs via DADL	Go MCP SDK + DADL parser
Code Mode	list_tools + execute_code — LLMs write JS instead of JSON	AST-parsed tool calls
Audit	Every tool call logged structurally	slog (write-only) or SQLite (queryable)
Authorization	User → Plan → Tool relationships	OpenFGA
Credential Store	Secrets injected at runtime, never in prompts	Env vars (CREDENTIAL_*), extensible
Output Gate	JS policies validate input/output	goja (Go JS engine)

Extension Model

Three components are extensible via a registry pattern (inspired by Go’s database/sql drivers):

Component	Registry Function	Built-in	Config
Credential Store	credentials.Register()	embedded (env vars)	CREDENTIAL_STORE=<name>
Tool Backend	backend.Register()	mcp, rest (DADL), echo	config/backends.yaml
Gate Evaluator	gate.RegisterEvaluator()	goja (JavaScript)	GATE_EVALUATORS=<list>

Extensions register via init() functions. Enterprise extensions live in a separate module and are included via Go build tags:

go build -tags enterprise ./cmd/toolmesh

Enterprise Extensions

Component	Extension	Description
Credential Store	InfisicalStore	Infisical Secrets Manager integration
Credential Store	VaultStore	HashiCorp Vault / OpenBao integration
Gate Evaluator	Compliance-LLM	LLM-based content classification
Audit Store	Temporal	Durable audit for failure-prone backends

Project Structure

toolmesh/
├── cmd/
│   ├── toolmesh/          # Main entrypoint (MCP server)
│   └── tm-bootstrap/      # CLI: load OpenFGA model, write example tuples
├── internal/
│   ├── mcp/               # MCP server (Streamable HTTP + STDIO)
│   ├── backend/           # ToolBackend interface + MCPAdapter + RESTAdapter
│   ├── executor/          # ExecuteTool pipeline (AuthZ → Creds → Gate → Exec → Audit)
│   ├── audit/             # Audit store interface + log/sqlite implementations
│   ├── authz/             # OpenFGA authorization
│   ├── credentials/       # Credential store interface + EmbeddedStore
│   ├── gate/              # Output gate (goja policy engine)
│   ├── userctx/           # UserContext propagation
│   └── config/            # Environment-based configuration
├── config/                # Backend config (backends.yaml, users.yaml, apikeys.yaml)
├── tools/                 # TypeScript tool definitions (canonical source)
├── policies/              # JavaScript gate policies
└── docs/                  # Documentation