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.

Bundled servers

The following MCP servers are available out of the box. No setup or configuration needed:

To restrict which tools from a bundled server your agent can access, use the tools filter or configure policies.

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. Omit it 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}")
• profile (under auth:): resolves an OAuth token from your ~/.databrickscfg:

tools:
  internal-api:
    type: mcp
    url: https://my-workspace.databricks.com/mcp
    auth:
      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)

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 reference an external config file.

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 config file

Point to a separate YAML file containing the sub-agent's spec. This is useful when the sub-agent is complex, shared across multiple parents, or maintained independently:

tools:
  reviewer:
    type: agent
    description: Review proposed code changes.
    config: agents/reviewer.yaml

The config path resolves relative to the parent agent's YAML directory. The referenced file is a standard agent config that can define its own tools, skills, harness, and policies.

A sub-agent tool can have its own harness, model, tools, and policies. 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