> ## Documentation Index
> Fetch the complete documentation index at: https://usemci.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Toolsets

> Learn how to organize, share, and filter tool collections using MCI toolsets for better project structure

# MCI Toolsets

Toolsets are collections of tools organized into reusable, shareable files. They provide a way to structure tools by domain, share them across projects, and apply filtering to control which tools are loaded in main `mci.json` file.

## What are Toolsets?

A **toolset** is a separate MCI schema file that contains a collection of related tools. Unlike main entry files, toolsets:

* Are stored in a library directory (default: `./mci`)
* Contain only tool definitions (no top-level configuration)
* Can be shared across multiple projects
* Support schema-level filtering when loaded

## Toolsets vs Main Schema Files

### Main Entry File (mci.json)

```json theme={null}
{
  "schemaVersion": "1.0",
  "metadata": {
    "name": "My Application"
  },
  "libraryDir": "./mci",
  "directoryAllowList": ["/data"],
  "enableAnyPaths": false,
  "toolsets": [{ "name": "weather" }, { "name": "database" }],
  "tools": [
    {
      "name": "main_tool",
      "execution": {
        "type": "text",
        "text": "Main tool output"
      }
    }
  ]
}
```

**Can contain:**

* `schemaVersion` (required)
* `metadata` (optional)
* `tools` (optional)
* `toolsets` (optional)
* `mcp_servers` (optional)
* `libraryDir` (optional)
* `directoryAllowList` (optional)
* `enableAnyPaths` (optional)

### Toolset File (./mci/weather.mci.json)

```json theme={null}
{
  "schemaVersion": "1.0",
  "metadata": {
    "name": "Weather Toolset",
    "description": "Tools for weather information",
    "version": "1.0.0"
  },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather",
      "tags": ["weather", "read"],
      "execution": {
        "type": "http",
        "method": "GET",
        "url": "https://api.weather.com/current",
        "params": {
          "location": "{{props.location}}"
        }
      }
    },
    {
      "name": "get_forecast",
      "description": "Get weather forecast",
      "tags": ["weather", "read"],
      "execution": {
        "type": "http",
        "method": "GET",
        "url": "https://api.weather.com/forecast",
        "params": {
          "location": "{{props.location}}"
        }
      }
    }
  ]
}
```

**Can contain:**

* `schemaVersion` (required)
* `metadata` (optional - for documentation only)
* `tools` (required)

**Cannot contain:**

* `toolsets`
* `mcp_servers`
* `libraryDir`
* `directoryAllowList`
* `enableAnyPaths`

**Key Differences:**

| Feature                  | Main Entry File       | Toolset File           |
| ------------------------ | --------------------- | ---------------------- |
| Location                 | Project root          | `./mci` directory      |
| Purpose                  | Configure application | Define tool collection |
| Can Define tools         | ✓ Yes                 | ✗ Yes                  |
| Can reference toolsets   | ✓ Yes                 | ✗ No                   |
| Can register MCP servers | ✓ Yes                 | ✗ No                   |
| Can set security configs | ✓ Yes                 | ✗ No                   |
| "tools" required         | ✗ No                  | ✓ Yes                  |

## Creating Toolsets

### Basic Toolset

Create a file in your toolsets directory:

**./mci/github.mci.json:**

```json theme={null}
{
  "schemaVersion": "1.0",
  "metadata": {
    "name": "GitHub Tools",
    "description": "Tools for GitHub API integration",
    "version": "1.0.0",
    "authors": ["DevOps Team"]
  },
  "tools": [
    {
      "name": "create_issue",
      "description": "Create a GitHub issue",
      "tags": ["github", "write"],
      "inputSchema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "body": { "type": "string" },
          "repo": { "type": "string" }
        },
        "required": ["title", "repo"]
      },
      "execution": {
        "type": "http",
        "method": "POST",
        "url": "https://api.github.com/repos/{{props.repo}}/issues",
        "auth": {
          "type": "bearer",
          "token": "{{env.GITHUB_TOKEN}}"
        },
        "headers": {
          "Accept": "application/vnd.github+json"
        },
        "body": {
          "type": "json",
          "content": {
            "title": "{{props.title}}",
            "body": "{{props.body}}"
          }
        }
      }
    },
    {
      "name": "list_repos",
      "description": "List user repositories",
      "tags": ["github", "read"],
      "execution": {
        "type": "http",
        "method": "GET",
        "url": "https://api.github.com/user/repos",
        "auth": {
          "type": "bearer",
          "token": "{{env.GITHUB_TOKEN}}"
        }
      }
    }
  ]
}
```

