MCP & Tools

Tools give your agent capabilities beyond conversation. They are declared under the tools key in your agent YAML, each identified by a name you choose.

Omnigent supports MCP servers, built-in tools, Python functions, sub-agents, and inherited tools.

MCP servers

MCP (Model Context Protocol) servers expose tools over a standard protocol.

Custom servers

For MCP servers not in the bundled set, declare them in your agent YAML. Transport is inferred: use command for local stdio servers, url for remote HTTP/SSE servers.

Local command (stdio):

tools:
  my-server:
    type: mcp
    command: node
    args: [dist/server.js]
    env:
      API_KEY: ${MY_API_KEY}          # env vars expanded at runtime

Remote URL (HTTP/SSE):

tools:
  docs-api:
    type: mcp
    url: https://example.com/mcp
    headers:
      Authorization: "Bearer ${API_TOKEN}"   # env vars expanded at runtime

The optional tools list filters which MCP tools are exposed to the agent. It works the same on both transports — list the tool names you want to allow, and only those are surfaced to the model:

tools:
  github:
    type: mcp
    command: npx
    args: [-y, server-github]
    tools: [search_issues, get_pull_request]   # only these two are exposed

Omit tools to expose everything the server provides.

Authentication

As shown in the examples above, custom MCP servers accept credentials through:

• env: environment variables passed to stdio server processes (e.g., API_KEY: ${MY_API_KEY})
• headers: HTTP headers for remote servers, with ${...} env var expansion (e.g., Authorization: "Bearer ${API_TOKEN}")
• auth: with type: databricks: resolves an OAuth token from a profile in your ~/.databrickscfg. databricks is the only supported auth type; inside it, profile is required. Other servers don't use auth: — they authenticate via env or headers above:

tools:
  internal-api:
    type: mcp
    url: https://my-workspace.databricks.com/mcp
    auth:
      type: databricks
      profile: my-profile

Built-in tools

Omnigent ships a set of built-in tools you can enable by name under tools.builtins, without writing any code.

web_search

A unified web search tool whose backend is determined by your agent spec:

• OpenAI models — passes through to OpenAI's native web_search_preview (server-side, using the LLM API key). No search_provider needed.
• Other models (Anthropic, Llama, Databricks-hosted, etc.) — set search_provider to name the engine explicitly. There is no default and no env var fallback, so the engine that runs is always explicit; with no search_provider set, the tool returns an error naming the options.

Supported backends:

Keyless backends run out of the box; keyed backends need credentials for a sturdier, higher-rate service.

tools:
  builtins:
    - name: web_search
      search_provider: duckduckgo   # a keyless backend, as an example
      # api_key: ${PERPLEXITY_API_KEY}   # required for keyed backends

Keenable

Keenable is keyless by default. With no api_key in the spec it calls the keyless public endpoint and runs out of the box; supplying an api_key switches to the authenticated endpoint and lifts rate limits. Set the optional max_results to control how many results are returned (1–20, default 5):

tools:
  builtins:
    - name: web_search
      search_provider: keenable
      # api_key is optional — omit it to use the keyless free tier:
      # api_key: ${KEENABLE_API_KEY}
      # max_results: 5            # 1-20 (default 5)

Hindsight long-term memory

Three built-in tools give an agent memory that survives across runs and sessions, backed by Hindsight, an open-source agent-memory system. Unlike conversation history — which is lost between sessions — anything an agent retains stays available in every future run.

The Hindsight client SDK is an optional dependency. Install the memory extra and provide an API key:

pip install 'omnigent[memory]'
export HINDSIGHT_API_KEY=hsk_...    # https://ui.hindsight.vectorize.io

Enable the tools by name under tools.builtins:

tools:
  builtins:
    - name: hindsight_recall
      api_key: ${HINDSIGHT_API_KEY}
    - name: hindsight_retain
      api_key: ${HINDSIGHT_API_KEY}
    - name: hindsight_reflect
      api_key: ${HINDSIGHT_API_KEY}

Config keys

api_key is required; every other key is optional:

Memory is scoped by the resolved bank. With no bank_id, the bank defaults to the agent id, so each agent gets an isolated memory bank out of the box. Pin a fixed bank_id to share one human-readable bank across runs (or several agents):

tools:
  builtins:
    - name: hindsight_retain
      api_key: ${HINDSIGHT_API_KEY}
      bank_id: remy          # stable, easy to inspect in Hindsight

Because these tools only persist and recall when the model actually calls them, prompt the agent to recall before answering and to retain durable facts as it learns them — see the remy example agent for a worked prompt.

Python function tools

Expose any Python callable as a tool. The function is referenced by its fully qualified import path:

tools:
  summarize_file:
    type: function
    description: Summarize a local text file.
    callable: my_package.tools.summarize_file
    parameters:
      type: object
      properties:
        path:
          type: string
      required: [path]

The JSON Schema under parameters is optional. If you omit it, Omnigent auto-generates the schema from the function's type annotations and signature.

Sub-agent tools

Declare agents as tools so a supervisor agent can delegate work to them. You can define a sub-agent inline, or keep it in its own directory and reference it by name.

Inline definition

Define the sub-agent's full spec directly in the tools block:

tools:
  reviewer:
    type: agent
    description: Review proposed code changes.
    prompt: |
      You are a careful code reviewer. Focus on correctness,
      tests, security, and maintainability.
    executor:
      harness: claude-sdk
      model: claude-sonnet-4-6
    os_env: inherit
    pass_history: true
    max_sessions: 2

External directory

For a sub-agent that is complex, shared across parents, or maintained independently, give it its own directory under the parent's agents/ folder and list it by name under tools.agents. Omnigent discovers every agents/<name>/config.yaml at load time:

# Parent config.yaml
tools:
  agents:
    - reviewer

# agents/reviewer/config.yaml — a standard agent config
spec_version: 1
name: reviewer
description: Review proposed code changes.
prompt: |
  You are a careful code reviewer. Focus on correctness,
  tests, security, and maintainability.
executor:
  type: omnigent
  config:
    harness: claude-sdk
  model: claude-sonnet-4-6

Entries under tools.agents are just names (strings) matching a subdirectory of agents/. Each referenced file is a full agent config that can define its own tools, skills, harness, and policies.

A sub-agent (inline or external) can have its own harness, model, tools, and policies. On an inline sub-agent the pass_history flag controls whether the parent's conversation history is forwarded, and max_sessions limits concurrent invocations.

Tool inheritance

Use inherit to pass one of the parent's tools down to a sub-agent:

tools:
  researcher:
    type: agent
    prompt: Research and summarize.
    tools:
      word_count: inherit    # gets word_count from parent

The sub-agent receives the same tool definition the parent has, with no duplication.

Use spec: self for a sub-agent that clones the entire parent spec. It gets the same tools, prompt, and configuration as the parent agent.

Combine tool types

A single agent can mix all tool types. The tools block is a flat map of names to definitions:

tools:
  github:
    type: mcp
    command: uv
    args: [run, python, -m, my_package.github_mcp]

  summarize_file:
    type: function
    callable: my_package.tools.summarize_file

  reviewer:
    type: agent
    config: agents/reviewer.yaml