agentleFS
xaedalonxaedalon/factory-community/skills/factory-mcp-install/SKILL.md

factory-mcp-install

Skill2 starsChanged 53 days agoApache-2.0View on GitHub

Point a coding agent at Factory's MCP server so it can create tasks, start workflows and read runs — choosing between every project on this machine and one repository. Use when the user asks to add Factory to their agent, connect Factory over MCP, or invokes /factory-mcp-install. Not for installing Factory itself (that is `factory-setup`).

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use setup rather than doctor for this.

    line 84
  2. Distinctive:

    Do not carry a list in your head.

    line 107
  3. Very specific:

    Use each client's own command.

    line 121
  4. Very specific:

    If the CLI is reached by path rather than as factory, the command and arguments change and nothing else does:

    line 147
  5. Very specific:

    Check the client you actually configured.

    line 163

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adding Factory to a coding agent

You are pointing a coding agent — Claude Code, the Copilot CLI, or whatever else the person uses — at factory mcp, so that it can resolve the project they are standing in, see what that project can run, create a task, queue it and read what came back.

This is one entry in that agent's own configuration. It installs nothing, downloads nothing and changes nothing about Factory: the server is a command that already exists in their checkout.

Two different things are called a scope around here, and confusing them is expensive. Factory's scopes — project, user, builtin — decide which workflows a project gets, and they live in .xaedalon/.factory. This runbook never touches them. What it writes is a coding agent's own configuration: ~/.claude.json, ~/.copilot/mcp-config.json, or a .mcp.json in one repository. Name the file rather than saying "user level", and you will not confuse them or yourself.


Rule one: ask where, and say what the answer costs

Before writing anything, ask the one question this runbook exists to ask, and lead with the default:

Do you want Factory available to your agent everywhere on this machine, or only in one repository?

Everywhere is what I'd suggest: one entry in your agent's own configuration, and it works in every project — including directories Factory has never heard of, where it will simply say so.

One repository means a .mcp.json file in that directory. Three things follow, and none is a problem as long as you know: it will show up in your git status; Claude Code will hold it at pending approval until you approve it in a session; and it is Claude Code that reads it — the Copilot CLI keeps its servers in your home directory and does not report a repository one. If you use both, the everywhere option is the one that covers both.

Take everywhere if they do not say. Then proceed without further prompting unless something below says to stop.

Rule two: three things are theirs, not yours

  1. Never approve a project-scoped server for them. Claude Code holds a .mcp.json entry at ⏸ Pending approval on purpose — approving a server is agreeing to let something run. Tell them it is waiting, and that clearing it means starting claude in that directory and approving when it asks. This is the same gate as Factory's own security disclaimer, which factory-setup also refuses to accept on anybody's behalf.
  2. Never commit .mcp.json. Writing it into a repository is a change to their repository. Say it is there and let them decide between a commit and a line in .gitignore.
  3. Never install a coding-agent CLI. Configure the ones that are there; report the ones that are not and leave them.

1. Check Factory is here, and how it is reached

command -v factory                  # a global shim, if they linked one
  • It answers → the entry's command is factory, arguments ["mcp"].
  • It does not → find the checkout and use the built CLI by absolute path:
    node <checkout>/apps/cli/dist/bin.js --help | head -1     # must print the usage line
    The entry is then node with ["<checkout>/apps/cli/dist/bin.js", "mcp"]. Discover that path; never type one from this document — a checkout lives wherever they put it, and a wrong absolute path in a client config fails silently at every session start.

If Factory is not installed at all, stop. Say so and point at factory-setup, which is the only copy of those steps. Do not install Factory as part of this.

2. Check a daemon is running, and on which port

factory mcp talks to the daemon and never starts one. Without it every tool answers DAEMON_UNAVAILABLE and tells the agent to ask a person to start it.

factory setup                        # its last line says if the daemon is not answering

Use setup rather than doctor for this. doctor mentions the daemon only when it has other problems to report — with nothing else wrong it prints No problems found. and returns — whereas setup always ends with "The daemon is not running, so this is only what the files can tell you." when it could not reach one. Measured both ways.

The port matters more than it looks. The daemon is at $FACTORY_URL, or 127.0.0.1:$FACTORY_PORT, default 7317 — and an MCP client starts factory mcp with whatever environment it has, not the shell you are standing in.

echo "${FACTORY_URL:-unset}" "${FACTORY_PORT:-unset}"
  • Both unset → the entry needs no environment.
  • Either is set → the entry must carry it, or the server will talk to 7317 and find nothing. Both commands below take it: claude … -e FACTORY_PORT=7417, copilot … --env FACTORY_PORT=7417.

