Customer guide

Host recipes (23 coding agents)

Three ways in, one verdict path. kya connect writes the host config itself (merge, never clobber). Config recipes are copy-paste examples for hosts whose config is not safe to write programmatically. kya wrap covers any CLI with no MCP support - it gates the invocation, and only the invocation. Every recipe below links to the full OSS page with a verify step, uninstall, and troubleshooting.

Cursor (IDE + Agent CLI)

kya connect cursor → ~/.cursor/mcp.json. One config covers the IDE and the Agent CLI.

OpenCode

kya connect opencode → ~/.config/opencode/opencode.json (under the mcp key). --project for per-repo wiring.

Qwen Code

kya connect qwen → ~/.qwen/settings.json. Stdio or hosted variant - never enable both.

Kimi Code CLI

kya connect kimi → ~/.kimi-code/mcp.json.

Kiro CLI

kya connect kiro → ~/.kiro/settings/mcp.json. --project for per-repo wiring.

Kilo Code CLI

kya connect kilo → ~/.config/kilo/kilo.json (same local-server shape as OpenCode).

MastraCode

kya connect mastracode → ~/.mastracode/mcp.json.

Amp

kya connect amp → ~/.config/amp/settings.json. Amp prefixes its root key (amp.mcpServers); connect handles it.

GitHub Copilot CLI

kya connect copilot → ~/.copilot/mcp-config.json. Global config only - no project scope.

Claude (Code, Desktop, claude.ai)

kya start wires .mcp.json in a project. Desktop and claude.ai use the shipped examples in the public package.

Hosted-plane hook (early access): kya connect claude --hooks --hosted --plane-config <absolute path> evaluates every Claude Code tool call on your workspace and denies when the plane cannot answer. See Hosted-plane hook.

Roll the Claude Code plugin out to your team

With a kya release that includes kya team (not every published version has it: kya --help lists team init when yours does), run kya team init in the repository and commit the .claude/settings.json it writes: it registers the shield-kya marketplace pinned to the release tag that matches your kya version and enables kya@shield-kya. A prerelease kya (npm next) refuses, because a prerelease has no public tag: use a stable kya. Every teammate sees Claude Code's folder trust prompt once; nothing is accepted for them. A tag can be moved by anyone with write access to the public repository, so check it exists before you commit. For every machine in an organization, kya team managed-settings prints the managed-settings JSON an admin deploys. This is the OSS plugin: advisory, fails open, blocks the never-list and the guard pack. Hosted enforcement is separate. Guide: docs/team-rollout.md.

Codex (OpenAI)

Merge openai/codex.config.example.toml into ~/.codex/config.toml by hand - TOML with its own conventions.

Gemini CLI

Merge the stdio or hosted example into ~/.gemini/settings.json. Keep "trust": false. Verified in CI: gemini mcp list shows shield-kya after wiring.

Grok

Hosted-only: grok.com rejects localhost. Add a custom connector at https://shield-agent.com/mcp with a Bearer machine key. Never tunnel the OSS server.

Cline (VS Code)

Config lives in VS Code globalStorage - merge the example by hand. Keep autoApprove empty. Weakest MCP coverage of the MCP hosts.

Droid (Factory)

Prefer droid mcp add. The on-disk schema is unverified - the shipped example is a starting point, not gospel.

Pi

No documented MCP support. kya wrap --offline -- <cmd> gates the invocation only.

OMP

Local model-runner CLI, no MCP. Wrap gates the invocation only.

Devin CLI

Cloud dev agent. Wrap gates the launch command - not what the agent does inside its own environment.