Agent MCP MCP server
Commit Nov 3, 2026Provides an OpenCode-compatible interface for file manipulation, shell execution, web searching, and web fetching over HTTP or stdio.
Also known as uukelele/agent-mcp
- Stars
- 0
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 3, 2026
- License
- MIT
What is Agent MCP MCP?
Agent MCP provides an OpenCode-compatible interface for file manipulation, shell execution, web searching, and web fetching over HTTP or stdio. It exposes 9 tools, such as read, glob, grep.
Summary generated from the project's README
About Agent MCP MCP server
Giving an AI agent controlled access to a local or remote machine is what agent-mcp enables. This server provides a standardized interface for file manipulation, shell execution, and web interaction that matches the tool names and input fields used in OpenCode. It can be deployed locally via stdio or remotely over HTTP using a secure bearer token for authentication.
Developers can use specific tools like read, write, edit, and patch to manage files within a defined root directory. The server also includes shell access for executing commands, glob and grep for searching files, and webfetch and websearch for retrieving online information. Web searches are powered by DuckDuckGo and do not require an external API key.
This server works on Linux, macOS, and Windows. It is designed to be used with any MCP client, though it offers specialized compatibility for OpenCode users. When running via HTTP, it supports features like stateless sessions and custom host configurations to accommodate various deployment environments.
Written from the project's README. Every use case is checked against a quote from it.
Agent MCP MCP tools 9
Detected from the READMEreadglobgrepeditwritepatchshellwebfetchwebsearch
Configuration
AGENT_MCP_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableuukelele/agent-mcp is public and reachablegithub.com/uukelele/agent-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/uukelele/agent-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagent-mcp
A cross-platform FastMCP server that exposes file, search, shell, and web tools with the same names and input fields as the built-in tools in OpenCode. It runs over Streamable HTTP (with a static bearer token) or stdio, on Linux, macOS, and Windows.
Use it to give an agent controlled access to another machine, or to replace a subset of local tools with a single authenticated MCP endpoint.
OpenCode / any MCP client
│ Authorization: Bearer <token>
▼
http://127.0.0.1:8765/mcp
│
├── read / write / edit / patch
├── glob / grep
├── shell
└── webfetch / websearch
Tool compatibility
| Tool | Parameters (same names as OpenCode) | Behavior |
|---|---|---|
read |
path, offset?, limit? |
Numbered lines, 2,000-line / 50 KiB pages, directory listings, images/audio/PDF as MCP media |
glob |
pattern, path?, hidden?, limit? |
Recursive glob, hidden filtering, newest first |
grep |
pattern, path?, include?, caseSensitive?, literal?, limit? |
Regex or literal content search; uses rg when available, Python fallback |
edit |
path, oldString, newString, replaceAll? |
Exact replacement; errors on ambiguous matches unless replaceAll=true; returns a diff |
write |
path, content |
Create or replace a file, creating parents |
patch |
patchText |
*** Begin Patch envelope: add, update, move, delete |
shell |
command, workdir?, timeout?, background? |
Host shell, millisecond timeout, process-tree kill, background log |
webfetch |
url, format?, timeout?, offset? |
Markdown reader with metadata, main-content extraction, .md/llms.txt preference, and pagination; text/html retained for compatibility; PDFs/images returned as MCP media |
websearch |
query, max_results?, recency?, news? |
DuckDuckGo results with no API key; optional recency filter or news search |
Not mirrored: question, skill, subagent, and execute are client-side
tools. websearch uses DuckDuckGo's public endpoint and needs no provider key.
Install
Requires Python 3.10+.
# from this checkout, in a project virtualenv
uv venv && uv pip install -e .
# or install the CLI in an isolated environment from the checkout
pipx install .
# uv tool install .
# or install directly from the public repository
pipx install "git+https://github.com/uukelele/agent-mcp.git"
Run over HTTP
export AGENT_MCP_TOKEN="$(openssl rand -hex 32)"
agent-mcp \
--root /srv/project \
--host 127.0.0.1 \
--port 8765 \
--token "$AGENT_MCP_TOKEN"
Endpoint: http://127.0.0.1:8765/mcp.
- Every request must send
Authorization: Bearer <token>. - Binding a non-loopback address without a token is refused unless you pass
--no-authexplicitly. --statelessremoves MCP session IDs (useful behind buffered proxies).--json-responsereturnsapplication/jsoninstead of request-scoped SSE.--allowed-host/--allowed-originextend FastMCP's Host/Origin guard when running behind a reverse proxy.
For a public deployment, terminate TLS in Caddy/nginx and forward to
127.0.0.1:8765; do not send bearer tokens over plain HTTP across a network.
Run with Docker
export AGENT_MCP_TOKEN="$(openssl rand -hex 32)"
mkdir -p workspace
docker compose up -d
The compose file publishes only 127.0.0.1:8765 and mounts ./workspace as
the sandbox root. The container runs as an unprivileged mcp user, but shell
still executes inside the container with that user's full access to the mounted
workspace. Add --allow-outside-root, --allow-private-web, or other flags to
the compose command only when you need them.
Run over stdio
agent-mcp --transport stdio --root /srv/project
OpenCode starts it for you:
{
"mcp": {
"servers": {
"tools": {
"type": "local",
"command": ["agent-mcp", "--transport", "stdio", "--root", "/srv/project"]
}
}
}
}
Connect from OpenCode (HTTP)
Because this server uses a static header token and does not advertise OAuth,
set "oauth": false:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"tools": {
"type": "remote",
"url": "http://127.0.0.1:8765/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:AGENT_MCP_TOKEN}"
}
}
}
}
}
CLI equivalent:
opencode mcp add tools --url http://127.0.0.1:8765/mcp \
--header 'Authorization=Bearer {env:AGENT_MCP_TOKEN}'
# `mcp add` does not write oauth:false; add it to the generated entry.
opencode mcp list
Tool names are prefixed with the server name (for example tools_read,
tools_shell). Under OpenCode's default Code Mode they are grouped under the
server namespace. Set "codemode": false on the server if you want them exposed
directly in the native tool list.
Authentication
--token/AGENT_MCP_TOKEN/MCP_AUTH_TOKENsets the only accepted bearer token. Tokens shorter than 16 characters are rejected.- The token is compared with
secrets.compare_digest. --no-authis required to run HTTP without authentication. It is only sensible on loopback.--print-configshows the resolved settings with the token redacted.
Cross-platform behavior
- Shell: on Linux/macOS the default is
$SHELL -lc(falling back tobash/sh); on Windows it is PowerShell (pwsh/powershell) with-NoProfile -NonInteractive -Command, falling back tocmd.exe /d /s /c. Override with--shellorAGENT_MCP_SHELL. Background commands write their log to<root>/.agent-mcp/shell/, soreadcan access it inside the sandbox; add that directory to.gitignore. - Process trees: timeouts kill the whole tree with
killpgon POSIX andtaskkill /Ton Windows. - Encoding: UTF-8, UTF-8/UTF-16/UTF-32 BOMs, BOM-less UTF-16, and the platform ANSI code page are detected. Edits round-trip the original encoding and BOM byte-for-byte.
- Newlines: CRLF, LF, and CR are preserved when editing or patching.
- Paths: relative paths resolve against
--root; absolute paths are checked withcommonpath, including Windows drive letters. Glob/grep display workspace-relative POSIX paths for consistent agent output. - Atomic writes: temp file in the target directory,
fsync, thenos.replace; existing permissions are preserved.
Patch format
*** Begin Patch
*** Add File: hello.txt
+hello
*** Update File: hello.txt
@@
hello
-world
+there
*** Update File: old.txt
*** Move to: new.txt
@@
-a
+b
*** Delete File: gone.txt
*** End Patch
Every operation is parsed and every hunk is matched before anything is written. A missing context line aborts the whole patch. New files are written as UTF-8 with LF; updates keep the file's existing encoding and newline style.
Security model
- File access is confined to
--rootunless--allow-outside-rootis set. Symlink targets are resolved before the containment check. shellis not sandboxed. It runs as the server user with that user's full privileges. Run the server as a dedicated, unprivileged account and restrict network access.webfetchchecks every redirect hop and pins the connection to the checked DNS address, so rebinding cannot swap in a private host. Loopback, private, link-local, and reserved addresses are blocked by default, and cloud metadata addresses stay blocked even with--allow-private-web.websearchonly calls DuckDuckGo throughddgs; it needs no API key.shellinherits the server environment, including any provider API keys stored there. Run the service under a dedicated account and keep unrelated secrets out of its environment.- Keep the token in an environment variable, not in a world-readable config.
Limitations
readreturns PDFs as embedded resources rather than extracting text.grepuses Python'sreengine in the fallback path: lookaround works, but\p{...}and some PCRE syntax do not. With ripgrep, matching uses ripgrep's Rust regex syntax (no lookaround unless--pcre2is added) but is faster. Ripgrep detects UTF-16 with a BOM; BOM-less UTF-16 is covered by the Python fallback. Anchor patterns or narrow withincludefor predictable results.globreturns files, not directories.- Background shell commands return immediately; there is no completion
notification. Poll the returned log path with
read. webfetchdoes not run JavaScript. JavaScript-only pages, bot checks, and paywalls may return an error or a link-preview summary; use another source.webfetchprefers a site's Markdown version,.mdtwin, and/llms.txtwhen present. HTML extraction is heuristic, so some unusual layouts may lose content. Site-specific readers cover X/Twitter, YouTube, Reddit, Stack Exchange, TikTok, and link-preview-only social sites.webfetchreturns PDFs and images as MCP file/image content;format="text"andformat="html"use a simpler raw fetch without main-content extraction.websearchdepends on DuckDuckGo's public endpoint; rate limits or changes on their side can make a search fail. Re-run or rephrase the query.- The server does not implement OpenCode's permission prompts, snapshots, or
patch-for-GPT-only policy. Your MCP client decides when to call a tool.
Development
uv venv
uv pip install -e ".[dev]" # or: uv pip install -e . pytest httpx
.venv/bin/pytest
.venv/bin/agent-mcp --print-config
License
MIT. The web reader, site-specific readers, and search result formatting are adapted from the author's Obsidian project.
Agent MCP MCP questions
What tools does Agent MCP MCP provide?
It exposes 9 tools, including read, glob, grep, edit, write.
Does websearch require an API key?
No, websearch uses DuckDuckGo's public endpoint and does not require a provider key.
How can I run the server without authentication?
You can run the server without authentication by passing the --no-auth flag, though this is only recommended for loopback addresses.