Agent Integration Guide

How Discovery Works

Discovery is a three-step flow: search → install → connect. The agent never installs anything without the user saying yes.

1. Search. The agent calls the Pharos REST API with a natural-language query. It receives ranked package results and presents a short list to the user inside the chat.
2. Install. Once the user picks a package, the agent runs pharos installand generates the appropriate config block for the user's platform.
3. Connect.The agent reloads its MCP connection. The newly installed server's tools are now available to call in the same session.

Prerequisites

• A Pharos API key — get one at getpharos.dev/v1/.
• An MCP client library — the official Python mcp-sdk or the TypeScript @modelcontextprotocol/sdk.
• Your agent platform's plugin or extension system, so you can write config and reload MCP connections at runtime.

Search API

Discovery starts with a plain HTTP GET. Pass the user's query in q and cap the result count with limit. Authenticate with the API key in a Bearer header.

GET https://getpharos.dev/v1/search?q=filesystem&limit=5
Authorization: Bearer ***

[
  {
    "name": "filesystem-mcp-server",
    "description": "Read/write access to local files and directories.",
    "version": "1.2.0",
    "downloads": 15320,
    "registry": "npm",
    "verified": true,
    "hosted": false
  },
  {
    "name": "safe-fs",
    "description": "Sandboxed filesystem access for untrusted agents.",
    "version": "0.4.1",
    "downloads": 842,
    "registry": "pypi",
    "verified": false,
    "hosted": true
  }
]

Install Flow

Once the user picks a package, shell out to the Pharos CLI to install it. The CLI handles download, hash verification, and returning the command and args you need for config.

import subprocess
import json

def install_mcp_server(package_name: str) -> dict:
    """Install an MCP server via Pharos CLI."""
    result = subprocess.run(
        ["pharos", "install", package_name],
        capture_output=True,
        text=True
    )
    if result.returncode != 0:
        raise RuntimeError(f"Install failed: {result.stderr}")
    return json.loads(result.stdout)

The returned object contains command and args — feed those into the platform config in the next step.

Generate Platform Config

Each agent platform reads MCP servers from a different config file with a slightly different shape. Detect which platform the user is on and write the matching block. The examples below all consume the install_result from the previous step.

config = {
    "mcpServers": {
        package_name: {
            "command": install_result["command"],
            "args": install_result["args"]
        }
    }
}
# Write to claude_desktop_config.json

Consent and Safety

The agent should alwaysask the user before installing a package. Present enough information for an informed decision: package name, version, download count, what tools it exposes, and whether it's verified.

I found filesystem-mcp-server (v1.2.0, 15k downloads).
It provides file read/write tools. Verified package.

Install?

After install, run pharos audit to check the new server for known security advisories. If the audit reports issues, surface them to the user before connecting.

pharos audit --format json

Inline OAuth

Some MCP servers need OAuth — GitHub, Slack, and Notion servers are common examples. The agent should handle the flow inline so the user never leaves the chat:

1. Detect that the server requires OAuth from the package metadata.
2. Start the flow with pharos auth <package>.
3. Present the returned auth URL to the user.
4. Capture the callback and store the token.

def handle_oauth(package_name: str, user_id: str) -> str:
    """Start OAuth flow for a package that requires it."""
    result = subprocess.run(
        ["pharos", "auth", package_name, "--user", user_id],
        capture_output=True,
        text=True
    )
    auth_url = json.loads(result.stdout)["auth_url"]
    return auth_url

Full Example

A complete agent-side handler that ties the pieces together: the user asks for a capability, the agent searches Pharos, presents results, installs the chosen package, generates config, audits, and reloads MCP.

import subprocess
import json

def discover_and_install(query: str, platform: str, user_id: str):
    # Step 1: Search
    results = subprocess.run(
        ["pharos", "search", query, "--format", "json"],
        capture_output=True, text=True
    )
    packages = json.loads(results.stdout)[:5]

    # Step 2: Present to user (your UI layer)
    selected = present_options(packages)
    if not selected:
        return None

    # Step 3: Confirm with user
    if not confirm_install(selected):
        return None

    # Step 4: Install
    subprocess.run(["pharos", "install", selected["name"]], check=True)

    # Step 5: Handle OAuth if needed
    if selected.get("requires_oauth"):
        auth_url = handle_oauth(selected["name"], user_id)
        present_auth_url(auth_url)

    # Step 6: Generate config for user's platform
    config = generate_config(selected, platform)
    write_config(config, platform)

    # Step 7: Audit
    audit = subprocess.run(["pharos", "audit", "--format", "json"],
                          capture_output=True, text=True)

    # Step 8: Reload
    reload_mcp()

    return selected

present_options, confirm_install, generate_config, write_config, and reload_mcpare platform-specific hooks you implement in your agent's UI and plugin layer.

Next Steps