Connect an assistant to Topaz so it can look up syntax, check code, and inspect execution results. For an assistant that reads URLs, start with the reference file below.
To call tools, install Topaz and use an assistant with local MCP support. MCP is the protocol the assistant uses to discover and call these tools.
Connect the tools
Add this command to your client's local MCP server settings.
{
"command": "topaz",
"args": ["mcp", "serve"]
}The client starts the installed executable and exchanges messages through standard input and output, called stdio. Topaz includes the server and its worker process on all supported native platforms. No separate server download or worker path is needed.
After connecting, the client should list topaz_spec, topaz_examples, topaz_check, and topaz_run. If it cannot start topaz, check the installation and the executable path available to the client.
Check the connection with a call
Use the tool name and JSON input from this table. The expected values also appear in the verification block of mcp.json.
| Tool | Input | What to check in the response |
|---|---|---|
topaz_spec | {"section":"The everyday working set"} | status is found, followed by the requested reference section |
topaz_examples | {"concept":"function"} | status is found, with function examples from the installed reference |
topaz_check | {"source":"function main() -> int { 42 }\n"} | status is clean and diagnostics is empty |
topaz_run | {"source":"let answer = 40 + 2\nanswer\n"} | status is completed and value is "42" |
topaz_check returns syntax, name, and type diagnostics with their original codes and source positions. If status is diagnostics, fix the reported location in the submitted source and call it again. Test application behavior with representative inputs as well.
topaz_run checks the source before starting a fresh worker process. Read toolchain and compiler_selection in the check response. The run response identifies the product and worker through semantic_identity and execution_identity. The default compiler is self. Rust is the reference compiler selected explicitly with --compiler rust for comparison. See Toolchain Status for compiler details.
Apply the Agent Pack rules
A profile adds named rules to the source check. To use the Agent Pack rules, add "profile":"agent-pack" to a topaz_check input alongside source.
The response uses schema topaz.mcp-check-result/v2 and includes profile: "agent-pack". When a profile rule rejects the source, find its name in the diagnostic's data.profileRule. Change the reported operation according to the profile rules. Without profile, the response uses topaz.mcp-check-result/v1.
Know what submitted code can access
Submit code you trust. The worker denies host operations, but it does not provide operating-system isolation.
Each run starts a new worker from the installed Topaz executable. Submitted code has no filesystem or network access, host discovery, callbacks, component loading, or fallback execution path. Calls do not share execution state. Source arrives through stdin and is neither logged nor retained.
| Limit | Behavior |
|---|---|
| Two active runs | Additional calls are rejected without a queue |
| Five seconds per run | A worker exceeding the wall-clock limit is terminated |
| 1 MiB response | A worker exceeding the response limit is terminated |
| Cancellation | The worker is terminated and reaped |
The server reaps terminated workers before returning. Read the returned status before using a result. These limits do not impose a hard CPU or memory limit.
Give a URL-reading assistant the reference
Ask the assistant to read this file before writing Topaz code.
https://topaz.ooo/agents.mdIt describes file structure, syntax, host access, and profiles. It also lists unsupported forms such as Vec<T>, async, try, and classes. For missing values, it distinguishes the supported T | null form from using null for every kind of absence.
Choose another reference URL when the assistant needs a different amount of detail.
| URL | Contents |
|---|---|
https://topaz.ooo/llms.txt | Compact document index |
https://topaz.ooo/llms-full.txt | Complete English manual in Markdown |
https://topaz.ooo/docs/<slug>.md | One English page, with title, source route, and specification sections in its frontmatter |
https://topaz.ooo/version.json | Version served by the site |
https://topaz.ooo/mcp.json | Tool inputs, local command, execution limits, and connection checks |
Use Syntax at a Glance to find language forms. For connecting a program to other systems, continue to Interop Boundaries.