Skip to main content

Tools & Plugins

Osaurus combines built-in tools, native plugins from its registry, and tools from remote MCP providers. Tools are exposed via the Model Context Protocol (MCP) so any MCP-compatible client can use them. Osaurus is both a full MCP server and client.

In the default Auto mode, agents start each session with a small always-loaded set of tools and pull in more from your enabled capabilities on demand — the same discovery mechanism that loads skills and methods. See Skills and Methods for how that works.

Why Native Tools?​

Osaurus's built-in and native-plugin tools are compiled Swift and Rust implementations, not Python plugin scripts running through interpreters. This matters for production AI agents:

AspectPython/uv MCPsNative Swift Tools
CPU SpeedInterpreter overhead + GIL limits parallelismCompiled machine code, true multi-threading
MemoryHigher baseline (~50MB+) + garbage collector pausesARC provides precise, predictable memory control
StartupVirtual environment + interpreter load (~200ms)Binary loads in under 10ms
DependenciesRequires Python runtime, pip packagesSelf-contained binary, zero dependencies

For agents that make dozens of tool calls per session, these differences compound.

Built-in Orchestrator tools​

The built-in Osaurus Orchestrator has a read-only agent definition and a compact management surface:

  • osaurus_inspect reads current state and describes agents, models, providers, MCP, native and Claude plugins, schedules, watchers, skills, knowledge, channels, memory, Sandbox, settings, and the declarative configuration schema.
  • osaurus_config validates and applies approval-gated configuration changes. It can create a specialist agent and activate that agent for delegation in the same chat turn.
  • osaurus_help lists or reads the bundled guide-* topics, so product explanations are grounded in the guide shipped with the app rather than model memory.

The same desired-state model is available through osaurus config, loopback HTTP, and YAML or JSON files. Sensitive controls that are intentionally outside the declarative schema remain UI-only.

Security-sensitive controls such as delegation budgets, autonomy ceilings, identity and pairing keys, privacy settings, and blanket tool approval remain UI-only.

Native plugin catalog​

The plugin registry changes independently of the app, so Osaurus does not rely on a fixed built-in inventory. Browse the current catalog and each plugin's tool list in Settings… (⌘,) → Tools & MCP → Plugins, or search it with osaurus tools search.

Tools & MCP has three tabs:

  • Services — connected MCP services, Add Service, and a Directory of services you can add.
  • All Tools — every tool grouped by source, with its permission policy and Auto-Allow All Tool Calls.
  • Plugins — installed and available native plugins from the registry.

There is no global Disable Tools switch. Tool availability is configured per agent under Abilities → Overview and Abilities → Tools.

Web search, browser automation, the clock (get_current_time), the calculator (calculate), Computer Use, and the Apple Apps tools (Calendar, Reminders, Contacts, Notes, Mail, Messages, Maps & Location, Music, Shortcuts) ship as built-in capabilities rather than registry plugins. Apple app tools are off by default and turned on per custom agent under Agents → agent → Abilities → Tools, one group per app.

calculate(expression, angle_unit?) evaluates one plain-text expression exactly, so agents don't do arithmetic in their heads. It handles + - * / ^ ** (and the Unicode ×, ÷, − signs), implicit multiplication, postfix %, !, and degrees, phrases like 15% of 80 and 200 + 15%, thousands separators, hex/binary/octal literals, ;- or newline-separated statements with variables, and an equation with one unknown (solved for all real roots). Integer arithmetic stays exact in 64 bits; roots show 12 significant digits. Errors come back as invalid_args on expression with a corrective message. Like get_current_time, it's available to the Orchestrator, custom agents, and spawned workers.

The former Apple app plugins (osaurus.calendar, osaurus.reminders, osaurus.contacts, osaurus.notes, osaurus.mail, osaurus.messages, osaurus.maps, osaurus.music) are superseded: their cards show a Built into Osaurus banner and installed copies are never loaded. Agents whose tool lists named the old plugin tools were migrated once to the built-in names with the matching app enabled.

Installing Tools​

Use the Osaurus CLI to manage tools:

# Install a tool from the registry
osaurus tools install <plugin-id>

# Install multiple tools
osaurus tools install <plugin-id> <another-plugin-id>

# List installed tools
osaurus tools list

# Search available tools
osaurus tools search xlsx

# Uninstall a tool
osaurus tools uninstall <plugin-id>

# Dev mode with hot reload
osaurus tools dev com.acme.my-plugin

Tools are installed to:

~/.osaurus/Tools/<plugin_id>/<version>/

Auto-selection (on-demand discovery)​

Key feature

Most other tools load every tool definition upfront — burning thousands of tokens before you even ask anything. Osaurus keeps the schema small and lets the agent expand it only when needed.

Each agent has a tool mode, set with the Auto-discover relevant tools switch in Settings… → Agents → the agent → Abilities → Tools:

ModeBehavior
Auto (default)The model starts with a small always-loaded hot set and loads more from your enabled capabilities on demand
ManualAll enabled capabilities are sent to the model every turn

In Auto mode, the agent expands its kit mid-conversation via two always-on tools: capabilities_discover searches your enabled methods, tools, and skills and returns ranked IDs; capabilities_load injects the selected items (with their dependencies) into the active session.

This keeps the context small compared to loading every tool spec, leaving more room for conversation and reasoning. Skills → · Methods →

Using Tools​

Via MCP Clients​

Once installed, tools are automatically available to any connected MCP client. Configure your client to connect to Osaurus:

Cursor / Claude Desktop:

{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}

The CLI proxies MCP over stdio to the running Osaurus server. If Osaurus isn't running, it auto-launches.

Via HTTP API​

Tools are also accessible via HTTP endpoints:

EndpointMethodDescription
/mcp/healthGETCheck MCP availability
/mcp/toolsGETList active tools
/mcp/callPOSTExecute a tool

Example: List available tools

curl http://127.0.0.1:1337/mcp/tools | jq

Example: Execute a tool

curl -X POST http://127.0.0.1:1337/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read_file",
    "arguments": {"path": "/etc/hosts"}
  }'

Via OpenAI Function Calling​

Tools can also be used through the standard OpenAI function calling interface:

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:1337/v1", api_key="osaurus")

response = client.chat.completions.create(
    model="gemma-4-e2b-it-4bit",
    messages=[{"role": "user", "content": "What files are in my home directory?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "list_directory",
            "description": "List contents of a directory",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "Directory path"}
                },
                "required": ["path"]
            }
        }
    }]
)

Tool Permissions​

Each tool can specify a permission policy:

  • ask (default) — Prompts user for approval before each execution
  • auto — Executes automatically if requirements are met
  • deny — Blocks execution entirely

Policies are set per tool under Tools & MCP → All Tools. A few built-in tools always ask regardless of policy — sending mail or messages and deleting calendar events or reminders show an approval card on every call.

Some tools require macOS system permissions:

PermissionHow to GrantUse Case
AutomationSystem Settings → Privacy & Security → AutomationAppleScript, controlling other apps
AccessibilitySystem Settings → Privacy & Security → AccessibilityUI automation, input simulation

The Tools UI shows which permissions are needed and provides one-click buttons to grant them.

Community Tools​

The Osaurus Tools Registry hosts community-contributed plugins. Browse available tools:

osaurus tools search <keyword>

Example: osaurus-emacs​

The osaurus-emacs plugin demonstrates a community tool that executes Emacs Lisp code:

osaurus tools install osaurus.emacs

Once installed, AI agents can interact with your Emacs instance:

{
  "id": "execute_emacs_lisp_code",
  "description": "Execute Emacs Lisp code in a running Emacs instance",
  "parameters": {
    "code": "(buffer-name)"
  }
}

Remote MCP Providers​

Osaurus can connect to external MCP servers and aggregate their tools into your local instance, alongside your locally installed plugins.

Adding a Remote MCP Provider​

  1. Open Settings… (⌘ ,)
  2. Navigate to Tools & MCP → Services
  3. Click Add Service and pick a service from the catalog (Linear, Notion, GitHub, and more) or Custom Server — or click Add on a row in the Directory below the list
  4. Sign in, enter an API key, or fill in the custom server details

Custom Server Options​

FieldDescription
NameDisplay name for the provider (also the tool-name prefix)
URL / stdio commandMCP server URL, or a local command for stdio servers
AuthNone, Bearer token, or OAuth — secrets are stored in the Keychain
Auto-connectConnect when Osaurus starts
StreamingEnable/disable streaming responses
Discovery TimeoutHow long tool discovery may take (default 20s)
Tool Call TimeoutHow long a single tool call may take (default 45s)

Use Test to check the connection before saving.

