download_for_offlineRails Path

Install mcptask_runner in Your Rails Project

A real Ruby on Rails project. One gem. One command. About two minutes to your first AI agent picking up tasks. Below is the human-friendly walkthrough — no AI-agent prompt, no copy-paste rituals.

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

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.

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 Settings → API Access 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/com.mcptask.runner.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 — example: 0 8 * * 1-5 cd /path/to/your/rails && /usr/local/bin/bundle exec rake mcptask_runner:auto:squash:today >> ~/mcptask.log 2>&1

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

Three commands cover 95% of the time. You 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.

smart_toy

Work the day autonomously

Runs task after task until your daily quota is reached. Squashes and merges each PR on green CI. Stops on errors or when the quota is hit.

bundle exec rake mcptask_runner:auto:squash:today

Designed to be run by the LaunchAgent (or your cron entry) every weekday morning.

visibility

Auto mode, no auto-merge

Same as the auto command, but does NOT squash-merge. You review every PR yourself before it lands.

bundle exec rake mcptask_runner:auto:no_merge:today

Pick this when you want full human-in-the-loop review.

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.

Plain-language definitions

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 Settings → API Access, and click 'Generate 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 → Settings → API Access → Generate 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.

Ask your agent
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.

Ask your agent
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.

Ask your agent
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?

Settings → API Access 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. It runs in your own Rails project directory, with your permissions. It uses a quota system, opens PRs (so every change is reviewable), and stops on error. Nothing is merged without CI green if you picked the auto:squash:today mode.

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.

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.