download_for_offlineRails Path

An Autonomous Developer on Your Machine in Two Minutes

Install mcptask_runner in your Rails project — one command. It runs locally against your real database, picks the right model (Claude, Kimi, DeepSeek, or local ollama), and hands you ready PRs by the time you sit down. Hand it well-specified work in the evening — find the PRs done in the morning.

Start Free Trial
terminal
mcptask_runner installer$ rake mcptask_runner:install
→ Installing skills into./.claude/skills/
→ Checking required helpers✓ ok
→ Merging permissions into.claude/settings.local.json
→ ProvisioningMCPTASK_TOKEN
→ Writing.mcp.json✓
→ macOS LaunchAgent scheduled (weekdays 08:00)✓
1 lineto install
~2 minto first task

Why This Install Is Different

Other AI agent setups leave you assembling pieces by hand. mcptask_runner ships the whole thing in one command — and keeps your real environment in the loop.

bolt

Zero configuration

One rake task drops the bundled skills, baseline permissions, the MCPTASK_TOKEN, the .mcp.json entry, and the macOS LaunchAgent. With other setups you wire those together by hand.

tune

You pick the model

The runner runs on top of Claude Code with whichever model you configure. Copilot and Codex lock you into their premium model; we let you choose — Claude, Kimi, DeepSeek, or a local ollama.

storage

Your real infrastructure

The agent runs on your machine against your real PostgreSQL, your real system tests, and your real screenshots. Not a stripped-down cloud sandbox with mocked data.

check_circle

It actually finishes

If the agent gets stuck, runs out of context, or is interrupted, the harness recovers and the task lands in a PR. If it hits an unrelated bug, it spawns its own tracked task, fixes it, and gets back to your work.

PR Is Just the Start

The same tool that picks up the work also closes the loop: from PR to merge, to a logged timesheet, to the invoice your client pays. One workflow from task in to cash out.

terminal
PR ready
receipt_long
Timesheet logged
merge
Auto-merged
handshake
Invoice sent
paid
Paid

What You Need Before You Start

Three things — and you almost certainly already have them.

code

An Existing Rails Project

A Ruby on Rails 7+ app you actually develop. The installer drops a few files into its root and your home directory; nothing else is touched.

terminal

Ruby + Bundler

Ruby 3.0+ with Bundler installed. The mcptask_runner gem hooks into your existing toolchain — no extra system packages required.

ruby -v && bundle -v
smart_toy

Claude Code CLI

Claude Code installed and authenticated in your terminal. The runner talks to Claude Code; without it, install is half-useful. Claude Code is a harness — you choose the model underneath yourself (Anthropic, Kimi, DeepSeek, local ollama…), see runner configuration.

Five Steps to a Working Runner

Each step is one short shell command. Read the recap on the next section if you just want the highlights.

1

Add the mcptask_runner gem to your Gemfile

In your Rails project root, open the Gemfile and add the line below. The gem is a small, focused helper — it does not pull in extra runtime dependencies into your app.

codeshell
# Gemfile
group :development do
  gem "mcptask_runner", github: "jchsoft/mcptask_runner"
end

infoWe put it in the :development group because the runner is a developer-machine tool, not a server-side dependency. It will not bloat your production bundle.

2

Run bundle install

Install the gem. You should see "Installing mcptask_runner" in the output.

codeshell
bundle install
3

Run the installer

This is the main event. The installer does the boring setup for you: drops the bundled Claude Code skills, merges baseline permissions, generates your MCPTASK_TOKEN, and writes the .mcp.json file. On macOS it also offers to schedule a daily 08:00 LaunchAgent.

codeshell
bundle exec rake mcptask_runner:install

What just happened

You will be asked which mode to schedule on macOS: Auto squash-merge today's tasks, or Manual run for today. Pick one — you can change it later. Get your MCPTASK_TOKEN beforehand from User → Advanced info → API Token on mcptask.online (the installer also prompts you to paste it).

4

(macOS) Activate the schedule

The installer prints a launchctl bootstrap command at the end. Run it once and the runner will fire on weekdays at 08:00. You can verify with launchctl list | grep mcptask.

