Open source · MIT · TypeScript and Python

Let agents use tools.
Stay in control of what they do.

Matimo is the governance layer for AI agent tools. Every call is risk-checked, every risky one is approved by a human, and every result lands on a tamper-evident log.

Building with agents? Serve tools to Claude DesktopResponsible for what agents can do? Require approval for risky calls

$ npm install matimo
129ready-made tools
449governed Composio tools (TypeScript)
15meta-tools
2SDKs: TypeScript and Python

Watch

Agent-written tool to audit log in 60 seconds

A short walkthrough built from real recorded runs of npm matimo 0.3.0 and PyPI matimo 0.2.0. Recorded against published versions; some behavior may differ in the next release. The narration is synthetic.

Read the transcript

Your agent just wrote a tool. Did anyone read it first? In TypeScript, Matimo gives your agent fifteen meta-tools. It can search tools, read skills, and write a new tool itself. It starts as a draft. Call it now, and it does not exist. Approve it, and it runs. Risky calls ask first too. HTTP deletes and shell commands wait for approval. One command serves every tool, yours and the built-ins, to MCP clients. Executions are chained into an audit log. Edit one value and verification finds the line. Open source, MIT. npm install matimo. Your agent's next tool waits for you.

The core idea

Your AI agent asks before it does anything risky

Matimo sits between your agent and its tools. Safe actions run right away, risky ones wait for a person to say yes, and everything is written to a log you can check later.

  • Every action is rated. Before a tool runs, Matimo rates it low, medium, high or critical using rules you can read.
  • Risky ones wait for a human. Deleting data or running a shell command pauses until a person approves. If nobody answers, it is refused.
  • A log that shows edits. Each entry is linked to the one before it, so an edit or removal is detected. It does not prevent one.
How the policy gate works →
The agent calls matimo.execute and the policy gate checks it with the approval handler, content validator, risk classifier, integrity tracker and approval manifest before an allowed call reaches the tool executor.

Governance first, then everything else

Run a tool. Let an agent write one.

The same call in both SDKs. An agent-created tool starts as a draft and needs approval before it runs.

import { MatimoInstance } from 'matimo';

const matimo = await MatimoInstance.init({ autoDiscover: true });
const result = await matimo.execute('slack_send_channel_message', {
  channel: '#general',
  text: 'Hello Matimo!',
});
Read the quick start →

Try it: approve or deny a risky call

A replay of a real run of the Python SDK. Press Run, then choose what the human reviewer does. Nothing is executed in your browser.

from matimo import Matimo, MatimoError, JsonlFileSink, verify_audit_log

async def on_approval(request):
    return await ask_a_human(request)   # you decide

matimo = await Matimo.init(
    "./tools",
    on_approval=on_approval,
    audit_sink=JsonlFileSink("./audit.jsonl"),
)

await matimo.execute("add_numbers", {"a": 2, "b": 3})
await matimo.execute("clear_cache", {"path": "./build"})

verify_audit_log("./audit.jsonl")
python demo.pyrecorded run

Press Run to start.

Want the real thing? Run it locally in five minutes.

How Matimo is different

Most agent tooling stops at "here are functions to call". Matimo adds the checks before a call and the record after it, and keeps both in your hands.

A plain tool libraryA hosted tool gatewayMatimo OSS
Where it runsIn your processOn the vendor's serversIn your process (TypeScript or Python)
Checks before a callYou write themThe vendor's rulesRisk class, policy file and human approval, built in
Agent creates its own toolNot coveredVariesStarts as a draft; needs approval before it runs
Record of what ranYour own loggingThe vendor's logsA hash-chained file you hold, with a verifier that shows edits
Tool definitionCode per frameworkThe vendor's catalogOne YAML for every framework, plus your own tools
Third-party catalogsNot coveredTheir ownWrap one, such as Composio, under the same policy

These are general categories, not named products. Why Matimo also lists what Matimo does not do, including compliance certifications, which it has none of.

