FAQ

FAQ

Short answers to the questions that come up first.

Applies to: zig-sdk 0.1.0. The answers that name version 0.2.0 apply to zig-sdk 0.2.0.

Which MCP revision does the SDK speak?

Only 2026-07-28. Older revisions had an initialize handshake and sessions. This revision is stateless. A client of an older revision gets -32601 for initialize with a message that names 2026-07-28. See Versioning.

Can VS Code use my server?

Not directly. The MCP clients of VS Code speak revision 2025-11-25 and start with initialize, which the SDK refuses. Use the bridge of zig-bridge-sdk. Its executable mcp-bridge-vscode is a stdio server for VS Code that starts your server as a child process. Or embed the bridge: depend on the package bridge_sdk and call vscode.serveStdio in place of mcp.transport.stdio.serve. See its wiki page VS Code.

Does the SDK have dependencies?

No. It needs Zig 0.16.0 and nothing else. TLS, HTTP/2, HPACK, protobuf, WebSocket and a D-Bus client are in the tree. The test fixtures from the MCP repository, the JSON Schema Test Suite and the proto files of the typed gRPC binding are data, not code. The RFC 7541 tables are also data.

Can I use the standard library TLS client instead of the SDK client?

The HTTP client used it before the SDK client existed. It has no ALPN and no client certificates, so the gRPC binding cannot use it. The SDK client is the only path now.

How do I add a tool?

Write a handler fn(ctx: *mcp.RequestContext, args: Args) anyerror!mcp.Outcome(mcp.CallToolResult) and register it with server.addTool(.{ .name = "..." }, handler). The input schema comes from the Args type. See Server Guide.

How does a tool ask the user something?

It returns .input_required with an elicitation. The client answers it and sends the request again with the answers. The server keeps its state in a sealed requestState. See Concepts.

Does the validator support all of JSON Schema 2020-12?

Yes, from version 0.2.0. The validator evaluates all keywords of 2020-12, also unevaluatedProperties, unevaluatedItems, $dynamicRef and $id in subschemas. format and the content keywords are annotations, as 2020-12 specifies. The draft 2020-12 files of the JSON Schema Test Suite run with the tests. The limits are remote references, custom meta-schemas and some regular expression features. See JSON Schema Support.

Does a request have a default timeout?

Yes, from version 0.2.0. A client request without timeout gets limits.request_timeout (60 s). A longer timeout gets the upper limit limits.max_total_timeout (600 s). Progress notifications do not extend a timeout. A listen stream has no default timeout. See Client Guide.

Does the validator support regular expressions?

Yes, from version 0.2.0. The SDK has its own engine for pattern and patternProperties, with the ECMA-262 syntax. The match time is linear in the input length. Backreferences and lookaround are not available. See JSON Schema Support.

Does the TLS code support post-quantum key exchange and RSA keys?

Yes, from version 0.2.0. The hybrid group X25519MLKEM768 is the first choice of the default order on both sides. The server and the client accept RSA certificate keys of 2048 to 4096 bits and sign with RSA-PSS. See TLS and Certificates.

Can a local client connect without HTTP?

Yes. Use stdio when the client starts the server. Use the Unix socket transport when the server runs already and serves many local clients. See Transport Unix Socket.

How do I run something long?

Enable the Tasks extension and return .start_task from the tool. The client polls the task or, with callTool, waits for it. See Tasks Extension.

Why does the wiki read the way it does?

The prose follows ASD-STE100 Simplified Technical English, customized for this project. Short sentences, one meaning per word, active voice. zig build lint-docs checks it. See Style Guide (STE).

How do I put the server behind nginx or Caddy?

Bind the SDK server to loopback and let the proxy terminate TLS. Add the public name to allowed_hosts when the proxy forwards it. See Deploy Reverse Proxy.

Where are the API docs?

On the documentation site, https://christianpresley.github.io/zig-sdk/. zig build site writes the same site to zig-out/site, and zig build docs writes the reference of the module mcp to zig-out/docs. See API Reference.

How do I report a security problem?

See SECURITY.md in the repository. Do not open a public issue for it.