codeshell
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/online.mcptask.runner-<slug>.plist

infoLinux / server users: the installer still writes .mcp.json and installs skills, but it does NOT create a LaunchAgent. Use cron or systemd instead. Default morning run: 0 8 * * 1-5 cd /path/to/your/rails && /usr/local/bin/bundle exec rake mcptask_runner:auto:squash:today >> ~/mcptask.log 2>&1. To run in the evening, change the cron expression: 0 22 * * 1-5 cd /path/to/your/rails && /usr/local/bin/bundle exec rake mcptask_runner:auto:squash:today >> ~/mcptask.log 2>&1

What just happened

To change the time on macOS, edit the Hour/Minute integers inside StartCalendarInterval in ~/Library/LaunchAgents/online.mcptask.runner-<slug>.plist, then unload and reload the agent: launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/online.mcptask.runner-<slug>.plist && launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/online.mcptask.runner-<slug>.plist. Replace <slug> with your project directory name (underscores become dashes); find the exact file with ls ~/Library/LaunchAgents/ | grep mcptask-runner.

5

Try one task by hand

Before trusting the schedule, run the runner once manually. It picks the most important task from your queue, works it, and writes a PR. Watch the terminal — no daemon, no detached process.

codeshell
bundle exec rake mcptask_runner:manual:once
descriptionRequired step

Tell the AI Which Project to Work On

