Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP Tools Setup

Configure MCP (Model Context Protocol) tools to give your agents capabilities like database access, file operations, and external API integration.

Overview

MCP tools are configured as TOML files and stored in the tools directory:

  • User tools: ~/.archia/tools/user/{tool-name}/tool.toml
  • Marketplace tools: ~/.archia/tools/{org}/{tool}/{version}/tool.toml

Once configured, tools can be assigned to agents via the mcp_tools field in agent configuration.

Quick Start

Step 1: Create a Tool

Create a directory for your tool:

mkdir -p ~/.archia/tools/user/database

Create the tool configuration:

vim ~/.archia/tools/user/database/tool.toml

identifier = "database"
name = "Database Tool"
description = "SQLite database access via MCP"
version = "1.0.0"
type = "mcp"

[local]
cmd = "mcp-sqlite"
args = ["--database", "/data/mydata.db"]
timeout_secs = 30

Step 2: Grant Agent Access

Update your agent configuration to use the tool:

# ~/.archia/agents/analyst.toml
name = "analyst"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
system_prompt = "You are a data analyst with database access."

[mcp_tools]
database = null  # Grant access to all tools from 'database' MCP

Step 3: Test

curl -X POST http://localhost:8080/v1/chat/1/message \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "analyst",
    "content": [{"type": "text", "text": "List all tables in the database"}]
  }'

Local Tools (STDIO Transport)

Local tools run as processes on the same machine, communicating via STDIO.

Basic Local Tool

# ~/.archia/tools/user/sqlite/tool.toml
identifier = "sqlite"
name = "SQLite Database"
description = "Query SQLite databases"
version = "1.0.0"
type = "mcp"

[local]
cmd = "mcp-sqlite"
args = ["--database", "/path/to/database.db"]
timeout_secs = 30

NPX-Based Tools

Many MCP servers are available via npm:

# ~/.archia/tools/user/filesystem/tool.toml
identifier = "filesystem"
name = "File System Access"
description = "Read and write files"
version = "1.0.0"
type = "mcp"

[local]
cmd = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@latest"]
timeout_secs = 30

[local.env]
ALLOWED_PATHS = "/home/user/documents,/home/user/projects"

Environment Variables

Pass configuration via environment variables:

# ~/.archia/tools/user/github/tool.toml
identifier = "github"
name = "GitHub Integration"
description = "Interact with GitHub repositories"
version = "1.0.0"
type = "mcp"

[local]
cmd = "npx"
args = ["-y", "@modelcontextprotocol/server-github@latest"]
timeout_secs = 60

[local.env]
GITHUB_TOKEN = "${GITHUB_TOKEN}"

Remote Tools (HTTP Transport)

Remote tools connect to external MCP servers over HTTP.

Bearer Token Authentication

# ~/.archia/tools/user/cloud-api/tool.toml
identifier = "cloud-api"
name = "Cloud API Service"
description = "Access cloud-hosted API"
version = "1.0.0"
type = "mcp"

[remote]
url = "https://api.example.com/mcp"
transport = "streaming_http"
auth_type = "bearer"
auth_token = "${CLOUD_API_KEY}"
timeout_secs = 60

OAuth Authentication

# ~/.archia/tools/user/oauth-service/tool.toml
identifier = "oauth-service"
name = "OAuth Protected Service"
description = "Service requiring OAuth authentication"
version = "1.0.0"
type = "mcp"

[remote]
url = "https://api.service.com/mcp"
transport = "streaming_http"
auth_type = "oauth"
oauth_scopes = ["mcp", "read", "write"]
oauth_client_id = "your-client-id"
oauth_client_secret = "your-client-secret"
timeout_secs = 90

Granting Tool Access to Agents

All Tools from an MCP

Grant access to all tools provided by an MCP:

# ~/.archia/agents/power-user.toml
name = "power-user"
model_name = "claude-sonnet-4-5-20250929"
enabled = true

[mcp_tools]
filesystem = null    # null = all tools
database = []        # empty array = all tools

Specific Tools Only

Grant access to specific tools for better security:

# ~/.archia/agents/reader.toml
name = "reader"
model_name = "claude-haiku-4-5-20251001"
enabled = true

