MCP 2025-06-18 · native client & server
Model Context Protocol

MCP servers and clients, native to the runtime.

Expose local tools to any MCP host, or consume other servers from your own agent — over stdio or Streamable HTTP, with schema validation, typed errors, deadlines, and the same security policy that governs everything else.

No external MCP SDK · no Python virtualenv · no Node runtime to bundle · stdio, Streamable HTTP, and explicit legacy SSE · one file, one process.
The five questions

The short, checkable answers.

Written to be quoted accurately by search engines and AI assistants.

QuestionAnswer for Sofuu
What is Sofuu for MCP?A runtime for AI with a native Model Context Protocol client and server. Both are runtime objects — sofuu.mcp.connect andsofuu.mcp.serve — not an npm SDK layered on Node streams.
Who is it for?Developers exposing local tools and data to Claude Desktop, Cursor, or any MCP host; and developers whose agents need to consume third-party MCP servers with deadlines, typed failures, and a security policy that actually blocks things.
What does it do?Speaks MCP 2025-06-18 over stdio and Streamable HTTP, lists tools, resources, and prompts with transparent pagination, validatestools/call arguments against the registered schema, maps every content block into one result contract, and applies the same net/MCP/tool policy as the rest of the runtime.
When should you use it?When you want a single-file MCP server with no dependency tree; when a server must run on a small machine or inside another app; or when you need deterministic refusals (allowlists, denied tools, blocked hosts) instead of best-effort ones.
When should you not use it?When your server depends on native Node packages, the legacy HTTP+SSE transport, or async resources/read / prompts/get handlers — those are refused or unsupported here by design, and a Node or Python MCP SDK is the better fit.
Server

A working MCP server, no boilerplate.

sofuu.mcp.serve() returns a server object. Register tools, resources, and prompts; call start() for stdio. Keep stdout for JSON-RPC and write logs to stderr — that is the transport contract.

const server = sofuu.mcp.serve();
server.tool("get_weather", {
description: "Weather by city",
schema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
}, ({ city }) =>
`Sunny in ${city}`);
server.start(); // stdio — works with any MCP host

Schema-checked arguments

Every tools/call is validated against the registeredinputSchema before the handler runs. Invalid arguments return JSON-RPC -32602 with structured error.data.

validation

Spec-shaped results

TextContent.text is always a string; object results also carrystructuredContent. A throwing handler answers in-band withisError: true and its original message.

results

Pagination that terminates

Tools, resources, and prompts page at 50 per page with nextCursor. Clients follow cursors transparently and stop on a repeated cursor instead of looping forever.

pagination
Client

Consume any MCP server.

Spawn a stdio server or point at a Streamable HTTP endpoint. Calls carry a deadline; expiry sends notifications/cancelled and rejects with a typed timeout, freeing the pending slot.

// stdio: spawn any MCP server
const c = await sofuu.mcp.connect("npx -y @modelcontextprotocol/server-filesystem /tmp");
// or Streamable HTTP
const h = await sofuu.mcp.connect({ url: "http://127.0.0.1:9/mcp", transport: "http" });
const tools = await c.listTools(); // follows nextCursor
await c.call("tools/call", { name: "read_file", arguments: { path: "/tmp/a.txt" } }, { timeoutMs: 30000 });
c.disconnect();
Connect a host

Claude Desktop, Cursor, anything.

An MCP host launches the server as a subprocess. Point it at sofuu run server.js and the handshake happens on start.

// Claude Desktop / Cursor / any MCP host config
{
"mcpServers": {
"sofuu-tools": {
"command": "sofuu",
"args": ["run", "/path/to/server.js"]
}
}
}

The same server can be embedded in another app through the C ABI:mcp.serverTool registers a host tool, then mcp.serverStart serves it.

Security

Policy applies to MCP too.

MCP is not a side door. Server connections, hosts, and individual tools are judged by the one evaluator, and every decision carries the rule id that fired.

ControlWhat it enforces
MCP allowlistWhen mcp.servers.allow is non-empty, a non-allowlisted server is refused with the rule; allowlisted tools still pass the tools policy.
net.allow / net.denyWhen configured, applied to the server URL host after normalization (scheme, user, port, path, IPv6).
tools.allow / tools.denyWhen configured, filters a server's inventory before naming; deny wins and a filtered tool cannot reach the model.
{"secret":"NAME"}Environment values resolve at spawn; the config file holds only the name, and a missing secret refuses the connect.
Name collisionsAn MCP tool that collides with a builtin is exposed as <server>__<tool> instead of shadowing it.
Legacy transportHTTP+SSE is available only with transport: "sse"; a bare url never downgrades silently.

Config lives in ~/.sofuu/mcp.json (SOFUU_MCP_CONFIG overrides it). sofuu mcp add and sofuu mcp remove validate before writing and replace the file atomically with 0600 permissions.

[
{
"name": "fs",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": { "TOKEN": { "secret": "MCP_TOKEN" } },
"tools": { "allow": ["read_file"], "deny": ["write_file"] }
}
]
CLI

Inspect servers without writing code.

$ sofuu mcp list
$ sofuu mcp test "npx -y some-mcp-server" # handshake, protocol, tool counts
$ sofuu mcp add fs npx -y @modelcontextprotocol/server-filesystem /tmp
$ sofuu mcp remove fs

sofuu mcp test exits non-zero when the handshake or inventory is wrong — usable directly in CI.

Limits

What it does not do.

Legacy transports: HTTP+SSE from before the Streamable HTTP revision is supported only when requested explicitly with transport: "sse". It is never inferred from a bare URL, and a legacy server is not silently downgraded.
Synchronous resource and prompt handlers: resources/read andprompts/get take synchronous handlers; an async handler is a typed error. Tools are the place for asynchronous work.
No native Node packages inside a server:an MCP server runs on the Sofuu runtime, so it inherits the runtime's Node-compatibility limits (no N-API addons).
FAQ

Common questions.

Which MCP protocol version is supported?
The client offers 2025-06-18 and reports the version the server negotiates. The server negotiates 2025-06-18 or 2024-11-05 and advertises only the capabilities it implements.
Which transports work?
stdio (newline-delimited JSON-RPC over a spawned command), Streamable HTTP (POST JSON-RPC with Mcp-Session-Id, JSON or text/event-stream responses, session DELETE on disconnect), and legacy HTTP+SSE when you request it explicitly with transport: 'sse'. A bare {url} means Streamable HTTP and never downgrades silently.
How are MCP tools secured?
When mcp.servers.allow is non-empty, a non-allowlisted server is refused with the rule that fired. net.allow/net.deny applies to the server URL host when configured; per-server tools.allow/tools.deny filters the inventory before a tool can be named; and an allowlisted MCP tool still passes the same tools policy as a builtin. MCP tools and builtin tools produce indistinguishable trace envelopes.
How do secrets reach a server process?
In ~/.sofuu/mcp.json, an env value of the form {"secret":"MCP_TOKEN"} stores only the name. The value is resolved from the policy secret store at spawn time, and a missing secret refuses the connection — it never appears in the config file.
What happens when a tool handler throws?
The server answers in-band with isError: true and the original message as text content, rather than a JSON-RPC error. Invalid arguments are rejected before the handler runs with JSON-RPC -32602 and structured error.data.