Claude Code does not magically know which mcptask.online project or account is yours. Add a short section to your project's CLAUDE.md so it reads the right project from the start.

  • check_circleWithout it, the AI has no idea where to read or write tasks.
  • check_circleFill in the values with YOUR project name, id, and account code (find them in your project's URL on mcptask.online).
  • check_circleKeep it short — the snippet below is everything the runner needs to behave correctly from day one.
codeCLAUDE.md
## mcptask.online
- Project name: <your project name>
- project_relative_id=<your project id>
- account_code: `<your account code>`

## Usage notes
- Access mcptask.online via the MCP server (key: `mcptask-online`).
- Everything is a **piece** — URIs never use `/tasks/` or `/stories/`.
- Always use `relative_id` in URLs / references, never the internal `id`.
- Read with: mcptask://pieces/{account_code}/{piece_id}
- Current user: mcptask://user
- Create pieces via the write tools; **content in English**.

Day-to-Day Commands

These commands cover the typical day-to-day flow. Run them from your Rails project root, with Bundler.

play_arrow

Try one task, supervised

Picks the most important available task, works it, opens a PR. You watch. You learn.

bundle exec rake mcptask_runner:manual:once

Best for first run, debugging, and one-off work.

today

Work the day manually

Runs task after task until your daily quota is reached. Creates PRs but leaves them open for your review.

bundle exec rake mcptask_runner:manual:today

Good for a supervised daily batch where you merge by hand.

account_tree

Full workflow: reviews, then tasks

Processes open PR reviews first, then works today's queue. PRs stay open for review.

bundle exec rake mcptask_runner:manual:workflow

Best for days with active review feedback.

task_alt

Run one specific task

Tell the runner exactly which piece to work. Useful when you want a known task done next.

bundle exec rake mcptask_runner:manual:task[task_id]

Replace task_id with the relative_id from the URL.

folder_open

Run all tasks in a story

Pick up every available task under one story, in priority order. PRs stay open for review.

bundle exec rake mcptask_runner:manual:story[story_id]

Replace story_id with the story's relative_id.

What Just Happened After Install

A short checklist of what `rake mcptask_runner:install` set up for you. If any item is missing, re-run the installer — it's idempotent.

check

Skills installed into .claude/skills/

The bundled Claude Code skills (commit, pr, worktree, …) are copied locally so the runner can use them offline.

check

.mcp.json written

The MCP server entry pointing at https://mcptask.online/mcp/sse with Authorization: Bearer ${MCPTASK_TOKEN} is added.

check

MCPTASK_TOKEN provisioned

Your access token is stored as an environment variable, ready to be used by the runner and Claude Code sessions.

check

Permissions merged into .claude/settings.local.json

Baseline Claude Code permissions (the safe set) are merged in so the runner does not have to ask before every Bash call.

check

macOS LaunchAgent scheduled (08:00 weekdays)

On macOS, a LaunchAgent plist is generated. After you run the printed launchctl bootstrap command, the runner fires automatically on weekday mornings.

check

Linux/server: no scheduler, but full runner still works

On Linux the installer skips the LaunchAgent. The runner, .mcp.json, and skills are still in place — wire it into cron or systemd yourself.

publicAny System

Don't Use Rails? Connect Any AI Agent via MCP

mcptask.online is not just for Ruby on Rails. Any MCP-capable AI agent — Claude Code, Claude Desktop, or any compatible client — can read and work your tasks directly. No gem. No Ruby. Just a tiny config file.

If your AI client supports MCP (Model Context Protocol), the connection takes about two minutes: get a token, add one server entry, and tell your agent which project to work on.

Vysvětlení lidskou řečí

MCP (Model Context Protocol)

The open standard AI clients use to talk to external tools. Think of it as the USB-C cable between your AI agent and mcptask.online — one standard, many devices.

SSE (Server-Sent Events)

The streaming transport mcptask.online uses to push updates to your AI. One open HTTP connection; the server pushes changes as they happen.

Agent

Your connected AI client — Claude Code, Claude Desktop, or any MCP-compatible assistant. The agent is what does the work; mcptask.online feeds it the next task.

Which clients work?

Anything that speaks MCP. As of today:

Claude Code (CLI)

Works

Best fit. Add the server to your .mcp.json and Claude Code can read, list, and create tasks.

Claude Desktop

Works

Add the same server entry to Claude Desktop's MCP settings. Same token, same endpoint.

Other MCP clients

Works

Any client that accepts the standard MCP server config (VS Code Continue, Cursor when MCP-enabled, custom agents) works the same way.

GitHub Copilot / non-MCP tools

Limited

Copilot does not speak MCP natively. Use it as a code editor alongside an MCP-capable agent, or pick a client above.

The mcptask_runner gem is OPTIONAL. It is a convenience wrapper for the fully-autonomous daily loop in a Rails project. Plain MCP read/write works without it on any stack.

Four Steps, No Ruby Required

Pick any MCP-capable AI client, follow the four steps below, and you are connected. Each step is short and copy-paste ready.

1

Get your MCPTASK_TOKEN

Log in to mcptask.online, open User → Advanced info → API Token. Copy the long string. That is your MCPTASK_TOKEN. Treat it like a password — anyone with it can act as you on mcptask.online.

Where to find it
codeWhere to find it
mcptask.online → User → Advanced info → API Token
Shell
codeshell
export MCPTASK_TOKEN=mcptask_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

What just happened

Put the export line in your shell profile (~/.zshrc, ~/.bashrc) so the token is available to every MCP client you start.

2

Add the mcptask-online server to your MCP config

Open your client's MCP config file (e.g. .mcp.json in your project root for Claude Code, or Claude Desktop's developer settings) and add the server entry below. The endpoint, transport, and auth header are exactly the same as what the Rails installer writes — no surprises.

.mcp.json
code.mcp.json
{
  "mcpServers": {
    "mcptask-online": {
      "type": "sse",
      "url": "https://mcptask.online/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${MCPTASK_TOKEN}"
      }
    }
  }
}

infoFor Claude Desktop, paste the same entry into Settings → Developer → Edit Config. The exact file path depends on your OS — Claude Desktop shows the file path in that same dialog.

3

Tell the agent which project to work on

Open your project's CLAUDE.md (or the equivalent context file your AI client reads) and add a short mcptask.online identity section. Without it, the agent has no idea which project or account to read and write tasks for. This is the human-readable way the agent gets its bearings.

Add to your project's CLAUDE.md
codeAdd to your project's CLAUDE.md
## mcptask.online
- Project name: <your project name>
- project_relative_id=<your project id>
- account_code: `<your account code>`

## Usage notes
- Access mcptask.online via the MCP server (key: `mcptask-online`).
- Everything is a **piece** — URIs never use `/tasks/` or `/stories/`.
- Always use `relative_id` in URLs / references, never the internal `id`.
- Read with: mcptask://pieces/{account_code}/{piece_id}
- Current user: mcptask://user
- Create pieces via the write tools; **content in English**.
- The work loop: load the most important task → work on it → check the daily quota → repeat.

