toolnexus

Build an agent in a few lines. Point at an mcp.json and a skills/ folder, call run(), and you have a working agent — MCP servers, agent skills, your own functions, and HTTP endpoints unified as one tool set, driving any LLM.

Right-sized. Not a framework (no builders, no config to wade through), not a toy that falls over the moment you need streaming or a retry. Everything a real agent needs — the loop, hooks, streaming, retries, memory — and nothing it doesn't.

The Python port of toolnexus — the same library, byte-identical, also in JavaScript, Go, Java, C#, Elixir and Clojure. Built on the official MCP Python SDK (the mcp package). Python ≥ 3.11.

Install

pip install toolnexus

Quick start

The 10 built-in tools (bash, read, grep, webfetch, …) are on by default, so the model can act with no mcp.json and no skills folder:

import asyncio
from toolnexus import create_toolkit, create_client

async def main():
    tk = await create_toolkit()                          # built-in tools, on by default
    agent = create_client(
        base_url="https://openrouter.ai/api/v1", style="openai",
        model="deepseek/deepseek-chat",                  # any OpenRouter/OpenAI/Anthropic model
    )
    res = await agent.run("List the files here, then count them.", tk)
    print(res.text)
    await tk.close()

asyncio.run(main())

Add real tool sources by pointing at them:

tk = await create_toolkit(mcp_config="mcp.json", skills_dir=["skills"])

mcp.json is the standard Claude-desktop-style config (mcpServers / servers / mcp keys all accepted).
skills/ is a folder of **/SKILL.md files, loaded on demand through one skill tool.
Remote MCP headers values expand ${ENV_VAR} at call time and are never logged.

Documentation

Everything else — the full surface, with runnable examples — lives on the docs site:


Start here	Quickstart · Concepts · Install
Tool sources	MCP · Skills · Native · HTTP · Built-ins · A2A
The loop	Streaming · Memory · Suspension · Resilience · Observability
Agents	Sub-agents & teams · Personas · Typed decisions
API reference	Python
Cookbook	Zero to agent · MCP servers · Agent skills · Judge

Contract across all seven ports: SPEC.md.

Metadata

Release files for toolnexus 0.20.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for toolnexus 0.20.0
File	Size	Uploaded
toolnexus-0.20.0.tar.gz	292.2 kB	Sep 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for toolnexus 0.20.0
File	Interpreter	ABI	Platform	Reset
toolnexus-0.20.0-py3-none-any.whl 148.7 kB Sep 23, 2026	Python 3	none	any	Details

Total release size: 440.9 kB

Release files / toolnexus-0.20.0.tar.gz

Download URL	toolnexus-0.20.0.tar.gz
Size	292.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`0522587be690cf469368d165d477cf41c6b5adf23fb6c5dd45a4ee734cb748f8`
BLAKE2b-256 checksum How to use checksums	`eaa9a96b5b8c0a29e063ab1b68a4378854e6fc5976b3bb355c10636f1d8451a9`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/muthuishere/toolnexus
Publishing commit: github.com/muthuishere/toolnexus/tree/197726a355f72743ffcc4d3840613e12a77fe753

Workflow

Publishing configuration: github.com/muthuishere/toolnexus/blob/197726a355f72743ffcc4d3840613e12a77fe753/.github/workflows/release.yml
Publishing logs: github.com/muthuishere/toolnexus/actions/runs/35811618059/attempts/1

Artifact

Subject: toolnexus-0.20.0.tar.gz
SHA-256 checksum: 0522587be690cf469368d165d477cf41c6b5adf23fb6c5dd45a4ee734cb748f8 Verifying attestations

Release files / toolnexus-0.20.0-py3-none-any.whl

Download URL	toolnexus-0.20.0-py3-none-any.whl
Size	148.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4071df3a201ee8c9420736844e70417ee026edb97c01db9cb182e6b60fad6206`
BLAKE2b-256 checksum How to use checksums	`d3033310b00cb13d391358e48a9fb349628cf9665b4178fd972a825c2ecd04d6`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/muthuishere/toolnexus
Publishing commit: github.com/muthuishere/toolnexus/tree/197726a355f72743ffcc4d3840613e12a77fe753

Workflow

Publishing configuration: github.com/muthuishere/toolnexus/blob/197726a355f72743ffcc4d3840613e12a77fe753/.github/workflows/release.yml
Publishing logs: github.com/muthuishere/toolnexus/actions/runs/35811618059/attempts/1

Artifact

Subject: toolnexus-0.20.0-py3-none-any.whl
SHA-256 checksum: 4071df3a201ee8c9420736844e70417ee026edb97c01db9cb182e6b60fad6206 Verifying attestations