MCP servers

Why you need this

MCP is the emerging standard for tool servers — filesystem, GitHub, Postgres, Slack, your own internal services. Instead of hand-coding a client for each one, you point at an mcp.json and every server’s tools show up as uniform tools your model can call. It is vendor-neutral: reuse the whole MCP ecosystem without writing integration glue, and swap or add servers by editing config, not code.

Point the toolkit at an mcp.json — local stdio servers (command) and remote streamable-HTTP servers (url) both work, and their tools join the same tool set. A failing server is isolated (status failed); it contributes no tools and never breaks the build.

JavaScript

const tk = await createToolkit({
  mcpConfig: "./mcp.json",        // path, raw JSON string, or a parsed object
})
console.log(tk.tools().map((t) => `${t.name} (${t.source})`))

Python

tk = await create_toolkit(
    mcp_config="./mcp.json",       # path, raw JSON string, or a parsed dict
)
print([f"{t.name} ({t.source})" for t in tk.tools()])

Go

tk, _ := toolnexus.CreateToolkit(ctx, toolnexus.Options{
    McpConfig: "./mcp.json",                      // path, raw JSON, or parsed map
})

Java

Toolkit tk = Toolkit.create(new Toolkit.Options()
        .mcpConfig("mcp.json"));      // path, raw JSON string, or a parsed Map

C#

await using var tk = await Toolkit.CreateAsync(new Toolkit.Options()
    .WithMcpConfig("./mcp.json"));   // path, raw JSON string, or a parsed dict

Elixir

{:ok, tk} = Toolnexus.create_toolkit(
  mcp_config: "./mcp.json"           # path, raw JSON string, or a parsed map
)

Clojure

(require '[toolnexus.core :as tn])

(def tk (tn/build {:mcp "./mcp.json"}))    ; path, raw JSON string, or a parsed map
(tn/tool-names tk)                          ; sorted; (:statuses tk) shows any failed server

Rust

use serde_json::json;
use toolnexus::{McpConfigInput, ToolkitOptions, create_toolkit};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // usually McpConfigInput::Path("mcp.json".into()); inline here so the recipe runs offline
    let tk = create_toolkit(ToolkitOptions {
        mcp_config: Some(McpConfigInput::Json(json!({"mcpServers": {
            "everything": {"type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-everything"], "enabled": false},
            "broken": {"type": "local", "command": ["no-such-mcp-binary"]}
        }}))),
        ..Default::default()
    }).await?;
    for (server, status) in tk.mcp_status() {
        println!("{server}: {}", status.as_str()); // connected | disabled | failed
    }
    // a server that fails never takes the toolkit down; its tools are just absent
    assert_eq!(tk.mcp_status()["everything"].as_str(), "disabled");
    assert_eq!(tk.mcp_status()["broken"].as_str(), "failed");
    // tools are named sanitize(server)_sanitize(tool), e.g. everything_echo
    tk.close().await;
    println!("ok: mcp status reported");
    Ok(())
}

An mcp.json — both server kinds shown:

{
  "mcpServers": {
    "filesystem": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-api": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
    }
  }
}

${MCP_TOKEN} expands from the environment at call time and is never logged. The top-level key may be mcpServers, servers, or mcp. See MCP servers for the full config surface (per-server timeouts, tool allowlists, elicitation).

Next: Agent skills.