How It Works​

  • Tool Discovery — Osaurus queries the remote MCP server for available tools. Object schemas a server publishes without properties are filled in so strict providers accept them.
  • Namespacing — Remote tools are prefixed with the provider name (e.g., provider_toolname) to avoid conflicts. Each description notes the server's own name for the tool, and a call to the bare server name resolves to the prefixed tool of the server that publishes it.
  • Typed arguments — Integer arguments are sent as integers (a 0 or 1 is never coerced into a boolean).
  • Unified Access — All tools—local and remote—appear in the same tools list (Tools & MCP → All Tools)
  • Secure Storage — Authentication tokens are stored in macOS Keychain

Using Remote Tools​

Once connected, remote tools appear alongside local tools:

# List all tools (local and remote)
curl http://127.0.0.1:1337/mcp/tools | jq

# Call a remote tool (namespaced)
curl -X POST http://127.0.0.1:1337/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "provider_remote_tool",
    "arguments": {"param": "value"}
  }'

Remote tools are also available to MCP clients like Cursor and Claude Desktop through the standard osaurus mcp command.

Best Practices​

  • Use descriptive provider names — Makes it easy to identify tool origins
  • Set appropriate timeouts — Remote tools may have higher latency than local ones
  • Monitor connection health — The Services header summarizes connected services, ones that need attention, and tool counts; its ⋯ menu offers Reconnect All, Test Connections, and Copy Diagnostics

Plugin ABIs​

The native plugin host API is append-only. It has grown from v1 through v6, and every older plugin keeps loading unchanged against a newer host. Most plugins still choose between the two foundational tiers:

ABICapabilities
v1Tools only — define tool schemas and handle invocations, with no host callbacks
v2Full host API — register HTTP routes, serve web apps, persist data in SQLite, dispatch agent tasks, and call inference through any model

v2 plugins get the full Osaurus runtime, enabling integrations that go beyond simple tool calls. Versions v3–v6 add capabilities on top of v2 without breaking anything:

ABIAdds
v3Streaming control — cancel an in-flight completion by stream_id
v4Agent-context introspection — get_active_agent_id() so a plugin knows which agent invoked it
v5Structured logging — log_structured() emits searchable fields into Insights
v6Host-side free_string() — an allocator-stable free path for host-returned strings

Every new slot is optional: a plugin built against v6 checks host->version before calling a newer callback, and a v1 plugin runs fine on a v6 host. See the upstream ABI versioning reference for the full history and compatibility table.

v2 capabilities​

CapabilityManifest keyDescription
Toolscapabilities.toolsAI-callable functions
Routescapabilities.routesHTTP endpoints (OAuth, webhooks, APIs)
Configcapabilities.configNative settings UI with validation
Webcapabilities.webStatic frontend serving with context injection
DocsdocsREADME, changelog, external links

Each is opt-in. A plugin can declare any subset.

Tool contract​

Every tool — built-in, folder, sandbox, plugin, MCP — returns a JSON envelope in one of two shapes (success or failure). This is how the chat UI distinguishes "the tool succeeded with this result" from "the model used the tool wrong and should fix it on the next turn".

Tool Contract →

Creating Your Own Tools​

Want to build a tool? See the Plugin Authoring Guide for complete instructions.

Quick start:

# Scaffold a new Swift plugin
osaurus tools create MyPlugin --language swift

# Build and install locally
cd MyPlugin
swift build -c release
osaurus tools install .

# Dev mode with hot reload
osaurus tools dev com.example.myplugin

Central Registry​

All official and community tools are indexed in the osaurus-tools repository:

  • Browse plugins: See what's available
  • Submit your plugin: Open a PR to add your tool
  • Automatic CI: Your plugin JSON is validated on submission

Registry Structure​

osaurus-tools/
├── plugins/           # Plugin specifications
│   ├── osaurus.xlsx.json
│   ├── osaurus.pptx.json
│   └── ...
├── tools/             # Source code for official tools
└── scripts/           # Build and release automation

Troubleshooting​

Tool not appearing in MCP clients​

  1. Verify the tool is installed: osaurus tools list
  2. Check Osaurus is running: osaurus status
  3. Restart the MCP client to refresh the tool list

Permission denied errors​

  1. Check which permissions the tool requires in the UI
  2. Grant permissions via System Settings → Privacy & Security
  3. No restart required—permissions take effect immediately

Tool execution fails​

  1. Check Osaurus logs: Click the menu bar icon → View Logs
  2. Verify the tool's requirements are met
  3. Try reinstalling: osaurus tools uninstall <id> && osaurus tools install <id>

Related: