Use Zyx from your AI tool

Zyx is itself an MCP server. Any AI tool that speaks MCP can use it, and tools without an MCP client can use the same tools over REST. Your tool does the thinking. Zyx runs only its own tools, through the same gates as in Zyx’s own workspace.

The examples on these pages use https://zyx.example.com as the address of a company’s Zyx. Your operator gives you the real one.

Setup pages

Tool	How	Proven live?
Claude Code	MCP, API key or OAuth	API key: yes. OAuth: not yet
Codex	MCP, API key or OAuth	not yet
Cursor	MCP, API key or OAuth	not yet
Pi	REST with an API key	not yet
ChatGPT	MCP, OAuth only	not yet

“Not yet” means the setup follows the tool’s documented way and Zyx’s server side is covered by Zyx’s own tests, but nobody has run that tool against a real Zyx.

Two ways to sign in

• API key. The owner makes a key on Manage, API & MCP. A key acts as one person, and its scopes say what it may do. It is shown once and stored only as a hash. Revoke it on the same screen.
• OAuth 2.1. Zyx is its own authorization server: the tool registers itself, opens Zyx’s consent screen, and the person signs in to Zyx and ticks the scopes. It uses PKCE, refresh tokens that rotate (a reused one ends the grant) and revocation. Access tokens live an hour, refresh tokens 30 days, and only their hashes are stored. A grant is a key acting as that person: it shows on the keys screen labelled OAuth, and every gate and limit applies unchanged.

OAuth from outside the private network needs the operator to publish /api/mcp, the three metadata paths (/.well-known/oauth-protected-resource, /.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-authorization-server) and /oauth. Nothing else of Zyx is made public. OAuth access tokens work for /api/mcp only; the REST API takes API keys.

Scopes

Scope	What it allows
ask	asking Zyx or one of its agents in a new or an existing chat (zyx_ask). Zyx does the work with its own skills and tools, and anything consequential waits for a card
skills	listing the company’s saved skills and running one by name (zyx_skills, zyx_run_skill). Each skill’s own steps and approvals apply
read	search with sources, search_people, read_item, reading files and documents, the wiki, skills, routines, memory, waiting cards and recent chats, each as that person sees them
tools	changes: files and sheets, the wiki, memory, skill and routine drafts, mail drafts and sends, and the connected apps’ own tools
approve	pressing Approve or Reject on a card, from a person’s own screen. It stands alone on its key and never goes into an AI tool’s config, so the tool that asks never holds the key that decides. Not available over OAuth

An OAuth grant never gets approve, nor the owner-only scope for fleet status. Shell and coding tools are not served over MCP.

Same gates, and stricter

• Every call runs as the key’s person: their folders, their readers, the privacy gate both ways.
• Zyx cannot see what your tool read before it called, so every change that would need a card is a card. No automatic risk judgement waves it through.
• A wiki page, a memory line, a skill, a routine and every mail send are always a card.
• A held call answers waiting-for-approval with the card’s link, and does not block. A person approves in Zyx, and the approval runs the call itself. Do not call again: that could run the action twice. Read the result with zyx_card, or over REST with GET /api/v1/approvals/<card>.
• A tool that supports URL elicitation is asked to show its user the card’s link.
• At most 120 tool calls a minute per key. Other requests count against a wider read budget.
• All calls of one key and folder land in one chat in Zyx, named MCP: <key>, so a person can see what the tool did.

What the tool gets

• Tools: the list above, by scope, plus every connected app’s own tools.
• Citations: a search or read result carries citations: each source’s path, title, place and the link that opens it in Zyx.
• Prompts: every skill the person may use is also an MCP prompt.
• Resources: zyx://wiki/, zyx://skill/ and zyx://card/.
• ChatGPT’s shape: search and fetch, the same readers in OpenAI’s format.

Work in one folder, or in private

• Add ?folder=<folder> to the URL to work inside one folder, for example one client’s.
• A staff member adds ?private=1 (or no folder at all) to work in their private session. Their own sign-ins answer there and every card is theirs alone. The owner’s key cannot open one.

REST

The same tools answer over REST for tools with no MCP client: GET /api/v1/tools lists what a key may call, and POST /api/v1/tools/<name> calls one. 200 is the answer, 202 a card waiting for a person, 403 refused, 404 no such tool for this key, 400 bad input. See Pi for an example.