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 Osaurus assistant tools​

The built-in Osaurus assistant has a read-only agent definition and serves as a configure-and-explain surface. Its read tools are always available:

  • osaurus_status summarizes the default agent, server, models, providers, MCP, plugins, schedules, watchers, skills, knowledge, channels, memory, and Sandbox, then suggests useful next steps.
  • osaurus_list and osaurus_describe inspect agents, models, providers, MCP providers, plugins, schedules, skills, watchers, knowledge collections, themes, slash commands, channels, and search providers.
  • 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.

Permissioned change tools let the assistant configure Osaurus after a one-tap approval. osaurus_settings reads or changes supported server, default-agent, chat, app, memory, and voice settings. osaurus_watcher creates, updates, enables, disables, or deletes folder watchers. Other helpers manage custom agents, models, providers, MCP, search providers, plugins, and schedules. Custom-agent updates include supported capability toggles, and a schedule update can move that schedule to another custom agent.

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 Management → Plugins, or search it with osaurus tools search.

Web search, browser automation, the clock (get_current_time), and Computer Use ship as built-in capabilities rather than registry plugins.

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 calendar

# 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 in the agent's Capabilities settings:

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

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 the Management window (⌘ ⇧ M)
  2. Navigate to MCP Providers
  3. Click Add Provider
  4. Enter the provider details

Configuration Options​

FieldDescription
NameDisplay name for the provider
EndpointMCP server URL or command
TokenAuthentication token (stored securely in Keychain)
TimeoutRequest timeout in seconds
StreamingEnable/disable streaming responses

How It Works​

  • Tool Discovery — Osaurus queries the remote MCP server for available tools
  • Namespacing — Remote tools are prefixed with the provider name (e.g., provider_toolname) to avoid conflicts
  • Unified Access — All tools—local and remote—appear in the same tools list
  • 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 — Check the Management window for provider status

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.files.json
│   ├── osaurus.git.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: