Skip to main content

MCP

Introduction​

Agivar includes a built-in MCP (Model Context Protocol) service. External clients that support MCP can hand desktop tasks to Agivar, such as asking a coding assistant to verify a local web page, operate a desktop app, reproduce an issue, or check whether a workflow actually completed.

MCP tasks create conversations inside Agivar, so you can watch progress live in the app. When a task finishes, the external client can read the summary, tool observations, and captioned screenshots to judge whether the task succeeded.

Before using MCP, open Agivar and sign in. Only run one GUI task at a time; if another task is still running, wait for it to finish or cancel it before starting a new one.

Skill File (Optional)​

If your AI client supports Skills or custom skill files, you can download Agivar's SKILL.md and use it with the built-in MCP service. The file tells the client how to connect to Agivar MCP, poll results with the get_status -> run_gui_task -> get_task_result workflow, continue a task, cancel a task, and read screenshot evidence.

This file is not required to connect to MCP. Its purpose is to help Skill-aware clients use Agivar's desktop task capability more reliably. After downloading it, place it in the skill directory required by your client.

Download Agivar GUI Task SKILL.md

Connection​

Fitten Code​

  1. Open the Fitten chat page, click the user avatar in the upper-right corner, and choose "Feature Configuration -> MCP" to open the MCP page.
  2. Click "Add Configuration" to open the mcp_settings.json file, then add the agivar configuration:
{
  "mcpServers": {
    "agivar": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:17342/mcp"
    }
  }
}
  1. Import the custom SKILL: click the SKILL icon in the upper-right corner of the chat page, click the import button in the upper-right corner of the SKILL page, then select the folder that contains SKILL.md.

Claude App​

  1. Add a custom MCP Server: open "Settings -> Developer -> Edit Config", then open the corresponding configuration file and add this configuration:
{
  "mcpServers": {
    "agivar": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:17342/mcp"
      ]
    }
  },
  ...
}
  1. Add the custom SKILL: put the SKILL folder under $HOME/.claude/skills, then restart.

Codex App​

  1. Add a custom MCP Server: open "Settings -> MCP servers", click "Add server", set "Name" to agivar, choose "Streamable HTTP" as the type, set "URL" to http://127.0.0.1:17342/mcp, then click "Save".
  2. Add the custom SKILL: put the SKILL folder under $HOME/.codex/skills, then restart.

Available Tools​

ToolPurpose
get_statusChecks whether Agivar is signed in, whether it is busy, and whether any MCP task is currently running.
run_gui_taskStarts a new desktop GUI task. Provide a natural-language task description and optional background context; the call immediately returns a task_id.
get_task_resultQueries progress or the final result for a task_id. While the task is running, it returns current progress; after it ends, it returns a summary, observations, screenshots, and error information.
send_task_messageContinues the same MCP task conversation with a follow-up instruction, useful for refining, checking more, or taking the next step after a task finishes.
cancel_taskCancels a running GUI task. After cancelling, keep calling get_task_result until the task reaches a final state.

Examples​

Verify a Local Page​

You have started a local frontend page and want a coding assistant to confirm that the page opens, a button is clickable, and a dialog behaves as expected. An external MCP client can start a task like this:

Open http://localhost:5173, go to the settings page, switch the language, confirm that the UI text updates, and include screenshots in the result.

Agivar will open the page and operate the real desktop. When the task finishes, the client can read the summary and screenshots, then report the verification result back to you.

Reproduce a Desktop Interaction Issue​

If a problem only appears during real desktop interaction, give Agivar the reproduction path:

Open Agivar, go to the recording entry, and try to start a screen recording. If a system permission dialog appears, record which step is blocked and return a screenshot.

This is useful for issues that are hard to judge from code alone, such as permission dialogs, system settings, covered windows, or buttons that cannot be clicked.

Continue After a Task Finishes​

If the first task finishes but you need more work, you do not have to start a new task. Use the same task_id to send a follow-up:

You already opened the settings page. Now continue and check whether the recording history entry in advanced settings can be opened.

Agivar will keep the previous conversation context and continue the next check.

Cancel When a Task Goes Off Track​

If the external client notices that the task opened the wrong page, entered the wrong account, or made no useful progress for a long time, it can call cancel_task to stop the current task. After it stops, decide from the final result whether to start a clearer task.

Next​