MCP Server

filestarcli mcp is a local MCP server. It speaks JSON-RPC 2.0 over stdio, so the agent starts it as a program on your computer; there is no network port and no hosted server. Its tools call the same CLI you run by hand, so plans, limits and results are the same.

Start it

Agents start the server themselves. The entry is the same in every client that uses the common mcpServers format:

{
  "mcpServers": {
    "filestar": {
      "command": "filestarcli",
      "args": ["mcp"]
    }
  }
}

With the npm install you can use "command": "npx" and "args": ["-y", "filestar", "mcp"], which keeps working after updates. filestarcli agent install writes the right entry for each agent: see Get Started.

Tools

Tool	What it does
`detect_file`	Tells what kind of file a path is, from its contents, the same as `filestarcli detect`.
`list_skills`	Lists what Filestar can do with the given files, the same as `filestarcli skills -i`.
`describe_skill`	Lists a command's parameters, with their types, defaults and allowed values, the same as `filestarcli skills describe`.
`convert`	Runs a command or a recipe on files, with parameters and an output folder, and returns the files it wrote.
`account_status`	The plan on this computer, the free runs left and a link to upgrade.
`account_upgrade`	Starts the upgrade link and waits until the person has paid, the same as `filestarcli upgrade --wait`.

The server describes each tool's arguments in its tools/list answer, so agents always get the current schema.

Errors

A tool that fails returns a tool result with isError set and the same error object as the CLI's JSON: a code, a message, and where it applies forUser, hint, url and next. The codes are listed in the CLI Reference.

When the free runs are used up (CliAllowanceUsed), the result carries a link for the person. Where the agent supports asking the person to open a link, the server uses it, so the agent shows an "open link" prompt; otherwise the link is in the text.

Who is calling

The server takes the agent's name from the MCP handshake (clientInfo), so agents do not need to pass --user-agent.

Versions

Tool names and argument shapes are a contract: once published, they do not change. New abilities come as new tools or new optional arguments. Every result carries schemaVersion.