Connecting MCP Tools

Chvor extends agent capabilities through the Model Context Protocol (MCP). MCP tools let your agents read files, search the web, query databases, interact with APIs, and more — all through a standardized interface.

Tools are configured in ~/.chvor/config.json under the mcpServers key. Each entry defines an MCP server that provides one or more tools.

---

How MCP Works in Chvor

User message → Chvor server → Active skill selects tools → MCP server executes tool → Result returned to agent

1. A user sends a message that triggers a skill.
2. The skill’s tools field determines which MCP tools are available.
3. The LLM decides whether to call a tool based on the conversation context.
4. Chvor routes the tool call to the appropriate MCP server.
5. The MCP server executes the action and returns results.
6. The LLM incorporates the results into its response.

---

Finding MCP Servers

MCP servers are available from several sources:

Source	URL	Notes
Official MCP Servers	github.com/modelcontextprotocol/servers	Maintained by the MCP project
Chvor Registry	github.com/luka-zivkovic/chvor-registry	Community tools tested with Chvor
npm	npx @modelcontextprotocol/server-*	Many servers published as npm packages
Smithery	smithery.ai	MCP server directory

---

Configuration

All MCP servers are configured in ~/.chvor/config.json. If this file does not exist yet, create it:

{
  "mcpServers": {}
}

npx-based servers (recommended)

Most MCP servers are published as npm packages. You do not need to install them globally — use npx and Chvor will download and run them on demand:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/documents"
      ]
    },
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Locally installed servers

If you prefer to install a server globally or have a custom one:

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/index.js"]
    }
  }
}

Python-based servers

Some MCP servers are written in Python:

{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"]
    }
  }
}

---

Configuration Fields

Each MCP server entry supports these fields:

Field	Type	Required	Description
command	string	Yes	The executable to run (npx, node, python, etc.)
args	string[]	Yes	Arguments passed to the command
env	object	No	Environment variables set for this server process only
disabled	boolean	No	Set to true to temporarily disable without removing the config

Passing environment variables

Some tools need API keys or configuration. Use the env field to scope secrets to individual servers:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

This keeps secrets isolated — the GitHub token is only visible to the GitHub MCP server, not to other tools.

---

Permissions and Security

MCP tools can perform real actions on your system (read/write files, make network requests, execute commands). Treat tool configuration with the same caution as giving someone SSH access to your machine.

Best practices

1. Limit filesystem access. When configuring the filesystem tool, scope it to specific directories:

   {
     "command": "npx",
     "args": [
       "-y",
       "@modelcontextprotocol/server-filesystem",
       "/home/user/projects",
       "/home/user/documents"
     ]
   }

   This prevents the agent from reading /etc/passwd or your SSH keys.

2. Use read-only tools where possible. If the agent only needs to search, do not give it write access.

3. Scope skills to specific tools. In your skill YAML, list only the tools that skill actually needs:

   tools:
     - web-search

   Rather than leaving tools empty (which grants access to everything).

4. Audit tool calls. Chvor logs every tool invocation. Check ~/.chvor/logs/ for a record of what tools did.

---

Hot Reload

Chvor watches ~/.chvor/config.json for changes. When you save the file, the server:

1. Stops any MCP servers that were removed or changed.
2. Starts any new or modified MCP servers.
3. Logs the result.

You do not need to restart Chvor when adding or removing tools. Watch the server logs to confirm:

[mcp] Reloading config...
[mcp] Started: filesystem (3 tools available)
[mcp] Started: web-search (1 tool available)

If a server fails to start, you will see:

[mcp] Failed to start database: spawn uvx ENOENT

This usually means the command (uvx in this case) is not installed or not in your PATH.

---

Example: Filesystem + Web Search

A practical setup that gives your agent the ability to read local files and search the web:

1. Get a Brave Search API key

Sign up at brave.com/search/api — the free tier includes 2,000 queries/month.

2. Configure both servers

Edit ~/.chvor/config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxxxxxxxxxx"
      }
    }
  }
}

3. Create a skill that uses both

name: project-researcher
description: Answers questions about your projects using local files and web search.

trigger:
  patterns:
    - "look at my project *"
    - "what does * do in my code"

prompt: |
  You are a helpful assistant with access to the user's project files
  and web search. Use the filesystem tool to read relevant source files.
  Use web search to find documentation or Stack Overflow answers when needed.
  Always ground your answers in actual code or authoritative sources.

tools:
  - filesystem
  - web-search

4. Test it

Send a message like “look at my project and explain the main entry point” in the Brain Canvas. The agent will use the filesystem tool to list and read files, then explain what it finds.

---

Writing a Custom MCP Server

If the existing MCP servers do not cover your use case, you can write your own. An MCP server is a process that communicates over stdin/stdout using the MCP protocol.

Minimal example in TypeScript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-custom-tool", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "greet",
      description: "Returns a greeting for the given name.",
      inputSchema: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name to greet" }
        },
        required: ["name"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "greet") {
    const name = request.params.arguments?.name ?? "World";
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }]
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

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

Register it in Chvor

{
  "mcpServers": {
    "my-custom-tool": {
      "command": "node",
      "args": ["/path/to/my-custom-tool/index.js"]
    }
  }
}

For a full guide on writing MCP servers, see the MCP documentation.

---

Troubleshooting

Problem	Cause	Solution
spawn npx ENOENT	Node.js/npm not in PATH	Ensure Node.js is installed and npx is available in your shell
Tool not showing in skill	Tool name mismatch	The name in mcpServers must match the name in your skill’s tools list
ETIMEOUT on tool call	MCP server crashed or hung	Check server logs; restart Chvor if needed
Permission denied	Filesystem scoping	Add the directory to the filesystem server’s args list

---

Next Steps

• Creating Custom Skills — write skills that use the tools you just connected.
• Skill Schema Reference — full specification of the tools field.
• Registry Overview — browse pre-built tool configurations.