What just happened

Find project_relative_id and account_code in the URL when you open your project on mcptask.online (e.g. mcptask.online/p/<relative_id>) and in the project switcher. account_code is the short code under the account name.

4

Verify the connection

Restart your AI client (or reload its MCP config). Ask the agent one plain-English question to confirm it can reach mcptask.online. If it returns a piece, you are connected. If it errors, jump to the FAQ below.

Ask your agent
codeAsk your agent
List the next open task from my mcptask.online project.
Shell
codeshell
mcptask://pieces/{account_code}/@next

What just happened

That URI is the canonical read entry point. If the agent can fetch it and return one task, every other piece URI works too.

How to Confirm It Works

Three quick checks, in order. If all three pass, the connection is good. If any fails, the FAQ below has the most common cause for each.

check_circle

The agent lists your projects

Ask the agent to list your projects. It should return at least one row with a project name and a project_relative_id. If it returns nothing, the token is wrong or the account_code is missing from CLAUDE.md.

Zeptejte se svého agenta
What projects do I have on mcptask.online?
check_circle

The agent fetches the next open task

Ask for the next task. It should return one piece with a title, description, and difficulty. If you have no open tasks, it returns 'no available task' — that is fine, the connection is working.

Zeptejte se svého agenta
Fetch the next open task for me.
check_circle

The agent can read a specific task by URI

Give it an exact URI from the web UI (open any task, copy the relative_id from the URL). The agent should return that task's full details. This is the most reliable end-to-end check.

Zeptejte se svého agenta
Read mcptask://pieces/<account_code>/<task_id> and summarise it for me.

Common Questions, Plain Answers

help_outline

What is MCP, in plain language?

MCP (Model Context Protocol) is a standard way for an AI assistant to talk to other tools. Think of it as a USB cable between Claude Code and mcptask.online — the runner plugs Claude Code into your task queue so the AI can read, work, and log tasks directly.

help_outline

Where does my MCPTASK_TOKEN come from?

User → Advanced info → API Token on mcptask.online. It's a long personal access token that authenticates the runner as you. The installer will also prompt you to paste it during setup, and stores it as an environment variable.

help_outline

Does this work on Linux / Windows / a server?

Yes — the runner, .mcp.json and skills work everywhere. The macOS-only bit is the LaunchAgent scheduler: on Linux or a server, hook the same command into cron or systemd (we give a one-liner on this page). On Windows, use Task Scheduler.

help_outline

Is the runner safe to leave running overnight?

Yes — a well-specified task lands in a PR. The runner runs on your machine against your real database, so it tests, takes screenshots, and pushes commits the same way you would. If the agent gets stuck, runs out of context, or is interrupted, the harness recovers and the task lands in a PR instead of dying halfway. And if the runner hits a bug in code it was not asked to fix, it spawns its own tracked task, fixes it, merges, and gets back to your original work.

help_outline

Can I undo or remove the installation?

Yes. Delete .claude/skills/ (only the ones starting with mcptask_), remove the mcptask-online entry from .mcp.json, and on macOS run launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.mcptask.runner.plist. Then remove the gem from the Gemfile. Nothing else is touched.

forward_to_inbox

Not a Developer? Send This to Your Team

Setup takes about two minutes for whoever runs the project. Forward this page to your dev lead and they will have an autonomous dev wired up before their next coffee.

arrow_forwardSee the business view (no code)

PR Is Just the Start

The same tool that picks up the work also closes the loop: from PR to merge, to a logged timesheet, to the invoice your client pays. One workflow from task in to cash out.

terminal
PR ready
receipt_long
Timesheet logged
merge
Auto-merged
handshake
Invoice sent
paid
Paid
rocket_launch

Get the Token, Then Run the Installer

Two minutes from now you can have an AI agent picking up your most important task. Create a free account, grab your MCPTASK_TOKEN, and you're set.

Start Free TrialView the Runner on GitHub

verified_userFree 30-day trial. No credit card. Cancel any time. Runner is open source.