Provider-agnostic toolkit: dynamic MCP servers + agent skills for any LLM.
Project description
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, and C#. Built on the official MCP Python SDK
(the mcp package). Python ≥ 3.11.
Install
pip install toolnexus
An agent in 3 steps
The MCP SDK is async, so the toolkit is async:
import asyncio
from toolnexus import create_toolkit, create_client
async def main():
# 1. tools from an mcp.json + a skills/ folder
tk = await create_toolkit(mcp_config="./mcp.json", skills_dir="./skills")
# 2. point at any OpenAI- or Anthropic-style endpoint
agent = create_client(
base_url="https://openrouter.ai/api/v1",
style="openai", # or "anthropic"
model="openai/gpt-4o-mini",
)
# 3. run — skills injected, tools called for you, looped to an answer
res = await agent.run("Refund order 1234 for the customer.", tk)
print(res.text)
await tk.close()
asyncio.run(main())
create_client reads the key from OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
by default. The Toolkit is also an async context manager (async with await create_toolkit(...))
if you'd rather not call close() yourself.
Add your own tools
from toolnexus import define_tool, http_tool
# a plain function → a tool (schema inferred from the signature)
def add(a: float, b: float) -> str:
"""Add two numbers and return the sum."""
return str(a + b)
tk.register(define_tool(add, name="add"))
# a REST endpoint → a tool
tk.register(http_tool(
name="create_ticket", description="Create a ticket", method="POST",
url="https://api.example.com/tickets",
headers={"Authorization": "Bearer ${API_TOKEN}"}, # ${ENV} expands from os.environ, never logged
input_schema={"type": "object", "properties": {"title": {"type": "string"}}, "required": ["title"]},
))
URL {placeholders} are filled from args; the rest become the JSON body. Non-2xx →
ToolResult(output="HTTP <status>: <body>", is_error=True).
Bring your own loop
Don't want the host loop? Use the schema adapters and execute calls yourself:
tools = tk.to_openai() # or tk.to_anthropic() / tk.to_gemini()
system = tk.skills_prompt() # skills catalog for your system prompt (opens with a preamble telling the model to use the skill tool)
# when the model returns a tool call { name, arguments }:
res = await tk.execute(name, arguments) # -> ToolResult(output, is_error, metadata)
The four sources
| Source | How |
|---|---|
| MCP servers | an mcp.json (mcpServers/servers/mcp); local stdio + remote streamable-HTTP, headers for auth |
| Agent skills | a folder of <name>/SKILL.md; a skill tool loads each on demand + a system-prompt catalog |
| Native tools | define_tool(fn) / the @tool decorator — a function becomes a tool |
| HTTP / REST | http_tool(...) — an endpoint becomes a tool, ${ENV} headers |
All four appear as one uniform Tool in tk.tools(), with source in "mcp" | "skill" | "custom".
Built-in tools
A fifth source ships 10 built-in tools — bash, read, write, edit, grep, glob,
webfetch, question, apply_patch, todowrite (names + input schemas match
opencode) — so an agent can act with zero wiring. They appear in the tool schema
(to_openai()/to_anthropic()/to_gemini()), like MCP tools — not the system prompt.
On by default. One global toggle turns the whole source off, or a per-tool tools map
disables individual builtins on the all-on baseline:
tk = await create_toolkit(mcp_config="./mcp.json", builtins=False)
# also accepts {"disabled": True} or {"enabled": False}
# per-tool: drop bash, keep the other nine (unknown names ignored; whole-source-off still wins)
tk2 = await create_toolkit(mcp_config="./mcp.json", builtins={"tools": {"bash": False}})
bash/write/edit/apply_patch run commands and mutate the filesystem — the toggle is the
off-switch for locked-down hosts.
A2A agents (agent-to-agent)
Call remote A2A agents (each of their skills becomes a tool) and serve your own toolkit as an
agent other A2A peers can call. A genuine, minimal subset of real A2A (JSON-RPC 2.0; Agent Card at
/.well-known/agent-card.json; SendMessage → poll GetTask). No streaming / push / auth in v1.
Outbound — call a remote agent. Each advertised skill becomes a tool named <agent>_<skill>
(source="a2a"):
from toolnexus import create_toolkit, agent
tk = await create_toolkit(
agents=[agent("https://researcher.example.com/.well-known/agent-card.json")],
)
# or add one at runtime (an Agent or a bare card URL):
await tk.add_agent("https://writer.example.com/.well-known/agent-card.json")
agent(card, *, headers=None, timeout=None, poll_every=None) — headers support ${ENV}
expansion (never logged); timeout / poll_every are milliseconds (300000 / 1000 defaults). A
config file can also carry an agents block. A failing agent is isolated — contributes no tools,
never fatal.
Inbound — serve your toolkit as an agent. The Agent Card is built from your SKILL.md skills (never raw tools):
from toolnexus import create_client
agent_client = create_client(base_url="https://openrouter.ai/api/v1", style="openai", model="openai/gpt-4o-mini")
handle = await tk.serve("127.0.0.1:0", client=agent_client, a2a={
"name": "research-agent",
"description": "Answers research questions.",
# "skills": ["hello-world"], # subset of skills to advertise; omit ⇒ all
"store": "memory", # "memory" (default) | "file:<dir>" | a custom TaskStore
})
print(handle.url) # GET /.well-known/agent-card.json ; POST / (SendMessage / GetTask)
await handle.stop()
serve(addr, *, client, a2a=None, on_task=None) fulfils each inbound task via client.run. Task
persistence is a pluggable TaskStore — in-memory default, "file:<dir>", or your own.
API
| Python | Description |
|---|---|
await create_toolkit(...) |
async factory → Toolkit |
create_client(...) |
the unified host loop (await agent.run(msg, tk) / agent.stream(...)) |
tk.tools() / tk.get(name) |
the uniform tools |
await tk.execute(name, args, ctx=None) |
run a tool → ToolResult |
tk.skills_prompt() |
system-prompt skill catalog |
tk.mcp_status() |
per-server connection status |
tk.to_openai() / to_anthropic() / to_gemini() |
provider tool schemas |
tk.register(*tools) |
add native/http/custom tools |
await tk.close() |
disconnect MCP servers |
More
Full docs, the other four language ports, the shared behavior spec, and runnable examples: https://github.com/muthuishere/toolnexus
MIT licensed.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file toolnexus-0.2.1.tar.gz.
File metadata
- Download URL: toolnexus-0.2.1.tar.gz
- Upload date:
- Size: 105.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1c50745663b592ed5fd94df3e36749def247df5cdeee72e6963e20d2d241f3b8
|
|
| MD5 |
3aaef6ba72efc7f806bd05572badf5b4
|
|
| BLAKE2b-256 |
61f1924de11623cc8360f9721bc533f3b7b83811212da8ecd66f809b3f07bde6
|
Provenance
The following attestation bundles were made for toolnexus-0.2.1.tar.gz:
Publisher:
release.yml on muthuishere/toolnexus
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
toolnexus-0.2.1.tar.gz -
Subject digest:
1c50745663b592ed5fd94df3e36749def247df5cdeee72e6963e20d2d241f3b8 - Sigstore transparency entry: 2038328699
- Sigstore integration time:
-
Permalink:
muthuishere/toolnexus@ba9f4d87db821b99d94cb3c880bd469163ca83e5 -
Branch / Tag:
refs/tags/v0.2.1 - Owner: https://github.com/muthuishere
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@ba9f4d87db821b99d94cb3c880bd469163ca83e5 -
Trigger Event:
release
-
Statement type:
File details
Details for the file toolnexus-0.2.1-py3-none-any.whl.
File metadata
- Download URL: toolnexus-0.2.1-py3-none-any.whl
- Upload date:
- Size: 46.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
98b62f4e273a37bb046f0d5da879c1908dab6e565e7343441bf7ebe7cf53397a
|
|
| MD5 |
5b57f9f70aa1451fb3373f99786b16fa
|
|
| BLAKE2b-256 |
583507dfab43342ffc66b05a18d0d6170f96b6b3b91e0931fb973c1e330ce128
|
Provenance
The following attestation bundles were made for toolnexus-0.2.1-py3-none-any.whl:
Publisher:
release.yml on muthuishere/toolnexus
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
toolnexus-0.2.1-py3-none-any.whl -
Subject digest:
98b62f4e273a37bb046f0d5da879c1908dab6e565e7343441bf7ebe7cf53397a - Sigstore transparency entry: 2038328820
- Sigstore integration time:
-
Permalink:
muthuishere/toolnexus@ba9f4d87db821b99d94cb3c880bd469163ca83e5 -
Branch / Tag:
refs/tags/v0.2.1 - Owner: https://github.com/muthuishere
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@ba9f4d87db821b99d94cb3c880bd469163ca83e5 -
Trigger Event:
release
-
Statement type:
