agent-tool
MCP (Model Context Protocol) tool server for AI coding agents.
Why?
Built-in tools in AI coding agents (Claude Code, Cursor, Codex, etc.) have known limitations:
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
mcpb https://github.com/knewstimek/agent-tool/releases/download/v0.4.2/agent-tool.mcpbClaude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add knewstimek-agent-tool -- mcpb https://github.com/knewstimek/agent-tool/releases/download/v0.4.2/agent-tool.mcpb在終端機中執行。
{ "mcpServers": { "knewstimek-agent-tool": { "command": "mcpb", "args": [ "https://github.com/knewstimek/agent-tool/releases/download/v0.4.2/agent-tool.mcpb" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
MCP (Model Context Protocol) tool server for AI coding agents.
Built-in tools in AI coding agents (Claude Code, Cursor, Codex, etc.) have known limitations:
MCP tool server for AI coding agents -- encoding-aware file tools, binary analysis, DAP debugger, SSH/SFTP, process memory, and more
curl/wget requests. agent-tool uses ECH (Encrypted Client Hello) and DoH (DNS over HTTPS) by default to work around these restrictions.agent-tool solves these with agent-oriented tools that preserve project conventions while keeping model context bounded.
Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, and any MCP-compatible agent.
The default core profile exposes only 11 schemas (including toolbox) instead of
all 40. In a protocol-level measurement this reduced the serialized tool list from
about 74 KB (full) to 15 KB. For the smallest steady-state context, start with
--profile core-lite; its five schemas are about 6.4 KB and expose only read,
write, edit, grep, and toolbox. Use
toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute")
to load only one operation's fields and required list, then invoke it through
toolbox(operation="call", tool="ssh", arguments={...}). The gateway does not
depend on dynamic tool-list refresh, so it works with fixed-binding clients such as
Codex. Describe returns a tool/version-bound schema_handle; sending it on a later
describe returns a short unchanged acknowledgement when the schema is still current.
Common compact operations include SSH execution, MySQL queries, file copy, Windows
screenshots/clipboard images, and static-analysis operations. You can also start
with --profile core-lite|coding|remote|analysis|full.
Potentially large text responses default to 32K characters with a 128K hard ceiling.
Truncation is always visible and pageable tools return next_offset or next_cursor.
Local relative paths resolve against an explicit workspace, then the MCP client root.
LLMs typically output spaces, but many projects use tabs. AgentTool auto-converts indentation to match the file's existing style.
.editorconfig for indent_style and indent_size.editorconfigEdits preserve the original file encoding instead of forcing UTF-8.
.editorconfig charset → BOM-less UTF-16 → valid UTF-8 → chardet auto-detection → fallback encodingedit matches a multi-line old_string whether the file uses CRLF or LF, including files that mix both, and text inserted by edit/regexreplace follows the newline style of the region it lands in, so the rest of the file is left byte-identicallistdir defaults to 500 entries per page and returns next_cursor when more
entries are available. Narrow results with directories_only, files_only,
name_pattern (for example A*), or multiple OR patterns in include.
Use counts_only=true when only matching file/directory counts are needed.
After 30 minutes with no tool call, the server returns its heap to the OS. A stdio MCP server cannot tell an abandoned client from a quiet one -- the process that spawned it may be alive, finished with it, and still holding the pipe open, so no EOF ever arrives -- and exiting on that guess would break a session that merely paused. Releasing the memory is the safe half of that trade: an instance that once read a 50MB file settles back to its ~20MB baseline instead of holding 200MB for the rest of the machine's uptime. Open shell and ssh sessions survive, and nothing the client can observe changes.
agent-tool install (or agent-tool install claude for a specific agent)toolbox describes and calls every other tool on demandOr just ask your AI agent to do it for you:
"Download agent-tool from https://github.com/knewstimek/agent-tool/releases/latest and run
agent-tool install"
Any capable AI coding agent (Claude Code, Codex, etc.) can handle the full download → install → restart flow automatically.
After installing, agents will have access to agent-tool but may still default to built-in tools (Read, Edit, etc.). To ensure agents prefer agent-tool's encoding-aware, indentation-smart tools, add one of the instructions below.
Code navigation tip: For large projects, add this to your CLAUDE.md / AGENTS.md to enable AST-based code navigation:
At the start of a session, run codegraph(op="index", path="<project_root>") to build a code index.
For several repositories sharing one graph, use codegraph(op="index", path="<db_root>", roots=["<source_root_1>", "<source_root_2>"]). Source-root provenance prevents unrelated projects with the same symbol names from contaminating candidates while explicit/transitive includes can still cross roots.
Then use codegraph for structural queries (find, callers, callees, methods, inherits) instead of grep.
Pick Strict or Soft:
Where to put it:
Per-project — add to your project's CLAUDE.md:
ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.
Global (all projects) — add to ~/.claude/CLAUDE.md:
ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.
Hard enforcement — deny built-in file tools at the permission level via ~/.claude/settings.json:
{
"permissions": {
"deny": ["Read", "Edit", "MultiEdit", "Write", "Glob", "Grep"]
}
}
This makes Claude Code's built-in file tools unavailable, so the agent is forced to use agent-tool. Recommended when you want strict enforcement without relying on prompt instructions.
~/.codex/config.toml (top-level, not inside [mcp_servers.*]):model_instructions_file = "~/.codex/model_instructions.md"
~/.codex/model_instructions.md:ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.
Per-project — add to your project's AGENTS.md instead.
Add to your project's .cursorrules, .windsurfrules, or AGENTS.md:
ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.
# Register with all detected agents (full auto-approve — all tools)
agent-tool install
# Safe mode — only auto-approve local file tools (no SSH, HTTP, DB, shell)
agent-tool install --safe-approve
# No auto-approve — manual approval required for every tool call
agent-tool install --no-auto-approve
# Register with a specific agent
agent-tool install claude
agent-tool install claude --safe-approve
# Uninstall (removes agent-tool entry only, preserves other settings)
agent-tool uninstall # from all agents
agent-tool uninstall claude # from specific agent
Install permission levels:
Approval level is independent of schema profile: installation may approve the full
namespace while the server still starts with the token-efficient core profile.
toolbox is intentionally not auto-approved by --safe-approve, because its
operation=call gateway can invoke network, shell, database, and process-control
tools. Safe-mode users should review each toolbox approval and avoid granting it a
permanent allow rule unless they intend to trust the full AgentTool namespace.
Claude Code / Cursor / Cline (settings.json or mcp.json):
{
"mcpServers": {
"agent-tool": {
"command": "/path/to/agent-tool"
}
}
}
Codex CLI (~/.codex/config.toml):
[mcp_servers.agent-tool]
command = "/path/to/agent-tool"
# Select the initial schema profile (default: core)
agent-tool --profile core-lite
# Set fallback encoding for projects with non-UTF-8 files
agent-tool --fallback-encoding EUC-KR
Profiles are presets: core-lite (read/write/edit/grep/toolbox), core (11
schemas), coding (core plus broader file/build/shell tools), remote, analysis,
and full. At runtime, prefer the
client-independent toolbox gateway: operation=describe returns one tool's schema
(compact=true plus tool_operation limits it to one operation), and
operation=call invokes it through the stable toolbox binding. Re-send a returned
schema_handle to avoid receiving an unchanged schema again. When command
diagnostics are compacted, operation=output retrieves the bounded raw output by
its reported ID for 30 minutes and reports next_offset when paging is needed. enable,
disable, and profile remain available for clients that honor
tools/list_changed; fixed-binding clients can always keep using the gateway.
Set AGENT_TOOL_FALLBACK_ENCODING and/or AGENT_TOOL_PROFILE to avoid repeating CLI flags:
# Windows (no admin required)
setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR
setx AGENT_TOOL_PROFILE coding
# Linux / macOS (add to ~/.bashrc or ~/.zshrc)
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR
export AGENT_TOOL_PROFILE=coding
Priority: CLI flag > environment variable > default (UTF-8).
SSH and SFTP accept either connection_profile or a session-local connection_id,
so host, user, key, and jump-host fields do not need to be repeated. Profiles are
read from the OS user config directory at agent-tool/connections.json; override the
location with AGENT_TOOL_CONNECTION_PROFILE_FILE. Keep this file local and explicitly
ignored if it is placed inside a workspace.
{
"connections": {
"dev": {
"host": "192.0.2.10",
"user": "builder",
"key_file": "/local/path/to/id_ed25519",
"host_key_check": "strict",
"trusted": true
}
}
}
An initial call returns an opaque connection_id that remains reusable by both tools
for 30 minutes. Local profiles default to trusted:true; set trusted:false to show the
private-address warning on every call instead of once per pooled connection. This affects
only display; SSRF blocking and cloud metadata protection are unchanged. SSH also supports quiet, echo_command, and
result_only; the last returns compact JSON centered on stdout, stderr, and
exit_code. SFTP supports quiet, result_only, and upload_many (up to 100 files).
For Windows PowerShell, pass script text in powershell_script instead of command.
SSH uploads a unique UTF-8 temporary .ps1 through a short PowerShell command's
standard input, executes its contents with
a short PowerShell launcher, and deletes it after success or failure. Standalone
powershell[.exe] / pwsh[.exe] commands using -EncodedCommand (or -enc, -ec,
-e) are staged automatically at 8,000 UTF-16 code units. Safe profile, interactive,
apartment, and execution-policy options are preserved; unsupported options or shell
suffixes require explicit powershell_script input. Scripts are limited to 4 MiB.
SFTP is not required, including on legacy Windows SSH servers.
{"operation":"execute","connection_profile":"dev","powershell_script":"Write-Output 'hello'","result_only":true}
Preparation and foreground execution share timeout_sec. Background scripts use
the same upload and cleanup path, then expose job_id for status/tail/cancel.
The remote launcher attempts cleanup in finally; confirmed completion also triggers
bounded SSH cleanup. Cancellation or connection loss does not prove remote termination,
so the tool leaves deletion to the remote launcher and reports cleanup_warning if
completion or cleanup could not be confirmed. This warning is separate from the
script's exit code and captured output.
ssh_key converts a private-key file without sending its contents over the network or
returning key material in the response. Input is auto-detected as PPK, PEM, PKCS#8, or
OpenSSH. The output format is one of ppk, pem, pkcs8, or openssh.
{
"operation": "convert",
"input_path": "server.pem",
"output_path": "server.ppk",
"output_format": "ppk",
"input_passphrase": "",
"output_passphrase": "",
"overwrite": false
}
PPK output uses version 3. Passphrase-protected PPK output uses Argon2id,
AES-256-CBC, and HMAC-SHA-256; protected OpenSSH output uses OpenSSH's modern
encrypted format. Traditional PEM and PKCS#8 output are deliberately unencrypted;
use openssh or ppk when output encryption is required. New files are mode 0600,
and existing files are not replaced unless overwrite=true.
Agents can change settings at runtime via set_config without restarting:
go build -trimpath -ldflags="-s -w" -o agent-tool .
Cross-compile:
GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool.exe .
The guarded GitHub workflow runs tests, builds all declared assets, creates the MCPB and checksums,
and verifies uploaded bytes. From a clean, pushed master branch, dispatch a build-only dry run:
.\scripts\release.ps1
After the dry run succeeds, publish the version declared in main.go:
.\scripts\release.ps1 -Publish
The workflow requires tracked notes at docs/releases/vVERSION.md. Publication creates an
annotated tag and GitHub Release, then updates server.json with the released MCPB hash.
When RepoPlane uses this repository as its workspace, the same dry-run, publish, and status
operations are discoverable through the repository-local catalog/ manifests.
If Korean, Japanese, or other non-ASCII text appears as garbage characters:
Option 1: Add charset to your .editorconfig:
[*]
charset = euc-kr
Option 2: Set environment variable (persistent):
setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR # Windows
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR # Linux
Option 3: CLI flag (per-session):
agent-tool --fallback-encoding EUC-KR
agent-tool includes a agent_tool_help tool that agents can call for usage guidance. When an agent encounters encoding warnings or garbled text, it can call:
{ "tool": "agent_tool_help", "arguments": { "topic": "encoding" } }
Available topics: overview, encoding, indentation, tools, troubleshooting
agent-tool provides powerful system access (SSH, MySQL, Redis, file operations, HTTP requests). When used with AI coding agents, be aware of prompt injection risks:
set_config (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)../ path traversal are blocked (both zip and tar)set_config allow_symlinks=true (tar only; zip symlinks always skipped). Even when enabled, symlinks targeting outside the output directory are blockedset_config max_file_size_mb=NFor maximum security, review the AI agent's tool calls before approving, especially for SSH commands, HTTP requests to external URLs, and database queries.
The decompiler (Gosleigh) and the Ghidra language specs it embeds are licensed under the Apache License 2.0; Gosleigh is a reimplementation of the Ghidra decompiler, developed by the National Security Agency (https://github.com/NationalSecurityAgency/ghidra).
MCP tool server for AI coding agents -- encoding-aware file tools, binary analysis, DAP debugger, SSH/SFTP, process memory, and more
{ "mcpServers": { "knewstimek-agent-tool": { "command": "mcpb", "args": [ "https://github.com/knewstimek/agent-tool/releases/download/v0.4.2/agent-tool.mcpb" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Agent Tool 透過 stdio 在本機執行。
上次檢查時間:2026-11-17。 MCP tool server for AI coding agents -- encoding-aware file tools, binary analysis, DAP debugger, SSH/SFTP, process memory, and more