### Domain-Organized Toolsets

Organize toolsets by domain or purpose:

**./mci/database.mci.json:**

```json theme={null}
{
  "schemaVersion": "1.0",
  "metadata": {
    "name": "Database Tools"
  },
  "tools": [
    {
      "name": "query_users",
      "tags": ["database", "read"],
      // ...
      "execution": {
        "type": "cli",
        "command": "psql",
        "args": ["-c", "SELECT * FROM users;"]
      }
    },
    {
      "name": "backup_database",
      "tags": ["database", "write", "admin"],
      // ...
      "execution": {
        "type": "cli",
        "command": "pg_dump",
        "args": ["-f", "{{props.backup_file}}"]
      }
    }
  ]
}
```

## Loading Toolsets

Toolsets are loaded in the main schema file using the `toolsets` field.

### Basic Loading

```json theme={null}
{
  "schemaVersion": "1.0",
  "toolsets": ["weather", "github", { "name": "database" }]
}
```

### With Custom Library Directory

```json theme={null}
{
  "schemaVersion": "1.0",
  "libraryDir": "./toolsets",
  "toolsets": ["weather"]
}
```

## Toolset Resolving

MCI resolves toolset names using a flexible system that supports both files and directories.

### Resolution Order

When you reference a toolset by name (e.g., `"weather"`), MCI looks for it in this order:

1. **Directory**: `{libraryDir}/weather/` - If found, loads all `.mci.json` files in the directory
2. **Direct File**: `{libraryDir}/weather`
3. **With Extension**: `{libraryDir}/weather.mci.json`
4. **YAML Files**: Also checks `.mci.yaml` and `.mci.yml`, when extension not specified

### File-Based Toolset

```
mci/
└── weather.mci.json
```

Reference:

```json theme={null}
{ "toolsets": [{ "name": "weather" }] }
```

Resolves to: `./mci/weather.mci.json`

### Directory-Based Toolset

```
mci/
└── github/
    ├── issues.mci.json
    ├── prs.mci.json
    └── repos.mci.json
```

You can Reference:

```json theme={null}
{ "toolsets": [{ "name": "github" }] }
```

Resolves to: All `.mci.json` files in `./mci/github/`

And in some main files, reference only issues:

```json theme={null}
{ "toolsets": [{ "name": "github/issues.mci.json" }] }
```

### Nested Directories

```
mci/
└── apis/
    ├── github/
    │   ├── issues.mci.json
    │   └── prs.mci.json
    └── weather.mci.json
```

Reference:

```json theme={null}
{
  "toolsets": [{ "name": "apis/github" }, { "name": "apis/weather" }]
}
```

### Multiple Files in Directory

When loading from a directory, all `.mci.json` files are loaded:

**./mci/monitoring/status.mci.json:**

```json theme={null}
{
  "schemaVersion": "1.0",
  "tools": [
    {"name": "check_health", "execution": {...}}
  ]
}
```

**./mci/monitoring/metrics.mci.json:**

```json theme={null}
{
  "schemaVersion": "1.0",
  "tools": [
    {"name": "get_metrics", "execution": {...}}
  ]
}
```

**Loading:**

```json theme={null}
{ "toolsets": [{ "name": "monitoring" }] }
```

**Result**: Both `check_health` and `get_metrics` tools are loaded.

**Important Notes:**

* Only tools are merged from directory toolsets
* Metadata is NOT merged (used for documentation only)
* All files must use the same `schemaVersion`
* Schema version mismatch will raise an error

## Schema-Level Filtering

Apply filters when loading toolsets to control which tools are registered.

### Filter Types

| Filter Type   | Description                           | Example                       |
| ------------- | ------------------------------------- | ----------------------------- |
| `only`        | Include only specified tool names     | `"get_weather, get_forecast"` |
| `except`      | Exclude specified tool names          | `"delete_user, drop_table"`   |
| `tags`        | Include only tools with matching tags | `"read, search"`              |
| `withoutTags` | Exclude tools with matching tags      | `"write, delete"`             |

### Examples

**Include Only Specific Tools:**

```json theme={null}
{
  "toolsets": [
    {
      "name": "weather",
      "filter": "only",
      "filterValue": "get_weather, get_forecast"
    }
  ]
}
```

Result: Only `get_weather` and `get_forecast` tools are loaded from the weather toolset.

**Exclude Dangerous Tools:**

