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.

Release files for toolnexus 0.18.1

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.18.1
File	Size	Uploaded
toolnexus-0.18.1.tar.gz	248.3 kB	Sep 21, 2026	Details

Built distribution (wheel)

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

Total release size: 376.0 kB

Release files / toolnexus-0.18.1.tar.gz

Download URL	toolnexus-0.18.1.tar.gz
Size	248.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`789db51302e766bc34731de0edd2c2f163e1ebc90b03941956f836fe72731bb1`
BLAKE2b-256 checksum How to use checksums	`ee5d20ced6bdae6c9521ce96dbe63310479796d71dbf09a98aafc871c21cdd2f`
Upload date	Sep 21, 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/7f9e39122bd81a02a53fb0759f9800ed3d313a54

Workflow

Publishing configuration: github.com/muthuishere/toolnexus/blob/7f9e39122bd81a02a53fb0759f9800ed3d313a54/.github/workflows/release.yml
Publishing logs: github.com/muthuishere/toolnexus/actions/runs/35594119856/attempts/1

Artifact

Subject: toolnexus-0.18.1.tar.gz
SHA-256 checksum: 789db51302e766bc34731de0edd2c2f163e1ebc90b03941956f836fe72731bb1 Verifying attestations

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

Download URL	toolnexus-0.18.1-py3-none-any.whl
Size	127.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`71caf6c5c9c16813c6a2bf0d5a73d6a08e346badde301962eb7308d1fcd807c5`
BLAKE2b-256 checksum How to use checksums	`656ec2ded3e38504bf34dd2be93c455d288eb186ffb07473c1c520b9ec49bd41`
Upload date	Sep 21, 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/7f9e39122bd81a02a53fb0759f9800ed3d313a54

Workflow

Publishing configuration: github.com/muthuishere/toolnexus/blob/7f9e39122bd81a02a53fb0759f9800ed3d313a54/.github/workflows/release.yml
Publishing logs: github.com/muthuishere/toolnexus/actions/runs/35594119856/attempts/1

Artifact

Subject: toolnexus-0.18.1-py3-none-any.whl
SHA-256 checksum: 71caf6c5c9c16813c6a2bf0d5a73d6a08e346badde301962eb7308d1fcd807c5 Verifying attestations