Setup Guide

One command installs the Pharos MCP Server, the pharos CLI binary, and auto-configures up to 16 detected MCP clients.

The one-command install

pip install pharos-mcp gives you three things in one shot:

1.The pharos-mcp server binary (CLI tools by default, or Apps tools when PHAROS_MCP_APPS=true)
2.The pharos CLI binary (bundled, platform-specific) for install operations
3.Auto-configuration of up to 16 detected MCP clients across JSON, YAML, and TOML config formats

Install everything

pip install pharos-mcp

For LibreChat and other MCP Apps hosts, set PHAROS_MCP_APPS=true so the server exposes the _apps tools and UI resources:

Apps mode (LibreChat)

{
  "mcpServers": {
    "pharos": {
      "command": "pharos-mcp",
      "env": {
        "PHAROS_MCP_APPS": "true"
      }
    }
  }
}

What gets auto-configured

The installer detects which MCP clients you have installed and writes the server config automatically. You do not need to edit JSON, YAML, or TOML files by hand for supported clients.

Claude Desktop

JSON

Cursor

JSON

VS Code (Copilot)

JSON

Windsurf

JSON

Cline

JSON

Roo Code

JSON

Continue

JSON

Amazon Q Developer

JSON

Gemini CLI

JSON

Zed

JSON

OpenCode

JSON

Hermes Agent

YAML

LibreChat

JSON

MCPOmni

JSON

GoMCP

JSON

mcp-installer

JSON

Config formats:JSONYAMLTOML· 2 clients are stdio-only (no auto-config)

Already have a config? The installer merges the Pharos entry without overwriting your existing servers. Paths stay inside your home directory (no writing to system locations).

Verify your agent

After installing, restart your agent and try a search. The exact steps depend on which client you use:

Choose your agent

Restart Claude Desktop

Quit and relaunch Claude Desktop so it picks up the new server config that the installer wrote.

Start a new conversation

Open a fresh chat. Claude discovers MCP servers on launch.

Ask Claude to search Pharos

Try: "Search Pharos for filesystem tools". Claude should call pharos_search and return results.

Confirm it works

Ask your agent:

"Search Pharos for filesystem tools"

If you see search results, it is working. CLI mode calls pharos_search. Apps mode (LibreChat, PHAROS_MCP_APPS=true) calls pharos_search_apps and renders results from ui://pharos/results/{token}. From there, ask it to install — in Apps mode you must click Approve in the iframe before the install finishes.

Using Pharos in chat

CLI mode (default) uses pharos_search, pharos_info, pharos_install, pharos_remove, and pharos_list — no iframe. Apps mode (PHAROS_MCP_APPS=true, LibreChat) uses the _apps names. Both modes share daemon / list_tools / call_tool / check_approval. There is no pharos_connect or pharos_approve tool. Below is the Apps-mode chat flow.

pharos_search_apps— discover servers (Apps mode)

Ask your agent in plain language. In LibreChat it calls pharos_search_apps. Tool JSON is compact; the results card is ui://pharos/results/{token}, not a big html field. CLI mode uses pharos_search instead.

You say

"Search Pharos for filesystem tools"

Agent calls pharos_search_apps

pharos_search_apps(query="filesystem", limit=10)

→ Compact JSON + resource:
{
  "results": [
    {
      "id": "filesystem-mcp-server",
      "name": "filesystem-mcp-server",
      "description": "Read/write access to local files and directories.",
      "version": "1.2.0"
    }
  ],
  "ui": "ui://pharos/results/sr-a3b1c2"
}

pharos_install_apps— start install (pending click)

Ask the agent to install a result. Apps mode does not finish the install in the tool call. It returns a pending token and ui://pharos/approval/{token}. CLI mode uses pharos_install and has no iframe.

You say

"Install filesystem-mcp-server"

Agent calls pharos_install_apps

pharos_install_apps(server_id="io.github.malamutemayhem/openmeteo")

→ Returns compact JSON (not installed yet):
{
  "status": "pending_approval",
  "server_id": "io.github.malamutemayhem/openmeteo",
  "approval_token": "ia-openmeteo-1723540800-a3b1c2",
  "ui": "ui://pharos/approval/ia-openmeteo-1723540800-a3b1c2"
}

iframe Approve/Deny+pharos_check_approval— physical click required

The host renders the approval card in a sandboxed iframe (sandbox="allow-scripts", no same-origin). You click Approve or Deny. The button postMessages the host proxy, which calls POST /approve — a custom HTTP route invisible to the model. The agent then polls pharos_check_approval. There is no pharos_approve tool.

You click Approve in the iframe

POST /approve   ← host proxy, not an MCP tool

# Agent polls until the click is recorded
pharos_check_approval(approval_token="ia-openmeteo-1723540800-a3b1c2")

→ pending:
  { "status": "pending" }

→ after click:
  { "status": "installed", "server_id": "io.github.malamutemayhem/openmeteo" }

End-user chatbots require a physical click. The model cannot complete the install by calling an approve tool.

pharos_list_tools+pharos_call_tool— use the server

After approval, the agent can list available tools and call them on your behalf. It chains these naturally — you just ask.

You say

"List the tools on filesystem-mcp-server, then read the README.md"

Agent chains two tool calls

# First, list tools
pharos_list_tools(server_id="io.github.malamutemayhem/openmeteo")
→ { "tools": [{ "name": "read_file", ... }, ...] }

# Then call the one you asked for
pharos_call_tool(
  server_id="io.github.malamutemayhem/openmeteo",
  tool_name="get_weather",
  arguments={"location": "Austin"}
)
→ { "result": "# My Project\n..." }

The key insight: you never left the chat. The agent searched, started an install, waited for your Approve click, then called a tool — all from natural language. That is the Pharos workflow.

Troubleshooting

Agent does not see Pharos tools

Restart the agent. MCP clients discover servers on launch, not at runtime. If that does not work, check the config file was written:

Check the CLI is on your PATH

pharos-mcp --version

pharos-mcp command not found

Your pip bin directory may not be on your PATH. Run python -m site --user-base to find it, then add the bin subdirectory to your PATH.

Next steps

Read the full reference