OverviewDocsGuides

Agent MCP Reference

Two tool modes, compact JSON results, UI resources, and configuration for the Pharos MCP Server. Pharos is the install client and protocol layer — the catalog is synced from modelcontextprotocol.io / glama.ai / lobehub.com / mcp.so / mcp.directory / Smithery and other registries.

Two tool modes

The server is one process with two surfaces, switched by PHAROS_MCP_APPS. CLI mode is the default. Set PHAROS_MCP_APPS=true for Apps mode (LibreChat and other MCP Apps hosts). pharos_connect and pharos_approve are not MCP tools.

CLI mode (default)

pharos_search, pharos_info, pharos_install, pharos_remove, pharos_list, plus the shared daemon, list_tools, call_tool, and check_approval tools. No iframe.

Apps mode (PHAROS_MCP_APPS=true)

pharos_search_apps, pharos_info_apps, pharos_install_apps, pharos_remove_apps, pharos_list_apps, pharos_publish_apps, plus the same non-A/B tools. HTML is on ui://pharos/… resources.

CLI mode tools

Exposed when PHAROS_MCP_APPS is unset or false. Results are compact JSON.

pharos_search

Search the Pharos registry. Returns compact package JSON ranked by relevance.

Signature
pharos_search(query: str, limit: int = 10, remote_only: bool = False, transport: str = "", registry: str = "", page: int = 1) -> str
Parameters
  • query: str — Natural-language search query.
  • limit: int (default 10, max 50) — Maximum number of results to return.
  • remote_only: bool (default False) — If True, only return remote-transport servers.
  • transport: str — Filter: stdio, http-sse, streamable-http, sse, http.
  • registry: str — Filter: modelcontextprotocol.io, mcp.so, pharos, smithery.
  • page: int (default 1) — 1-based page, mapped to registry cursor offset.
Returns

JSON array of matching servers (id, name, description, version, transport, source_registry).

pharos_info

Fetch details for one package from the registry.

Signature
pharos_info(server_id: str) -> str
Parameters
  • server_id: str — Package ID from search results.
Returns

JSON package metadata from pharos info.

pharos_install

Install an MCP server from the registry. Delegates to the pharos CLI binary when available.

Signature
pharos_install(server_id: str) -> str
Parameters
  • server_id: str — Package ID from search results. Pin a version as name@version.
Returns

JSON install result with status, version, and path or endpoint.

pharos_remove

Uninstall a locally installed MCP server.

Signature
pharos_remove(server_id: str) -> str
Parameters
  • server_id: str — Installed package ID.
Returns

JSON removal result.

pharos_list

List MCP servers installed on this machine.

Signature
pharos_list() -> str
Returns

JSON array of installed packages and status.

Apps mode tools

Exposed when PHAROS_MCP_APPS=true. Use these names in LibreChat. Do not call the CLI-mode pharos_search / pharos_install names in Apps mode.

pharos_search_apps

Search the registry in Apps mode. Tool JSON is compact. Formatted results render from ui://pharos/results/{token} in a sandboxed iframe.

Signature
pharos_search_apps(query: str, limit: int = 10, remote_only: bool = False, transport: str = "", registry: str = "", page: int = 1) -> str
Parameters
  • query: str — Natural-language search query.
  • limit: int (default 10, max 50) — Maximum number of results to return.
  • remote_only: bool (default False) — If True, only return remote-transport servers.
  • transport: str — Filter: stdio, http-sse, streamable-http, sse, http.
  • registry: str — Filter: modelcontextprotocol.io, mcp.so, pharos, smithery.
  • page: int (default 1) — 1-based page, mapped to registry cursor offset.
Returns

JSON with compact hits plus ui_resource_uri such as ui://pharos/results/{token}.

pharos_info_apps

Package details in Apps mode. Detail HTML is a UI resource, not a large html field on the tool result.

Signature
pharos_info_apps(server_id: str) -> str
Parameters
  • server_id: str — Package ID from search results.
Returns

JSON compact metadata plus a ui://pharos/info resource URI.

pharos_install_apps

Start an install that requires a physical Approve/Deny click in the host iframe. Does not install until the user clicks. After the click, poll pharos_check_approval. There is no pharos_approve MCP tool.

