Claude Code
claude mcp add okyra -- okyra mcp
That adds it for the current project. Add --scope user to have it in every project. To pass a setting to the daemon, such as in a container, use -e:
claude mcp add okyra --scope user -e OKYRA_NO_SANDBOX=1 -- okyra mcp
Agent skill
The MCP server already teaches the agent plans, targets and settle through its own instructions, so with MCP you need nothing else. The agent skill is for agents that reach okyra only through a shell. Install it with:
okyra skill install
That writes ~/.claude/skills/okyra/SKILL.md. Use --dir for a project or another agent, or okyra skill print to paste it into an agent without a skills folder. Every tarball also holds SKILL.md.
Prefer the MCP server where your agent supports it. Through the shell, each plan costs two turns, a file write and okyra run plan.json, because shell tools such as Claude Code refuse JSON inside a command.
Cursor
Add an entry to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project:
{
"mcpServers": {
"okyra": { "command": "okyra", "args": ["mcp"] }
}
}Codex
codex mcp add okyra -- okyra mcp
Or write the entry yourself in ~/.codex/config.toml:
[mcp_servers.okyra] command = "okyra" args = ["mcp"]
Claude Desktop
Open Settings, then Developer, then Edit Config. That opens ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Add okyra, then quit and reopen Claude Desktop:
{
"mcpServers": {
"okyra": { "command": "/usr/local/bin/okyra", "args": ["mcp"] }
}
}Desktop apps do not always see your shell PATH, so give the full path. command -v okyra prints it.
Other MCP clients
Any client that starts a stdio server needs the same two things: the command okyra (or its full path) and the argument mcp. The server speaks MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
Tools and parameters
Every tool also takes page, the page label (default p1). A page opens on first use and stays open between calls.
| Tool | Parameters | Does |
|---|---|---|
okyra_goto | url (required) | Opens a URL and waits until the page settles. Returns url, title, settled. |
okyra_snapshot | interactive (boolean), max_lines (default 400) | Text outline of the page with refs for interactive elements. |
okyra_click | target (required) | Clicks, then waits for the page to settle. |
okyra_type | target, text (both required) | Clicks the field, clears it, types. Also fills date and time inputs. |
okyra_select | target, value (both required) | Picks a dropdown option by value or visible text. |
okyra_upload | target, files (array of absolute paths, both required) | Attaches files to a file input, the input a label points at, or the first file input inside the target. Works on hidden inputs. |
okyra_hover | target (required) | Moves the mouse over the target and returns the text that appeared, such as a tooltip. Null when nothing appeared. |
okyra_press | key (required) | Presses Enter, Tab, Escape, Backspace, an arrow, or one character. |
okyra_scroll | target, or dy and dx in pixels | Scrolls an element into view, or the window. |
okyra_text | target (required) | Visible text of one element. |
okyra_extract | target (required), limit (default 200) | Every match as JSON: table rows as arrays of cell texts, list items as text. |
okyra_eval | expression (required) | Runs JavaScript in the page and returns the JSON result. |
okyra_screenshot | annotate (boolean) | Viewport screenshot returned as an image. With annotate, refs are drawn on it and listed. |
okyra_plan | steps (required, array of steps) | Runs many steps in one call. See plans. |
okyra_pages | none | Lists open page labels. |
okyra_close | page (required) | Closes a page. |
Target: a ref like @e7, role and name like button "Next", a point like 420,260, or a CSS selector. See targets.
What the agent gets back
- A result as text: JSON for objects, the bare string for text.
- A failed action comes back as a tool error with the message, such as
no element matches #sign-in. - A plan that stops on a failed step comes back as a tool error holding the plan result: the error, the step index and a snapshot of the page.
- A screenshot comes back as a PNG image, plus a text legend like
@e7 button "Next" at 420,260whenannotateis on. The file is deleted after it is read.
The server sends instructions to the client when it starts. They tell the agent to do a task in as few calls as it can, put steps in one okyra_plan ending with the read it needs, and use each, repeat and hover for lists, pagers and tooltips. Nothing is printed to stdout but MCP messages, and the licence reminder is never shown there.