Tool Configuration Overview

Complete guide to defining and configuring MCP tools in Archia.

Configuration Options

Archia supports configuring tools in two ways:

1. User Tools: Custom tools defined as TOML files in ~/.archia/tools/user/
2. Marketplace Tools: Pre-packaged tools installed from the Archia marketplace

Tool Storage Location

Tools are stored in the tools directory:

• Production: ~/.archia/tools/
• Development: ~/.archia_dev/tools/

Directory Structure

~/.archia/tools/
├── user/                           # User-created tools
│   ├── my-custom-tool/
│   │   └── tool.toml
│   └── another-tool/
│       └── tool.toml
└── {organization}/                 # Marketplace tools
    └── {tool-name}/
        └── {version}/
            └── tool.toml

Tool Configuration Format

Each tool is defined in a tool.toml file with the following structure:

Basic Tool Definition

# ~/.archia/tools/user/my-tool/tool.toml

identifier = "my-tool"
name = "My Custom Tool"
description = "A custom MCP tool for specific tasks"
provider = "My Organization"
version = "1.0.0"

Local Tool (STDIO Transport)

Local tools run as processes on the same machine using STDIO communication:

identifier = "local-database"
name = "Local Database Tool"
description = "SQLite database access via MCP"
provider = "Archia"
version = "1.0.0"
type = "mcp"

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

[local.env]
LOG_LEVEL = "info"
MAX_CONNECTIONS = "10"

Remote Tool (HTTP/SSE Transport)

Remote tools connect to external MCP servers over HTTP:

identifier = "remote-api"
name = "Remote API Tool"
description = "Connect to external API service"
provider = "External Provider"
version = "1.0.0"
type = "mcp"

[remote]
url = "https://api.example.com/mcp"
transport = "streaming_http"    # or "sse"
timeout_secs = 60
headers = { "X-API-Key" = "your-api-key" }

Configuration Fields Reference

Top-Level Fields

Local Configuration ([local])

Remote Configuration ([remote])

Authentication Types

No Authentication

[remote]
url = "https://public-api.example.com/mcp"
transport = "streaming_http"
auth_type = "none"

Bearer Token Authentication

[remote]
url = "https://api.example.com/mcp"
transport = "streaming_http"
auth_type = "bearer"
auth_token = "your-api-key-here"

OAuth 2.1 Authentication

[remote]
url = "https://oauth-api.example.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"    # Optional for PKCE

Managing Tools

Via REST API

# List all tools
curl http://localhost:8080/v1/tool

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

# Get specific tool
curl http://localhost:8080/v1/tool/my-tool

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

# Update tool
curl -X PUT http://localhost:8080/v1/tool/new-tool \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "local": {
      "cmd": "my-mcp-server",
      "args": ["--config", "/new/path"],
      "timeout_secs": 60
    }
  }'

# Delete tool
curl -X DELETE http://localhost:8080/v1/tool/new-tool

Example Configurations

File System Access Tool

# ~/.archia/tools/user/filesystem/tool.toml

identifier = "filesystem"
name = "File System Access"
description = "Read and write files on the local system"
provider = "Archia"
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"

GitHub Integration Tool

# ~/.archia/tools/user/github/tool.toml

identifier = "github"
name = "GitHub Integration"
description = "Interact with GitHub repositories"
provider = "Archia"
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 Database Service

# ~/.archia/tools/user/cloud-db/tool.toml

identifier = "cloud-db"
name = "Cloud Database"
description = "Access cloud-hosted database service"
provider = "Cloud Provider"
version = "1.0.0"
type = "mcp"

[remote]
url = "https://db.cloudprovider.com/mcp/v1"
transport = "streaming_http"
auth_type = "bearer"
auth_token = "${CLOUD_DB_API_KEY}"
timeout_secs = 120

OAuth-Protected API

# ~/.archia/tools/user/protected-api/tool.toml

identifier = "protected-api"
name = "Protected API Service"
description = "OAuth-protected external API"
provider = "Third Party"
version = "1.0.0"
type = "mcp"

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

Connecting Tools to Agents

Once tools are configured, grant agents access via the mcp_tools field in agent configuration:

# ~/.archia/agents/developer.toml

name = "developer"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
description = "Development assistant with tool access"

[mcp_tools]
filesystem = ["read_file", "write_file", "list_directory"]
github = ["list_repos", "get_file", "create_issue"]
cloud-db = null    # All tools

Best Practices

1. Use Environment Variables for Secrets

Never hardcode API keys or tokens:

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

[remote]
auth_token = "${SERVICE_TOKEN}"

2. Set Appropriate Timeouts

Adjust timeouts based on expected operation duration:

[local]
timeout_secs = 30    # Fast operations

[remote]
timeout_secs = 120   # Network latency + processing

3. Constrain File Access

Limit filesystem tools to specific directories:

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

4. Version Your Tools

Use semantic versioning for tracking:

version = "1.2.3"

Troubleshooting

Tool Won’t Start

1. Verify the command exists and is executable:

   which mcp-sqlite
   

2. Check environment variables are set:

   echo $MY_API_KEY
   

3. Test the tool manually:

   mcp-sqlite --database /path/to/db
   

Connection Refused (Remote Tools)

1. Verify the URL is correct and accessible
2. Check authentication credentials
3. Ensure network/firewall allows the connection

Timeout Errors

Increase the timeout_secs value for slow operations or network latency.

Next Steps

• Agent Configuration → - Configure agents to use tools
• MCP Authentication → - Deep dive into OAuth and authentication
• REST API Reference → - Complete API documentation