Add Tools (MCP)

Give your agents superpowers

Tools let agents interact with the real world - search the web, access files, query databases, call APIs. MUXI uses the Model Context Protocol (MCP) standard for tools.

This guide uses Brave Search as an example. You can use any MCP-compatible tool server. The patterns shown here apply to all MCP integrations.

MCP Protocol Support

MUXI supports both MCP transport protocols:

Protocol Use Case Example
stdio (command) Local tools, CLI wrappers npx @modelcontextprotocol/server-brave-search
HTTP (sse) Remote services, hosted tools https://mcp.example.com/tools

Both protocols support authentication via environment variables, headers, or OAuth.

→ Tools Schema Reference - Full configuration options for both protocols

What You'll Build

By the end of this guide, your agent will:

  1. Detect when you need information
  2. Search the web using Brave Search
  3. Synthesize results into a response

Prerequisites

  • A working formation (muxi dev succeeds)
  • For this example: Brave Search API key (get one free)

Test tools in isolation first. Before adding a new MCP server to your formation, run it standalone and verify it works with direct calls. This saves debugging time.

  1. Create the MCP Configuration

    cd my-formation
mkdir -p mcp

    Create mcp/web-search.afs:

    schema: "1.0.0"
id: web-search
description: Brave web search
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-brave-search"]
auth:
  type: env
  BRAVE_API_KEY: "${{ secrets.BRAVE_API_KEY }}"

  2. Add the Secret

    muxi secrets set BRAVE_API_KEY

    Enter your Brave API key when prompted.

  3. Update Formation

    Update your formation.afs:

    Formation file:

    # formation.afs
schema: "1.0.0"
id: my-assistant
description: Assistant with web search

llm:
  api_keys:
    openai: "${{ secrets.OPENAI_API_KEY }}"
  models:
    - text: "openai/gpt-4o"

agents: []  # Auto-discovered from agents/

    Agent file:

    # agents/assistant.afs
schema: "1.0.0"
id: assistant
name: Assistant
description: Assistant with web search

system_message: |
  You are a helpful assistant with web search capabilities.
  Use web search when you need current information.

  4. Test It

    muxi dev

    Then try:

    You: What are the latest AI developments this week?
Assistant: [searches the web] Based on my search, here are the latest developments...

How It Works

sequenceDiagram
    participant U as User
    participant A as Agent
    participant T as Web Search Tool
    participant W as Brave API

    U->>A: "What's new in AI?"
    A->>A: Decides search is needed
    A->>T: search("AI news")
    T->>W: API call
    W-->>T: Search results
    T-->>A: Formatted results
    A->>U: Synthesized response

The agent decides when to use tools based on the request. You don't need to explicitly ask it to search.

Popular Tools to Add

File System

# mcp/filesystem.afs
schema: "1.0.0"
id: filesystem
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]

Database

# mcp/database.afs
schema: "1.0.0"
id: database
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-postgres"]
auth:
  type: env
  DATABASE_URL: "${{ secrets.DATABASE_URL }}"
# mcp/database.afs
schema: "1.0.0"
id: database
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-sqlite", "--db", "./data/app.db"]

GitHub

# mcp/github.afs
schema: "1.0.0"
id: github
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
auth:
  type: env
  GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

Agent-Specific Tools

Prefer per-agent tools over global tools. This produces better results:

  • Overlord routes smarter - Uses tool capabilities to pick the right agent
  • Agents choose tools better - Only see tools relevant to their role

Reserve global MCP servers (in mcp/*.afs) for tools that genuinely apply to ALL agents.

Formation-level MCP servers (in mcp/*.afs) are available to all agents. For agent-specific tools, define mcp_servers in the agent file:

# agents/researcher.afs
schema: "1.0.0"
id: researcher
name: Researcher
description: Research and gather information

system_message: |
  You are a research specialist.
  Your job is to gather accurate information...

mcp_servers:
  - id: web-search
    description: Web search
    type: command
    command: npx
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
# agents/developer.afs
schema: "1.0.0"
id: developer
name: Developer
description: Code and database work

system_message: |
  You are a software developer.
  Your job is to write code and manage data...

mcp_servers:
  - id: filesystem
    description: File access
    type: command
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem"]

Troubleshooting

Tool not appearing
  1. Check the MCP file exists in mcp/ directory
  2. Check the agent has the MCP ID in its mcps list
  3. Restart with muxi dev
API errors

Check your API key:

muxi secrets get BRAVE_API_KEY

Verify it's valid by testing directly:

curl "https://api.search.brave.com/res/v1/web/search?q=test" \
  -H "X-Subscription-Token: YOUR_KEY"
Tool timing out

Increase timeout in the MCP config:

timeout_seconds: 60

Next Steps

Home Registry Documentation Star on GitHub
Get priority support