Build your own tools and MCP server

Enterprises rarely need only public APIs. Matimo is built for your internal ones: define the tool, set the rules, expose it over MCP, and keep the evidence.

1Write a tool in YAML

Describe an internal API or command once: parameters, URL, headers. No SDK code and no per-framework wrapper.

2Set your policy

Keep your rules in a policy.yaml under version control. The policy reference lists the fields it supports.

3Serve it over MCP

Point the MCP server at your tool directory. Claude Desktop, Cursor and any MCP client see only what you expose.

4Approve and audit

Route risky calls to your reviewers and keep the audit log where your security team can verify it.

# tools/crm_lookup_customer/definition.yaml
name: crm_lookup_customer
version: "1.0.0"
description: Look up a customer in the internal CRM
parameters:
  customer_id:
    type: string
    description: The customer ID
    required: true
execution:
  type: http
  method: GET
  url: https://crm.internal.example.com/api/customers/{customer_id}
  headers:
    Authorization: Bearer {CRM_API_TOKEN}

# policy.yaml (fields are listed in the policy reference)
allowedDomains:
  - crm.internal.example.com
allowedHttpMethods:
  - GET
  - POST
# stdio for Claude Desktop or Cursor, with your own tools
npx matimo mcp --tool-paths ./tools

# a shared server with TLS and Vault-backed secrets
npx matimo mcp --transport http \
  --cert cert.pem --key key.pem \
  --secrets vault --tool-paths ./tools

What stays under your control

Ready-made tools, and room for your own

129 provider tools in 10 packages, plus 449 governed Composio tools in TypeScript. Add your own in a YAML file.

Works everywhere

Deploy to any framework or agent runtime without rewriting a tool.

Complete feature set

Everything needed to run agent tools in production.

1Core SDK

YAML-first tools

Define a tool once and run it from TypeScript, Python and any framework.

Hot-reload registry

Add or change tools at runtime without restarting your application.

Schema validation

Zod in TypeScript and Pydantic in Python for tool definitions and types.

Dual SDKs

TypeScript (Node 22.19+) and Python (3.11+) share the YAML format, policy rules and meta-tools. Composio is TypeScript only.

2129 ready-made tools

Slack and Gmail

Messages, channels and threads. Send, read and draft email.

GitHub

Issues, pull requests, repositories, code search and workflows.

Notion and HubSpot

Pages and databases. Contacts, deals and companies.

PostgreSQL

Parameterized SQL execution behind the policy engine.

Mailchimp and Twilio

Campaigns and audiences. SMS and MMS.

Microsoft and Bruno

Microsoft 365 tools and API-collection testing tools.

3Policy engine and governance

Risk classification

Every call is rated low, medium, high or critical with configurable policies.

Approval gates

Human-in-the-loop approval for sensitive operations, with signed manifests.

Audit trail

A hash-chained event log with secrets redacted. An edit or removed line is detected; it is not prevented.

Content validation

Pattern-based rules on agent-created tools before they can be approved.

Integrity tracking

Hash-based tamper detection so approved tools cannot change silently.

Approval expiry

Approvals carry a time limit and lapse on their own.

4Skills and self-extension

Skill search

TF-IDF keyword-relevance discovery of domain knowledge.

Skill library

Markdown SKILL.md files with YAML frontmatter, loaded only when relevant.

15 meta-tools

Create, validate, approve and reload tools and skills at runtime.

Agent self-extension

An agent can draft a tool. When your host passes agent context, the agent cannot approve its own tool.

5Integrations

LangChain

Convert tools to StructuredTool and add Matimo to existing agents.

CrewAI and Agno

Convert to framework tools with the same policy enforcement.

MCP server

stdio and HTTP transports for Claude Desktop, Cursor and other clients.

Composio catalog

449 governed tools across 14 toolkits (TypeScript, @matimo/composio).