Signature
pharos_install_apps(server_id: str, purpose: str = "User request") -> str
Parameters
  • server_id: str — Package ID from search results.
  • purpose: str — Why the install is requested. Shown on the approval card.
Returns

JSON pending approval token and ui://pharos/approval/{token}. Status is not installed until the user clicks Approve.

pharos_remove_apps

Remove an installed server in Apps mode. Requires a confirmation click.

Signature
pharos_remove_apps(server_id: str) -> str
Parameters
  • server_id: str — Installed package ID.
Returns

JSON pending_removal plus a ui://pharos/removal resource.

pharos_list_apps

List installed servers in Apps mode. The list UI is a resource, not inline HTML in the payload.

Signature
pharos_list_apps() -> str
Returns

JSON compact inventory plus a ui://pharos resource URI.

pharos_publish_apps

Publish or update a package through the Apps-mode UI resource. Apps mode only.

Signature
pharos_publish_apps(server_card_path: str = "") -> str
Parameters
  • server_card_path: str — Path to the server card JSON. Empty uses the current directory.
Returns

JSON pending_publish plus a ui://pharos/publish resource URI.

Shared tools

Same non-A/B tools in both modes, including daemon helpers, pharos_list_tools, pharos_call_tool, and pharos_check_approval. The last one is how the agent learns the user clicked Approve or Deny. The click itself never goes through an MCP tool.

pharos_list_tools

List available tools on a connected server.

Signature
pharos_list_tools(server_id: str) -> str
Parameters
  • server_id: str — Server ID of a connected server.
Returns

JSON with server_id, tools, and count.

pharos_call_tool

Call a tool on a connected server and return the result.

Signature
pharos_call_tool(server_id: str, tool_name: str, arguments: dict = None) -> str
Parameters
  • server_id: str — Server ID of a connected server.
  • tool_name: str — Name of the tool to call.
  • arguments: dict (default None) — Arguments to pass to the tool.
Returns

JSON with the tool call result.

pharos_check_approval

Poll whether the user clicked Approve or Deny on the sandboxed approval iframe. Approval itself is POST /approve — a custom HTTP route invisible to the model. The agent never calls an approve tool.

Signature
pharos_check_approval(approval_token: str, wait_seconds: int = 25) -> str
Parameters
  • approval_token: str — Approval token from pharos_install_apps.
  • wait_seconds: int (default 25, max 30) — How long to block waiting for a click.
Returns

JSON status: pending, installed, denied, timeout, or error.

MCP Apps UI resources

Apps mode does not return a large html field on the tool. The host fetches HTML from a ui://pharos/… URI and renders it in a sandboxed iframe (sandbox="allow-scripts", no same-origin).

Results

ui://pharos/results/{token}

text/html;profile=mcp-app

Formatted search results. Host renders this in a sandboxed iframe. Tool JSON stays compact.

Approval

ui://pharos/approval/{token}

text/html;profile=mcp-app

Approve/Deny card for pharos_install_apps. LibreChat uses sandbox="allow-scripts" (no same-origin). The button postMessages the host proxy, which calls POST /approve. Invisible to the model.

OAuth

ui://pharos/oauth/{token}

text/html;profile=mcp-app

OAuth consent card. Still a UI resource. Separate from install approval — the click path for installs is the approval iframe, not an MCP approve tool.

Installation

The Pharos MCP Server ships as a Python package. One command installs the server, the pharos CLI binary, and auto-configures up to 16 detected MCP clients across JSON, YAML, and TOML formats.

pip
pip install pharos-mcp

No API key required for search. The server uses the public Pharos registry endpoint by default.

Configuration

The installer auto-configures detected clients. For Apps mode (LibreChat and other iframe hosts), set PHAROS_MCP_APPS=true in the server env. If you need to add the server manually, use this entry (see the setup guide for platform-specific file locations):

MCP config (Claude Desktop format, Apps mode)
{
  "mcpServers": {
    "pharos": {
      "command": "pharos-mcp",
      "env": {
        "PHAROS_MCP_APPS": "true"
      }
    }
  }
}

Omit env for CLI mode. Most clients (Claude Desktop, Cursor, VS Code, Cline, Roo Code, and others) use "mcpServers" as the top-level key. Some clients use YAML or TOML instead of JSON — the installer handles all three formats automatically. For the full list of 16 supported clients, see the setup guide.