toolscript

Toolscript

Token-efficient tool usage via MCP Code Mode: Execute TypeScript code that calls MCP tools with full type safety.

Toolscript is a lightweight CLI tool and Claude Code plugin that enables LLMs to write TypeScript code calling MCP (Model Context Protocol) tools. It provides automatic type generation, sandboxed execution, and seamless Claude Code integration.

Features

• Type-Safe MCP Access: Automatic TypeScript type generation from MCP tool schemas
• Semantic Tool Search: AI-powered search using embeddings + fuzzy matching for tool discovery
• Sandboxed Execution: Secure Deno sandbox with minimal permissions
• Tool Filtering: Only expose the tools from a server that you really need
• Claude Plugin: Automatic gateway lifecycle management and hooks that auto-suggest relevant skills & tools

Why should I use this?

The idea of using MCP tools as code instead of direct LLM calls was described in popular blog posts from Anthropic and CloudFlare. The main problems with the current protocol implementations are:

1. MCP Context Bloat: All MCP tools with their descriptions and schemas are loaded into the system context, taking up significant space of the valuable context window and costing you money on each request. The more MCP tools you add to your agent, the more bloated it will get.
2. Tool Results Become Context: When the LLM chains multiple tool calls together to fulfill a more advanced request, all intermediate tool results are passed back to the model, adding more tokens to the context. Large context sizes from multiple heavy tool calls can make the LLM more likely to make mistakes when copying data between the different tool calls.

Toolscript solves these issues by:

1. Only exposing the tool definitions needed to the LLM through a search interface, leading to minimal context waste from system instructions
2. Allowing deterministic chaining of tool calls, with data passed directly between the calls, limiting the output processed by the LLM to only the relevant results

The goal of the project is to enable agents to be more cost-efficient and accurate at complex tasks.

Quick Start

Pre-Requisites

Toolscript requires the following to be available on the machine it is run on:

• Deno 2.x
• jq

Installation

The Toolscript CLI can be installed and upgraded from JSR:

deno install --global --allow-net --allow-read --allow-write --allow-env --allow-run --allow-sys --allow-ffi --unstable-webgpu -r -f --name toolscript jsr:@toolscript/cli

Claude Code

To install the matching Claude Code plugin, open claude and type:

/plugin marketplace add mKeRix/toolscript
/plugin install toolscript@toolscript

Finally, restart Claude Code to activate the plugin.

Other Agentic Tools

There are no special integrations for other agentic tools available yet, but as a CLI Toolscript can be used by any agent that has shell access. To do so, please ensure that a gateway is running on your machine (via toolscript gateway start) and then instruct your agent (via system prompt, plugins etc.) how to find and use tools. You can take inspiration from the Claude Code skill definition to do so.

Configuration

You can create .toolscript.json files on two levels to configure the servers it will load, which are merged together into the configuration that will be used. If a server name appears in multiple files, the latest definition wins.

• ~/.toolscript.json - user-level configuration for servers that you want to have enabled across all projects you are working on
• .toolscript.json - project-level configuration for servers that are specific to a single repository or should be shared with your team via the repository

The Toolscript config format resembles the MCP configuration found in Claude Code to make porting between the tools easier. An example config can be found below:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "LOG_LEVEL": "debug"
      },
      "includeTools": ["read_file", "write_file"],
      "excludeTools": ["delete_file"]
    },
    "web-search": {
      "type": "http",
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer ${SEARCH_API_KEY:-default-key}"
      }
    },
    "github": {
      "type": "sse",
      "url": "https://api.example.com/github",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}