Get your agent ready for Gryz

After you connect and authenticate Gryz MCP, ask your assistant: “Set up Gryz for this workspace.” It should call agent_onboarding. This is the single setup router for publishing, Notes, Agent Memory, User Skills, Tasks, and future Gryz capabilities, when enabled for your account.

How the setup loop works

1. The tool asks where instructions should live: the current project, your personal agent configuration, both places at once, or manual copy.
2. It returns exactly one action and an opaque continuation.
3. For a local write, your assistant must show the semantic targets and change summary, then wait for your explicit approval.
4. Only after the whole action succeeds does the assistant call the tool again with that continuation and the exact acknowledged_action_id.
5. Repeat until status is current and next is null.

Gryz is stateless between MCP requests. The signed, 24-hour continuation carries setup acknowledgements without a progress table or server session. A changed capability or version can make a later call return new work; current is scoped to the returned registry revision.

Every response also includes a read-only setup_state report: the capabilities and token scopes live on this connection, and whether a continuation was supplied. It is derived only from live signals — Gryz never inspects your files to build it — so it is a status summary, not the source of truth for what is installed.

If a follow-up call refers to a step that has already been completed or superseded, Gryz keeps the verified session: your earlier progress stays acknowledged and it simply re-offers the current step. An acknowledgement is only discarded when the continuation itself cannot be verified (wrong account, tampered, or older than 24 hours), in which case setup restarts cleanly with nothing saved.

When Gryz cannot identify the repository

Project-scoped memory needs a stable project key so the same facts show up in every tool you use on this repo. git_remote accepts the plain host/owner/repo form as well as https://, git@, and ssh:// URLs, and folds them all to one key. If the value cannot be parsed, or none is supplied, Gryz returns a repo_unidentified warning and pauses the memory step — it will not save project facts under a key that will not line up elsewhere. Fix it by re-running setup from inside the project folder, passing the repository's web address, or choosing to keep memory with you personally instead.

Collapsing a CLAUDE.md import stub

If your repo CLAUDE.md only contains @AGENTS.md, tell Gryz with client.repo_claude_imports_agents: true. It then proposes a single AGENTS.md write instead of putting the identical block in both files. This hint can only reduce the write set; it never adds a path.

Local writes and manual setup

Calling agent_onboarding is read-only on Gryz. A returned write_files action is only a proposal. It always declares downstream_effect: "local_write" and requires_confirmation: true; the assistant must not write until you approve the displayed targets.

Clients without a writable filesystem receive manual_copy instead. Copy the exact marked blocks into the suggested agent instructions and confirm completion before the assistant acknowledges the action. Gryz never accepts an arbitrary destination path, and repo_path is used only to derive a private project key—not as a write target or returned value.

Where the personal note goes, per client

The personal and both scopes write a short standing Gryz note into your client's global agent-config file. That file applies to every project you open, so the note stays general and carries no project key or account identifier. Onboarding only ever proposes one of these fixed paths:

Gryz emits the literal ~/... string. Your client resolves ~, and any $CODEX_HOME or $GEMINI_* override, when it performs the write, so the previewed path may land in a machine-specific location. The Windsurf global rules file has a 6,000-character limit; the Gryz note is kept well under it.

The both scope writes the project file (with its project key) and the global file (standing note only) in a single confirmed action.

Ask about one capability

Use focus for “how do I use X?” requests — for example "notes", "memory", "skills", "tasks", "document_editing" (how an assistant keeps a long document current without resending it), or "agent_team" (how a team member uses its own private memory and get_profile):

{ "focus": "skills" }

If that capability is configured, the tool returns usage guidance. If it is unavailable, it says so and lists what is live; the assistant must not invent a second setup_* tool.

OAuth reconnection

The scopes on the credential used for the current MCP request are authoritative. If an OAuth connection lacks a required scope, onboarding proposes a first-party authorization URL. Approve navigation, finish authorization, reconnect the client with the new token, and resume with the continuation. API-key callers are not sent through OAuth merely because they use an API key.

Compatibility

setup_memory remains available only as a deprecated compatibility alias for existing clients. New setup starts with agent_onboarding; its memory capability returns the same project-key derivation, Markdown block, Cursor .mdc block, and placement guidance.

See the complete MCP tool contract or the always-available MCP setup fallback.