[mcp_tools]
filesystem = ["read_file", "list_directory"]  # Read-only
database = ["query", "list_tables"]           # No write access

Multiple MCPs

Agents can access multiple MCPs:

# ~/.archia/agents/developer.toml
name = "developer"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
system_prompt = "You are a development assistant with access to code, git, and shell."

[mcp_tools]
filesystem = ["read_file", "write_file", "list_directory"]
github = ["list_repos", "get_file", "create_issue"]
shell = ["run_command"]

Managing Tools via API

List Tools

# All tools
curl http://localhost:8080/v1/tool

# User tools only
curl "http://localhost:8080/v1/tool?user_only=true"

Create Tool

curl -X POST http://localhost:8080/v1/tool \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "my-tool",
    "name": "My Tool",
    "description": "A custom MCP tool",
    "local": {
      "cmd": "my-mcp-server",
      "args": ["--config", "/path/to/config"],
      "timeout_secs": 30
    }
  }'

Delete Tool

curl -X DELETE http://localhost:8080/v1/tool/my-tool

Real-World Examples

Coding Assistant Setup

# Tool: GitHub access
# ~/.archia/tools/user/git/tool.toml
identifier = "git"
name = "Git Repository"
version = "1.0.0"
type = "mcp"

[local]
cmd = "npx"
args = ["-y", "@modelcontextprotocol/server-github@latest"]
timeout_secs = 60

[local.env]
GITHUB_TOKEN = "${GITHUB_TOKEN}"

# Tool: Local filesystem
# ~/.archia/tools/user/code/tool.toml
identifier = "code"
name = "Code Files"
version = "1.0.0"
type = "mcp"

[local]
cmd = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@latest"]
timeout_secs = 30

[local.env]
ALLOWED_PATHS = "/workspace"

# Agent: Coding assistant
# ~/.archia/agents/coder.toml
name = "coder"
model_name = "claude-sonnet-4-5-20250929"
enabled = true

system_prompt = """
You are an expert software engineer.
You can:
- Read and write code files
- Execute git commands
Always explain your actions and ask for confirmation before making changes.
"""

[mcp_tools]
git = null
code = ["read_file", "write_file", "list_directory"]

Data Analysis Setup

# Tool: Database
# ~/.archia/tools/user/analytics-db/tool.toml
identifier = "analytics-db"
name = "Analytics Database"
version = "1.0.0"
type = "mcp"

[local]
cmd = "mcp-postgres"
args = ["--connection-string", "${DATABASE_URL}"]
timeout_secs = 120

[local.env]
DATABASE_URL = "${ANALYTICS_DB_URL}"

# Agent: Data analyst
# ~/.archia/agents/analyst.toml
name = "analyst"
model_name = "claude-sonnet-4-5-20250929"
enabled = true

system_prompt = """
You are an expert data analyst. You can query the analytics database to:
- Generate reports
- Identify trends
- Answer business questions

Always use efficient queries and explain your analysis.
"""

[mcp_tools]
analytics-db = ["query", "list_tables", "describe_table"]

Security Best Practices

1. Limit Tool Access

Grant agents only the tools they need:

[mcp_tools]
database = ["query"]  # Read-only, no write operations

2. Use Environment Variables

Never hardcode secrets:

[local.env]
API_KEY = "${MY_API_KEY}"
DATABASE_PASSWORD = "${DB_PASS}"

3. Restrict File Paths

Limit filesystem access:

[local.env]
ALLOWED_PATHS = "/safe/directory/only"
READONLY = "true"

4. Set Appropriate Timeouts

Prevent runaway processes:

[local]
timeout_secs = 30  # Fail fast

Troubleshooting

Tool Won’t Start

  1. Check if the command exists:

    which mcp-sqlite

  2. Verify npx packages:

    npx -y @modelcontextprotocol/server-filesystem --help

  3. Check environment variables:

    echo $GITHUB_TOKEN

Permission Denied

  • Ensure the executable has correct permissions
  • Check file path permissions for filesystem tools

Timeout Errors

Increase timeout for slow operations:

[local]
timeout_secs = 120

Connection Refused (Remote)

  • Verify URL is correct and accessible
  • Check authentication credentials
  • Ensure firewall allows the connection

Next Steps