agent-toolbox
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
agent-toolbox
An MCP server that gives an agent hands: tools to query data, work with files and run Python for analysis — and a sandbox where those tools are callable as plain functions. New tools are added over time; every client discovers the current set over MCP.
It is a standard MCP server: the homelab agents use it, and so can any MCP client. It serves its tools by scope, one endpoint each, so every agent discovers only the tools meant for it (see Scopes).
Using the toolbox — run it, connect a client, know what each tool does. Working on the toolbox — how it is built and how to add a tool.
┌──────────────────────────────────────────────┐
agent / MCP client ───►│ agent-toolbox /mcp (all) · /mcp/<scope>│
(X-Request-ID) │ │
│ data tools ───────► databases, files, … │
│ python_executor ─► sandbox ─┬─► working dir │
│ (per scope that lists it) └─► its scope's │
│ data tools │
└──────────────────────────────────────────────┘Using the toolbox
Run it
Requirements: Python 3.14 and uv.
uv sync --group dev
cp .env.example .env # fill in the paths and the URL clients will use
make runEndpoint | |
MCP (streamable HTTP) |
|
Health |
|
Version |
|
/health/readiness answers 503 until the server has tools registered.
With Docker: make docker_build builds the image.
The tools
The server is the reference for what it offers: an MCP client lists the tools (tools/list) with their descriptions and full input and output schemas — the agent does it at boot, then every minute. The tools available today:
Tool | What it does | Inputs |
| Read-only SQL on the service database (users dashboard, payment data). Anything that writes or changes the schema is refused before it reaches the database |
|
| Returns a file's contents — parsed for |
|
| Writes (replaces) a file in one of the same formats |
|
| Runs Python for analysis or computation; the value of the variable |
|
| grafana_* | Grafana's MCP server: search and read dashboards, datasources, alert rules, PromQL and Loki queries | per tool (see tools/list) |
| mongodb_* | MongoDB's MCP server: list databases and collections, schema, find, aggregate, count — writes only when the deployment allows them | per tool |
| postgres_* | PostgreSQL's MCP server (postgres-mcp): schemas, objects, execute_sql, explain, health — read-only unless the deployment allows writes | per tool |
A call with invalid arguments gets an error naming the bad fields. Every tool added later follows the same rules: published with its schema, callable directly and from the sandbox.
The working directory. When WORKING_DIRECTORY is set, every file a tool reads or writes lives there, and relative paths name the same file in a tool call and inside python_executor code. Access outside it is refused.
The Python sandbox runs each piece of code in its own process:
allowed modules: pandas, numpy, matplotlib, datetime and the rest of pycraftcore's allowlist (listed in the tool's description);
256 MB of memory, at most 8 runs at a time, and a hard timeout;
with
SANDBOX_TOOL_ACCESS=true, the other tools are available inside the code as functions that return exactly what the tool returns. The tool's description lists each one in two lines, its Python signature and the first sentence of its description, so it stays small with many tools:
import pandas as pd
rows = users_tables(query="SELECT country, COUNT(*) AS users FROM users GROUP BY country")
df = pd.DataFrame(rows["rows"])
file_writer(file_path="users_by_country.csv", data=df.to_csv(index=False))
result = df.sort_values("users", ascending=False).head(3).to_dict("records")Tools from other MCP servers
The toolbox also republishes the tools of other MCP servers, as its own: listed in tools/list, called the same way, and available as functions in python_executor code. Each server's tools carry its prefix, and names are made valid Python (list-databases → mongodb_list_databases):
Server | Prefix | URL variable | Transport |
|
| streamable HTTP | |
|
| streamable HTTP | |
|
| SSE |
databases = mongodb_list_databases()
rows = postgres_execute_sql(sql="SELECT schemaname, COUNT(*) FROM pg_tables GROUP BY 1")
result = {"databases": databases["result"], "tables": rows["result"]}A server whose URL is empty is skipped. The others are read at start-up and again in the background, so the order the pods start in doesn't matter:
each server has its own loop, so one that is down never changes how often the others are read;
a server that doesn't answer is retried after 5 s, then 10, 20, 40, and every 60 s; its tools appear as soon as it answers, with no restart;
a server that answers is re-read every 60 s, so tools it adds, changes or drops follow (
python_executor's list of functions too);these numbers are the
refreshblock of each connector inconfig/<APP_ENV>/connector/mcp.yml(interval,retry_delay,max_retry_delay);MCP_REFRESH_INTERVAL,MCP_RETRY_DELAYandMCP_MAX_RETRY_DELAYchange them for every server. Leave a variable unset rather than empty, or the configuration fails to load;a server that stops answering keeps its tools listed: a call returns "its server may be down or restarting; try again later" until it's back.
/actuator/healthlists each server (UP, orDOWNsince when and why). The readiness probe stays about the toolbox itself, so one server down never takes the toolbox's own tools away.What each server may do (read-only or read-write, which tools) is decided where it runs; the toolbox republishes what it offers.
To keep only some of a server's tools, list their remote names under its operation's
toolsinconfig/<APP_ENV>/operation/mcp.yml.
Add another server: a connector named external_mcp_<name> in config/<APP_ENV>/connector/mcp.yml (its URL from an environment variable, '' by default), an operation of the same name with its prefix in config/<APP_ENV>/operation/mcp.yml, both listed in config/root.yml, and the variable in .env.example and devops/helm/values.yml.
Scopes
The toolbox serves its tools by scope, one MCP endpoint each, so every agent connects to its own scope and discovers only the tools meant for it:
Scope | Endpoint | Tools |
|
| every tool |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
python_executoronly where a scope lists it (allhas it:*matches it). Each such scope has its own: its description lists, and its code can call, only that scope's tools.Tools from other MCP servers join or leave each scope whose patterns match them while the toolbox runs.
An endpoint shows only its scope's tools and calls only those, so an agent can't reach a tool outside its scope through this endpoint.
To add or change a scope, edit
config/debug/operation/scope.yml: onemcpoperation on theselfconnector, with the scope's name asnameand shell-style patterns asparameters.tools. Then list it underoperation:inconfig/root.yml.allis built in.
Connect a client
Point the client's MCP connector at http://<host>:<port>/mcp with the streamable_http transport. The homelab agent's connector:
toolbox:
name: toolbox
type: mcp
base_url: ${oc.env:TOOLBOX_URL}
timeout: 30
transport: streamable_httpTo try the tools by hand, the MCP Inspector works against the same URL:
npx @modelcontextprotocol/inspectorAllowed hosts. Only requests whose Host matches TOOLBOX_URL are accepted (protection against DNS rebinding); any other host gets 421 Invalid Host header. When clients reach the toolbox under another name — a LAN hostname, a Tailscale name, a tool like Postman — list it in TOOLBOX_EXTRA_ALLOWED_HOSTS rather than changing TOOLBOX_URL.
Configure it
Variable | Meaning |
| Which |
|
|
| Where |
| Label shown by |
| The URL clients use, e.g. |
| Other |
| The folder file tools and the sandbox are confined to; unset = no working directory |
|
|
| Other MCP servers whose tools are republished (see Tools from other MCP servers); empty = skipped |
| OpenTelemetry collector (gRPC); an empty host turns telemetry off |
Tools that reach a backend add their own settings, read through a connector in config/<APP_ENV>/connector/. Today the SQL tool reads its SQLite database from USER_DB_HOST (folder) and USER_DB_NAME (file). .env.example is the reference for the full list.
Configuration files are in config/: root.yml sets the log level and lists what exists, and config/<APP_ENV>/connector/ defines the MCP server itself, telemetry, and each backend a tool uses. root.yml keeps server: {}: the MCP endpoint is not one of the web servers server/*.yml describes.
Logs
One format for every line the service writes; the third column is the request id sent by the client in X-Request-ID. Tool calls made from sandboxed code keep the id of the request that started them.
2026-09-27 10:47:47.785 | INFO | my-conversation | invoke_tool_usecase:invoke:23 - tool 'file_reader' invokedWith OTEL_HOST set, the same lines also go to the OpenTelemetry collector. Granian's own start and stop lines ([INFO] Starting granian…) keep Granian's format; access-log lines carry no request id.
With OTEL_HOST set, every MCP request is a span (tools/list, tools/call <tool>). A caller that sends its trace context in the request's _meta, as the MCP SDK does, gets the toolbox's span in its own trace: the agent's tool calls appear under its run_tools step. Notifications (notifications/initialized) get no span, so they don't add a one-span trace per session.
Related MCP server: MCP Powered AI Assistance
Working on the toolbox
Architecture
Hexagonal, like the agent: the use case and the tools know nothing about MCP. tests/architecture/test_boundaries.py enforces it (no agent, LangChain or LangGraph imports; no framework in the domain; no transport in the application).
MCP request ──► ToolBinder ──────────► InvokeToolUseCase ──► Tool.run
(inbound) one MCP tool per Tool validates arguments │
schemas from models logs, maps failures ├─► a data tool ──► its backend
│ (database, files, API, …)
sandboxed code ─► SandboxToolBridge ──► InvokeToolUseCase └─► ExecutePython ──► PythonSandbox
(python_executor) same use case, same tools, same request id (pycraftcore)Direct calls and calls from sandboxed code go through the same InvokeToolUseCase, so they return the same thing — tests/contract/test_tool_parity.py checks it.
Project layout
Path | What it holds |
|
|
|
|
|
|
|
|
| The tools, one folder per area ( |
| Settings, |
| Unit, architecture and contract tests |
Adding a tool
Define its input and output as pydantic models (
adapter/outbound/<area>/model/). Field descriptions become the MCP schema the agent reads.Subclass
Tool[Input, Output]with aname, adescriptionwritten for the model, andasync run(arguments). RaiseToolFailurewith a clear message when the call can't be served.If it needs a backend (a database, an API, …), add a connector in
config/<APP_ENV>/connector/, list it inconfig/root.yml, put its variables in.env.example, and build the client inToolboxDIfrom that connector.Register it in
ToolboxDI._ready_catalog, and add its name to the patterns of the scopes that should offer it (config/debug/operation/scope.yml). It is then published over MCP at/mcpand those scopes' endpoints and, whenSANDBOX_TOOL_ACCESSis on, callable frompython_executorcode — no change needed in the agent, which discovers it at its next start.Add unit tests next to the others, and its row to The tools.
class CountRows(Tool[CountRowsInput, CountRowsOutput]):
name = "count_rows"
description = "Count the rows of a table in the service database."
input_model = CountRowsInput
output_model = CountRowsOutput
async def run(self, arguments: CountRowsInput) -> CountRowsOutput: ...Tests and checks
make check # ruff + ty + pytest
make test
make lint / make format / make typecheckPre-commit hooks:
uv run pre-commit install --hook-type pre-commit --hook-type pre-pushDeploying
make docker_build builds agent-toolbox:local. It listens on port 8001; set the environment variables above on the container, with TOOLBOX_URL matching the address clients use.
On the homelab it runs as a Helm release: devops/helm/values.yml is how it runs there (env variables, Secrets it reads, port, probes, volumes). homelab-infra adds only this server's choices, in apps/agent-toolbox/values.yaml.gotmpl (its NetworkPolicy: who may call it and what it may reach).
Git flow: what each branch and tag publishes
feature/… ──PR──► develop ──PR──► main
│ │
└─ tag └─ tag vX.Y.Z a release
vX.Y.Z-rc.N image toufik142/agent-toolbox:X.Y.Z and :latest
image :X.Y.Z-rc.N chart oci://ghcr.io/s-toufik/charts/agent-toolbox:X.Y.Z
and :dev deployed once homelab-infra's versions.yaml says X.Y.Z
(never deployed)Event | Publishes | On the homelab | |
Pull request to | LINT, TYPECHECK, TEST, BUILD | nothing | nothing changes |
Push to | the same | nothing | nothing changes |
Tag | the same + RELEASE TARGET + PUBLISH | image | nothing changes |
Tag | the same + RELEASE TARGET + PUBLISH + CHART | image | nothing yet: deployed once homelab-infra asks for |
Only tags publish:
:devis the last pre-release,:latestthe last release. Only tags onmainreach the homelab; to try a pre-release there, homelab-infra's Q&A, How do I deploy a dev image of the agent?RELEASE TARGET finds the branch the tag is on, the same job in every repository with this pipeline (pycraftcore and homelab-ui too). A commit on both branches counts as
main. It refuses a tag on neither branch, a pre-release onmainand a final version only ondevelop, and then nothing is published.
What is deployed
The homelab runs the version in homelab-infra's environments/versions.yaml, apps.agentToolbox. On the server:
helm -n homelab list --filter '^agent-toolbox$' # CHART agent-toolbox-X.Y.Z, APP VERSION X.Y.Z
kubectl -n homelab get deploy agent-toolbox -o jsonpath='{.spec.template.spec.containers[0].image}'; echoRelease a version
Merge
developintomain(pull request); CI is green.Tag
main:git switch main && git pull git tag vX.Y.Z git push origin vX.Y.ZActions: PUBLISH and CHART are green.
In homelab-infra:
apps.agentToolbox: X.Y.Zinenvironments/versions.yaml, commit, push.On the server, in homelab-infra:
git pull,make diff R=agent-toolbox,make apply R=agent-toolbox(raw:helmfile -l name=agent-toolbox apply).Check: the
helm listabove showsX.Y.Z;make logs R=agent-toolbox.
Roll back: set the previous version in versions.yaml and make apply R=agent-toolbox, or right away make rollback R=agent-toolbox (raw: helm -n homelab rollback agent-toolbox). The step-by-step version is homelab-infra's DevOps guide, Release an app and Roll back.
The image is served by Granian, configured with GRANIAN_* variables in the Dockerfile (ASGI interface, factory, host, port, access log). Set any other Granian option the same way in your deployment, without rebuilding: for example GRANIAN_WORKERS=2 for two worker processes (each one builds its own server and tools), or GRANIAN_WORKERS_MAX_RSS=1024 to restart a worker that grows above 1 GiB — useful here, since python_executor runs user code.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables SQL query execution and database structure browsing via MCP tools and resources.MIT
- FlicenseNot gradedqualityDmaintenanceEnables secure execution of Python code, SQL queries, and metric fetching through MCP with ephemeral Docker sandboxing.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents and workflows to safely explore and query data in ephemeral sandboxed databases via MCP, with guardrails and snapshot capabilities.21MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to run SELECT-only queries and inspect table metadata against configured databases via MCP Proxy, with timeouts, row and byte caps, and audit logging.MIT