```json theme={null}
{
  "toolsets": [
    {
      "name": "database",
      "filter": "except",
      "filterValue": "drop_table, delete_all, truncate_table"
    }
  ]
}
```

Result: All database tools except the excluded ones are loaded.

**Filter by Tags (Include):**

```json theme={null}
{
  "toolsets": [
    {
      "name": "github",
      "filter": "tags",
      "filterValue": "read, search"
    }
  ]
}
```

Result: Only tools tagged with `"read"` or `"search"` are loaded.

**Filter by Tags (Exclude):**

```json theme={null}
{
  "toolsets": [
    {
      "name": "github",
      "filter": "withoutTags",
      "filterValue": "write, delete, admin"
    }
  ]
}
```

Result: All tools except those tagged with `"write"`, `"delete"`, or `"admin"` are loaded.

### Combining Multiple Toolsets with Different Filters

```json theme={null}
{
  "schemaVersion": "1.0",
  "toolsets": [
    {
      "name": "weather",
      "filter": "only",
      "filterValue": "get_weather"
    },
    {
      "name": "github",
      "filter": "withoutTags",
      "filterValue": "admin"
    },
    {
      "name": "database",
      "filter": "tags",
      "filterValue": "read"
    },
    {
      "name": "utilities"
    }
  ]
}
```

## Sharing Toolsets

Toolsets are designed to be shared across projects and teams.

### Sharing Within Organization

**Project Structure:**

```
organization/
├── shared-toolsets/
│   ├── github.mci.json
│   ├── slack.mci.json
│   └── monitoring.mci.json
├── project-a/
│   ├── mci.json
│   └── mci/ -> ../shared-toolsets/
└── project-b/
    ├── mci.json
    └── mci/ -> ../shared-toolsets/
```

**Using Symlinks:**

```bash theme={null}
# In project-a
ln -s ../shared-toolsets ./mci

# In project-b
ln -s ../shared-toolsets ./mci
```

### Sharing via Git Submodules

```bash theme={null}
# Add shared toolsets as submodule
git submodule add https://github.com/org/mci-toolsets.git ./mci

# Update toolsets
git submodule update --remote
```

### Sharing via Package Manager

**npm Example:**

```bash theme={null}
# Publish toolsets as npm package
npm publish @company/mci-toolsets

# Install in project
npm install @company/mci-toolsets
```

**In your schema:**

```json theme={null}
{
  "libraryDir": "./node_modules/@company/mci-toolsets",
  "toolsets": [{ "name": "github" }, { "name": "slack" }]
}
```

## Best Practices

### 1. Organize by Domain

```
mci/
├── apis/
│   ├── github.mci.json
│   ├── slack.mci.json
│   └── weather.mci.json
├── databases/
│   ├── postgres.mci.json
│   └── redis.mci.json
└── utilities/
    ├── logging.mci.json
    └── monitoring.mci.json
```

### 2. Use Tags for Categorization

```json theme={null}
{
  "tools": [
    {
      "name": "read_data",
      // ...
      "tags": ["database", "read", "safe"]
    },
    {
      "name": "delete_data",
      // ...
      "tags": ["database", "write", "destructive"]
    }
  ]
}
```

Then filter by tags:

```json theme={null}
{
  "toolsets": [
    {
      "name": "database",
      "filter": "tags",
      "filterValue": "read, safe"
    }
  ]
}
```

### 3. Document Toolsets

```json theme={null}
{
  "metadata": {
    "name": "GitHub API Tools",
    "description": "Complete GitHub API integration toolset. Requires GITHUB_TOKEN environment variable.",
    "version": "2.1.0",
    "authors": ["DevOps Team", "Platform Team"],
    "license": "MIT"
  }
}
```

### 4. Version Toolsets

Use semantic versioning in metadata:

```json theme={null}
{
  "metadata": {
    "version": "2.1.0"
  }
}
```

### 5. Keep Toolsets Focused

Each toolset should focus on a single domain:

✓ Good:

* `github.mci.json` - GitHub API tools
* `slack.mci.json` - Slack API tools
* `monitoring.mci.json` - Monitoring tools

✗ Avoid:

* `misc.mci.json` - Mixed unrelated tools
* `everything.mci.json` - Too broad

## Summary

* **Toolsets** organize tools into reusable collections
* **Main Schema Files** configure applications and reference toolsets
* **Toolset Files** contain only tool definitions
* **Resolving** supports both files and directories
* **Filtering** controls which tools are loaded from toolsets
* **Sharing** enables reuse across projects and teams

Toolsets make it easy to organize, maintain, and share tools across your organization.