Skip to main content
A toolset is how you bring your own tools. It registers them under a fixed lowercase namespace, so a toolset called billing gives you tools like billing.lookup_invoice. There are two kinds. An mcp toolset pulls its tools from a remote HTTPS MCP server. A client toolset declares them up front, and each call is handed back to your application through the client tool-call API. Registering a toolset doesn’t grant anything. It makes the names exist, and a role decides who may call them, either with tool:workspace:billing.* or an exact tool:workspace:billing.lookup_invoice. The model doesn’t get every tool schema stuffed into its context. It gets one tool, tool_search, and whatever a search turns up becomes callable by name for the rest of the thread. Search only looks at what the turn’s roles allow, so it can never surface a tool the agent isn’t allowed to call. Matrices also ships managed provider toolsets (Gmail, Calendar, Drive, Slack, GitHub, Linear, Notion, and more). Each has its own namespace and is granted with tool:managed:<namespace>.*, and each needs a connection as well as a role. An MCP toolset that speaks OAuth can carry its own client configuration under /v1/toolsets/{toolsetId}/oauth-client.
Belongs to a workspace · Has one namespace (immutable) · Is mcp or client · Granted by roles, never by registration

​
Rules

  • Registering a toolset grants nothing. See Rules.
  • Namespaces owned by built-in tools are reserved and cannot be claimed.
  • deny can’t target a toolset namespace; outside tools are allow-only.

​
API

  • The built-in catalog: Built-in tools.
  • GET/POST /v1/toolsets, PATCH/DELETE /v1/toolsets/{toolsetId}.
  • POST /v1/toolsets/{toolsetId}/probe to recheck an MCP server’s auth surface.