If no daemon is running, you may still write the entry — say that you have, and that nothing will answer until they start one. Do not start a daemon for them as part of this; that is factory-setup's job and its decision.

3. Ask Factory which agents can consume an MCP server

Do not carry a list in your head. Factory knows, because each provider declares it:

factory provider list --json     # "supports" includes "mcp" for the ones that can
factory provider list            # and which of those are installed on this machine

Configure every provider that both declares mcp and is installed. Today that is Claude Code and the Copilot CLI; a provider added later will appear here without this runbook changing.

Say which you found before you write anything.

4. Write the entry

Use each client's own command. Do not hand-edit JSON: the two formats differ in detail — both write a type, and it is stdio for Claude Code and local for Copilot, which also adds a tools list — and each CLI knows its own.

Everywhere on this machine — the default:

claude mcp add --scope user factory -- factory mcp     # ~/.claude.json
copilot mcp add factory -- factory mcp                 # ~/.copilot/mcp-config.json

One repository — run from inside that directory:

cd <the repository>
claude mcp add --scope project factory -- factory mcp  # writes ./.mcp.json

This covers Claude Code and not the Copilot CLI, and that is worth saying out loud rather than discovering later. copilot mcp add writes the user configuration and takes no repository option, and although its help says it loads a workspace .mcp.json or .github/mcp.json, copilot mcp list reports neither — measured, in both that file's shape and Copilot's own. So if they use Copilot too, offer them the choice honestly: the everywhere entry for Copilot alongside the repository one for Claude Code, or Factory simply not being available to Copilot there. Do not write a file and claim it works.

If the CLI is reached by path rather than as factory, the command and arguments change and nothing else does:

claude mcp add --scope user factory -- node <checkout>/apps/cli/dist/bin.js mcp

5. Prove it, twice

First, that the client has it:

claude mcp list         # names "factory"
copilot mcp list        # names "factory", under "User servers:"

Check the client you actually configured. For a .mcp.json entry Claude Code will say ⏸ Pending approval — correct, and not a failure; see rule two. copilot mcp list will not name a repository entry at all, for the reason in step 4.

One failure worth recognising, because it is the commonest and it names itself:

factory: factory mcp - ✘ Failed to connect — ENOENT: Executable not found in $PATH: "factory"

The entry names a command the client cannot find. Go back to step 1 and use the node <checkout>/apps/cli/dist/bin.js form, which does not depend on a shim being on the client's PATH.

Then that the server itself answers, which is the only check that covers the whole path without a client:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}' \
  | factory mcp
# one line of JSON back, with "serverInfo":{"name":"factory",...}

Do not run a bare factory mcp as a check. With a terminal on stdin it prints what it is for and exits; with anything else it waits for a client, which is exactly right and looks like a hang.

6. Hand it over

Report, briefly:

  • what was written, and where — the actual file, named: ~/.claude.json, ~/.copilot/mcp-config.json, or <repo>/.mcp.json
  • that the daemon has to be running, and how they start it
  • for a .mcp.json: that it is in their git status now, that committing it shares Factory with their team, and that Claude Code is holding it at pending approval until they start claude in that directory and say yes
  • what the agent can and cannot do — it can create tasks, queue them and read runs; it cannot accept Factory's security notice and cannot approve anything, both of which stay with them. docs/mcp.md is the short version
  • anything you could not finish, named plainly

Then stop. Do not create a project, do not create a task, and do not queue anything.


If they already have it

claude mcp list naming factory means it is already configured. Say so rather than adding a second entry. Two things are worth checking rather than re-running:

  • the command still resolves — command -v factory, or that the absolute path in the entry exists. A checkout that moved leaves an entry that fails at every session start.
  • the port still matches, if one was pinned.

claude mcp get factory prints the entry as it stands.

What this deliberately does not do

  • It does not start a daemon. factory mcp never starts one either, and for the same reason: two processes opening one database is how a run in flight gets marked failed while its agent is still working.
  • It does not approve anything, accept anything, or run a workflow.
  • It does not edit a client's configuration by hand. If a CLI cannot add the entry, say so and stop rather than writing the file yourself.
  • It does not touch .xaedalon/, the scope chain, or Factory's database. Nothing here is Factory's data.

Reference

docs/mcp.md — what the agent can do once this is done, which project it gets, and what every refusal means. docs/proposals/mcp.md — the standard it is built against. skills/factory-mcp-uninstall/SKILL.md — the other direction.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.