Tools (MCP)

Give agents superpowers with MCP servers

Tools let agents interact with the world - search the web, read files, query databases, call APIs. MUXI uses the Model Context Protocol (MCP) for tool integration.

Add Your First Tool

  1. Create the MCP config file

    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. Set the secret

    muxi secrets set BRAVE_API_KEY

  3. Test it

    All agents in the formation automatically have access to MCP servers defined in mcp/*.afs.

    muxi dev
# Then: "Search for recent AI news"

MCP Server Types

Command-based (Local)

Runs a local process:

# mcp/local-tool.afs
schema: "1.0.0"
id: local-tool
type: command
command: npx
args: ["-y", "@modelcontextprotocol/server-brave-search"]
timeout_seconds: 30
auth:
  type: env
  API_KEY: "${{ secrets.API_KEY }}"

HTTP-based (Remote)

Calls a remote MCP server:

# mcp/remote-tool.afs
schema: "1.0.0"
id: remote-tool
type: http
endpoint: "https://api.example.com/mcp"
timeout_seconds: 30
auth:
  type: bearer
  token: "${{ secrets.API_TOKEN }}"

MCP File Fields

Required Fields

Field Type Description
schema string Schema version ("1.0.0")
id string Unique identifier
description string What this MCP server does
type enum command (stdio) or http

Command Type Fields

Field Type Description
command string Command to execute (npx, python, node)
args array Command arguments
env object Environment variables for the command
cwd string Working directory for the command

HTTP Type Fields

Field Type Description
endpoint string HTTP endpoint URL
protocol enum http or https
method enum GET, POST, PUT, DELETE (default: POST)
headers object Additional HTTP headers

Common Optional Fields

Field Type Default Description
active bool true Enable/disable this server
timeout_seconds int - Request timeout
retry_attempts int - Number of retries (0-10)

Capabilities

capabilities:
  tools: ["list_repos", "create_issue"]  # Tool names provided
  streaming: false                        # Supports streaming?
  async: false                            # Supports async?

Health Check (HTTP only)

health_check:
  enabled: true
  endpoint: "/health"
  interval_seconds: 60
  timeout_seconds: 5

Rate Limiting

rate_limiting:
  requests_per_minute: 60
  requests_per_hour: 1000
  burst_limit: 10

Metadata

metadata:
  version: "1.0.0"
  author: "Your Team"
  homepage: "https://example.com"
  documentation: "https://docs.example.com"
  tags: ["search", "web"]

Popular MCP Servers

Server What It Does Type
@modelcontextprotocol/server-brave-search Web search command
@modelcontextprotocol/server-filesystem Read/write files command
@modelcontextprotocol/server-github GitHub API command
@modelcontextprotocol/server-postgres PostgreSQL command
@modelcontextprotocol/server-sqlite SQLite command

Configuration Examples

Web Search

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

File System

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

Always restrict file access to specific directories in the args.

Database

# mcp/postgres.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/sqlite.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 }}"

Formation-Level MCP Settings

Configure global MCP behavior in formation.afs:

mcp:
  default_timeout_seconds: 30
  max_tool_iterations: 10
  max_tool_calls: 50
  max_repeated_errors: 3

Agent-Specific Tools

Prefer per-agent tools. Defining tools per-agent improves Overlord's agent selection and each agent's tool selection. Use global MCP servers only for tools ALL agents need.

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 topics

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 assistant

system_message: |
  You are a software developer.
  Your job is to write, review, and debug code...

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

Authentication Types

Environment Variables

auth:
  type: env
  API_KEY: "${{ secrets.API_KEY }}"
  DEBUG: "true"

Bearer Token

auth:
  type: bearer
  token: "${{ secrets.TOKEN }}"

Basic Auth

auth:
  type: basic
  username: "${{ secrets.USERNAME }}"
  password: "${{ secrets.PASSWORD }}"

API Key Header

auth:
  type: api_key
  header: "X-API-Key"
  key: "${{ secrets.API_KEY }}"

Troubleshooting

Tool Not Available

Verify the server is installed:

npx @modelcontextprotocol/server-brave-search --version
Connection Failed

Check server logs:

muxi logs --mcp

Common issues:

  • Invalid API key
  • Network connectivity
  • Server not running

Next Steps

Home Registry Documentation Star on GitHub
Get priority support