6Auth and secrets

OAuth2 support

Provider-agnostic OAuth2 with token handling for Google, GitHub, Slack and others.

Placeholder credentials

Credentials are injected at call time through {NAME} placeholders, not stored in tool files.

Redacted logging

Secrets are redacted in audit events and error output.

Why teams choose Matimo

Dual SDKs

TypeScript and Python share the YAML format, policy rules and meta-tools. Composio is TypeScript only.

No tool duplication

Define once in YAML and use it from every framework.

Framework freedom

LangChain, CrewAI, MCP or your own loop, with the same tools.

Faster start

Ready-made Slack, GitHub, Gmail, Notion and more from day one.

Type safe

TypeScript types and Python hints, with Zod and Pydantic validation.

Community tools

A growing set of @matimo/* provider packages.

Agent self-extension

Agents build new tools at runtime, checked by policy.

Safe by default

Risky tools ask first. When your host passes agent context, an agent cannot approve its own creations.

Open source

MIT licensed, with about 4,700 tests across both SDKs (2,825 TypeScript run, 1,886 Python collected, counted 2026-10-29).

Four integration patterns

Pick what fits. Each pattern is shown in both SDKs.

1Factory pattern

Load tools and execute by name. Good for scripts, CLIs and quick prototypes.

matimo = await Matimo.init(auto_discover=True)
result = await matimo.execute('tool-name', params)

2Decorator pattern

Class-based approach. The @tool decorator executes the named tool for you.

class Agent:
    @tool('tool-name')
    async def my_method(self, param):
        pass  # executed through Matimo

3Framework integration

Convert Matimo tools to LangChain or CrewAI tools automatically.

from matimo import convert_tools_to_langchain
tools = convert_tools_to_langchain(matimo.list_tools(), matimo)

4MCP server

Run Matimo as a standalone MCP server for Claude Desktop, Cursor and any MCP client.

from matimo.mcp.server import MCPServer, MCPServerOptions

server = MCPServer(matimo, MCPServerOptions(transport="stdio"))
await server.start()

Developer CLI

Environment setup, validation and approval workflows from the terminal. Run it with npx matimo or, in Python, matimo.

Environment diagnostics

npx matimo doctor

Checks versions, installed @matimo/* packages, missing environment variables and YAML validity.

Approval workflows

npx matimo review list

Lists tools waiting for approval or in quarantine. Approve or reject from the terminal.

MCP setup

npx matimo mcp setup

Generates and writes the Claude Desktop configuration in one command.

Quick start resources

Production ready

Tested

About 4,700 tests across both SDKs. A pre-push hook runs both test suites. TypeScript coverage floors are 95% lines, 97% functions and 87% branches; Python core must stay at 95%.

Security controls

Secret isolation, command-injection prevention, integrity tracking and a fail-closed policy engine. No compliance certifications are held.

153 native tools

129 provider tools in 10 packages plus 24 core tools (15 of them meta-tools), and 449 more through Composio (TypeScript only).

Governance built in

Risk tiers, quarantine, approval manifests and an audit trail you can use in a compliance review.

One definition

The same YAML tool definition is used by both SDKs.

Open source

MIT licensed. Releases on npm (0.4.0) and PyPI (0.2.0).

Works with the frameworks you already use

Why Matimo →

For AI agents

Machine-readable docs for agents

Matimo is designed for agent-driven use under human oversight. Everything below is plain text, no JavaScript needed.

# TypeScript: core plus the CLI
npm install matimo
# TypeScript: core only
npm install @matimo/core
# Python
pip install matimo
# Serve tools to MCP clients
npx matimo mcp --tool-paths ./tools

Ready to govern your agents' tools?

Install it, run your first tool and see the approval gate in about five minutes.

Need a hosted runtime on top?

Matimo Workbench uses Matimo OSS as its tool layer, with a visual builder and managed runtime.

Explore Matimo Workbench