Tools & MCP

Connect AI capabilities through the Model Context Protocol. Use built-in tools, attach external MCP servers, and watch tool execution live on the Brain Canvas.

6 min read

Tools & MCP

Tools give your AI the ability to act — search the web, read files, execute code, call APIs. Chvor is MCP-native, meaning it uses the Model Context Protocol as the standard interface for all tool integrations. Built-in tools and external MCP servers work identically: they register themselves, describe their capabilities, and appear as nodes on the Brain Canvas.

Tool Simulation

waiting

Submit a query:

⎕

filesystemRead, write, and list files

⌕

web-searchSearch the web via MCP

▷

code-execExecute code in sandbox

Built-in tools

Chvor ships with several tools that cover common use cases out of the box.

Web search

Searches the web and returns structured results with titles, URLs, and snippets.

# In a skill definition
tools:
  - web_search

The web search tool uses a configurable provider. Set your preferred search backend in config.yaml:

tools:
  web_search:
    provider: tavily        # tavily | serper | brave | searxng
    api_key: tvly-...       # Provider-specific API key
    max_results: 5

Filesystem

Read, write, list, and search files on the host machine. Access is sandboxed to configured directories.

tools:
  web_search:
    provider: tavily
    api_key: tvly-...

  filesystem:
    allowed_paths:
      - ~/projects
      - ~/documents
    deny_patterns:
      - "**/.env"
      - "**/node_modules/**"
      - "**/.git/**"

The filesystem tool exposes these operations:

Operation	Description
`read_file`	Read the contents of a file
`write_file`	Write or overwrite a file
`list_directory`	List files and subdirectories
`search_files`	Search file contents with regex
`file_info`	Get metadata (size, modified date, type)

Code execution

Executes code in a sandboxed environment and returns stdout, stderr, and exit code.

tools:
  code_execution:
    languages:
      - python
      - javascript
      - bash
    timeout: 30000          # Max execution time in ms
    memory_limit: 256mb     # Max memory per execution

Supported runtimes are detected automatically from your system. The tool will only offer languages that are actually installed.

Model Context Protocol (MCP)

MCP is an open standard that defines how AI applications discover and use tools. Instead of hardcoding tool integrations, Chvor connects to MCP servers that describe their own capabilities.

How MCP works

An MCP server starts and exposes a set of tools via a JSON-RPC interface
Chvor connects to the server and calls tools/list to discover available tools
Each tool has a name, description, and JSON Schema for its parameters
When the AI decides to use a tool, Chvor calls tools/call on the MCP server
The result is returned to the AI as structured data

This means any MCP-compatible server works with Chvor without custom integration code.

Connecting an external MCP server

Add MCP servers in your config.yaml:

mcp_servers:
  # Stdio transport — Chvor spawns the process
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: ghp_...

  # Stdio transport — local script
  my-database:
    command: python
    args: ["./mcp-servers/database-server.py"]
    env:
      DATABASE_URL: "sqlite:///path/to/db.sqlite"

  # SSE transport — remote server
  company-tools:
    url: "https://mcp.internal.company.com/sse"
    headers:
      Authorization: "Bearer ${COMPANY_MCP_TOKEN}"

After adding a server to config, Chvor connects on next startup. You can also hot-reload by saving the config file — the server manager will connect to new servers and disconnect removed ones without restarting.

Transport types

Transport	Use Case	Configuration
stdio	Local tools, CLI wrappers, scripts	`command` + `args`
SSE	Remote servers, shared team tools	`url` + optional `headers`

Tool discovery and auto-registration

When an MCP server connects, Chvor automatically:

Discovers all tools via tools/list
Registers each tool in the internal tool registry
Creates a node on the Brain Canvas for each tool
Notifies all connected clients via WebSocket

You do not need to manually map MCP tool names to skill configurations. Use the MCP server name as a prefix:

# In a skill definition
name: developer
tools:
  - filesystem
  - code_execution
  - mcp:github              # All tools from the "github" MCP server
  - mcp:github:create_issue # A specific tool from the "github" MCP server

If an MCP server adds or removes tools at runtime (via the notifications/tools/list_changed event), Chvor picks up the change automatically. The Brain Canvas updates in real time — new tool nodes appear, removed ones fade out.

Viewing available tools

You can inspect all registered tools from the web UI or the API:

# List all available tools via the REST API
curl http://localhost:3000/api/tools | jq

# Response
{
  "tools": [
    {
      "id": "web_search",
      "type": "builtin",
      "description": "Search the web for information",
      "parameters": { ... }
    },
    {
      "id": "mcp:github:create_issue",
      "type": "mcp",
      "server": "github",
      "description": "Create a new issue in a GitHub repository",
      "parameters": { ... }
    }
  ]
}

Tool nodes on the Brain Canvas

Every tool — built-in or MCP — appears as a node on the Brain Canvas. Tool nodes show:

Tool name and source (built-in or MCP server name)
Status indicator: idle, executing, success, or error
Last invocation time and duration
Edges connecting to skills that have access

During execution, the tool node animates:

The skill node lights up (active)
An edge animates from the skill to the tool (invocation)
The tool node pulses (executing)
The edge animates back from tool to skill (result)
The tool node briefly shows success (green) or error (red)

Click any tool node to see its recent invocation history, including inputs, outputs, and timing.

Self-healing on failure

When a tool invocation fails — whether from a timeout, network error, or invalid response — Chvor’s self-healing system kicks in automatically. It retries with adjusted parameters, falls back to alternative tools if available, and logs the recovery on the brain canvas. Your AI doesn’t crash when a tool breaks; it adapts.

Hot reload

Tools support the same hot-reload behavior as skills. Changes to config.yaml are detected automatically:

# Add a new MCP server to config.yaml while Chvor is running
# The server logs will show:
# [mcp] Connecting to new server: my-database
# [mcp] Discovered 4 tools from my-database
# [mcp] Registered: mcp:my-database:query, mcp:my-database:insert, ...
# [canvas] Added 4 tool nodes

If an MCP server crashes or disconnects, Chvor marks its tools as unavailable (grayed out on the canvas) and attempts to reconnect with exponential backoff. The AI will not attempt to use unavailable tools.

Writing a custom MCP server

You can create your own MCP server to expose any capability to Chvor. Here is a minimal example in TypeScript:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "weather",
  version: "1.0.0",
});

server.tool(
  "get_weather",
  "Get current weather for a city",
  {
    city: z.string().describe("City name"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  },
  async ({ city, units }) => {
    // Your implementation here
    const weather = await fetchWeather(city, units);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(weather),
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Then register it in Chvor:

mcp_servers:
  weather:
    command: npx
    args: ["tsx", "./my-servers/weather.ts"]

The new tool appears on the Brain Canvas within seconds.

Security considerations

Filesystem sandboxing: The built-in filesystem tool only accesses directories you explicitly allow in allowed_paths. Deny patterns are checked before allow patterns.
Code execution sandboxing: Code runs with resource limits (timeout, memory) and no network access by default.
MCP server isolation: Each MCP server runs as a separate process. A crash in one server does not affect others.
Credential handling: API keys for MCP servers are stored in config.yaml with support for environment variable interpolation (${VAR_NAME}), so you can keep secrets in .env files rather than in the config directly.

Next steps

Skills — assign tools to skills for controlled access
Brain Canvas — watch tools execute in real time
Channels — understand how tool results flow back to users